diff --git a/deploy/env/health-patrol.env.example b/deploy/env/health-patrol.env.example
new file mode 100644
index 000000000..b1b9799e5
--- /dev/null
+++ b/deploy/env/health-patrol.env.example
@@ -0,0 +1,19 @@
+# 复制到 /etc/genarrative/health-patrol.env 后按生产环境调整。
+# 默认不启用 Pingora shadow 巡检；只有同时配置 base URL 与 probe token 才会检查。
+
+GENARRATIVE_HEALTH_PATROL_API_BASE_URL=http://127.0.0.1:8082
+GENARRATIVE_HEALTH_PATROL_SPACETIME_BASE_URL=http://127.0.0.1:3101
+GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=http://127.0.0.1
+# 默认公网入口仍按 Nginx 巡检；Pingora 直连切换后改为 pingora-direct。
+GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx
+# 本机打 127.0.0.1 时可填正式域名，确保命中正确 vhost / 证书语义。
+GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=
+GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS=5000
+GENARRATIVE_HEALTH_PATROL_SLOW_MS=3000
+GENARRATIVE_HEALTH_PATROL_FAIL_ON_WARNING=false
+GENARRATIVE_HEALTH_PATROL_SKIP_JOURNAL=false
+GENARRATIVE_HEALTH_PATROL_WEBHOOK_URL=
+
+# Pingora 影子网关巡检；probe token 应与 /etc/genarrative/pingora-gateway.env 保持一致。
+GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL=
+GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN=
diff --git a/deploy/env/pingora-canary-live.env.example b/deploy/env/pingora-canary-live.env.example
new file mode 100644
index 000000000..9cbff3728
--- /dev/null
+++ b/deploy/env/pingora-canary-live.env.example
@@ -0,0 +1,35 @@
+# 复制到本机临时 shell 或 CI secret 环境后运行：
+# npm run check:pingora-canary-live
+# 该检查只读访问已经人工启用的 Nginx -> Pingora canary，不会修改 Nginx。
+
+# 例如 http://127.0.0.1 或 https://genarrative.world。
+GENARRATIVE_PINGORA_CANARY_BASE_URL=http://127.0.0.1
+
+# 默认前缀必须和 deploy/nginx/snippets/genarrative-pingora-canary.conf 保持一致。
+GENARRATIVE_PINGORA_CANARY_PREFIX=/__genarrative_pingora_canary
+
+# 可选：真实路径 canary 使用 deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf。
+# 启用后运行：
+# GENARRATIVE_PINGORA_CANARY_MODE=realpath \
+# GENARRATIVE_PINGORA_CANARY_BASE_URL=${GENARRATIVE_PINGORA_REALPATH_CANARY_BASE_URL} \
+# npm run check:pingora-canary-live
+# 或使用 release readiness:
+# npm run check:pingora-release-readiness -- --require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名>
+GENARRATIVE_PINGORA_CANARY_MODE=prefix
+GENARRATIVE_PINGORA_REALPATH_CANARY_BASE_URL=http://127.0.0.1:18083
+GENARRATIVE_PINGORA_REALPATH_CANARY_HOST=
+
+# 本机直连 127.0.0.1 时必须设置正式域名，避免只命中 Nginx 默认 vhost；release readiness --require-live 必须提供。只填域名或 host:port，不要填 https:// URL。
+GENARRATIVE_PINGORA_CANARY_HOST=
+
+GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS=5000
+
+# live smoke 后必须继续按 request_id 对照 Nginx handoff access log 与 Pingora access log。
+GENARRATIVE_PINGORA_CANARY_NGINX_ACCESS_LOG=/var/log/nginx/genarrative.access.log
+GENARRATIVE_PINGORA_CANARY_PINGORA_ACCESS_LOG=/var/log/genarrative/pingora-gateway.access.log
+GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES=2000
+
+# 真实路径 canary 使用独立 Nginx access log，避免和生产真实用户请求混在一起。
+GENARRATIVE_PINGORA_REALPATH_CANARY_NGINX_ACCESS_LOG=/var/log/nginx/genarrative-pingora-realpath-canary.access.log
+GENARRATIVE_PINGORA_REALPATH_CANARY_PINGORA_ACCESS_LOG=/var/log/genarrative/pingora-gateway.access.log
+GENARRATIVE_PINGORA_REALPATH_CANARY_ACCESS_LOG_SINCE_LINES=2000
diff --git a/deploy/env/pingora-direct-live.env.example b/deploy/env/pingora-direct-live.env.example
new file mode 100644
index 000000000..b3d04c609
--- /dev/null
+++ b/deploy/env/pingora-direct-live.env.example
@@ -0,0 +1,68 @@
+# 复制到本机临时 shell 或 CI secret 环境后运行：
+# npm run check:pingora-direct-live
+# 该检查只读访问已经显式配置 TLS_LISTEN / HTTP_REDIRECT_LISTEN 的 pingora-gateway。
+# 切换窗口建议先运行：
+# npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free
+# release readiness --require-direct 必须确认 TLS/HTTP redirect 端口已释放，复核 health patrol env 已切到 direct 模式，并提供 Pingora access log 路径用于 request_id 落盘校验。
+# 直连启用前：
+# /opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status
+# /opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log
+# 启用脚本会先执行 current release 自审，确认 pingora-gateway 可执行且 systemd ExecStart 指向 current release；自审失败时不会安装 direct-entry drop-in。
+# 自审和 preflight 都通过后，启用脚本才会安装 drop-in、重启 Pingora、执行 direct live smoke，并强制 WSS subscribe 返回 101，同时用生成的 request_id 反查 Pingora access log。
+# 直连接管后同步更新 /etc/genarrative/health-patrol.env：
+# GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct
+# GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://127.0.0.1
+# GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>
+# 然后用 node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs 复核。
+# 直连验证失败时：
+# /opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名>
+# 回退脚本会先执行 nginx -t，reload 后确认 nginx.service 仍为 active，并用 smoke URL 证明 Nginx 入口可访问。
+# 回退后把 GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE 改回 nginx。
+
+# 例如 https://127.0.0.1 或 https://genarrative.world。
+GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL=https://127.0.0.1
+
+# 单独 direct live 可选；release readiness --require-direct 必须提供，用于校验 HTTP 入口 301 到 HTTPS，并确认 ACME challenge 没被重定向吞掉。
+GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL=http://127.0.0.1
+
+# 本机直连 127.0.0.1 时必须设置正式域名；direct live 会同时用作 Host header 和 TLS SNI。release readiness --require-direct 必须提供。只填域名或 host:port，不要填 https:// URL。
+GENARRATIVE_PINGORA_DIRECT_HOST=
+
+# 单独 direct live 可选；release readiness --require-direct 必须提供，用于显式校验 HTTP redirect Location 的 host。只填域名或 host:port。
+GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST=
+
+# 可选：高端口 rehearsal 访问 127.0.0.1:18443、但期望 Location 指向正式域名默认 HTTPS 入口时设置；只能填 https:// base URL，不要带路径、查询或片段。
+GENARRATIVE_PINGORA_DIRECT_REDIRECT_BASE_URL=
+
+# 可选：配置后会额外检查 /__genarrative_pingora/healthz 内部探针。
+GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN=
+
+# direct live 默认会对 wss://<HTTPS>/v1/database/<database>/subscribe 做 SpacetimeDB 握手检查；release readiness --require-direct 必须按目标环境显式设置。
+GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE=genarrative-prod
+
+# release readiness --require-direct 必须显式提供；direct live 会用每个请求生成的 X-Request-Id 反查 Pingora access log，证明直连流量真实进入 Pingora。
+GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG=/var/log/genarrative/pingora-gateway.access.log
+GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES=2000
+
+# direct live 单独运行时可设 true，要求 WSS subscribe 必须返回 101；release readiness --require-direct 会自动强制该口径。
+GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE=true
+
+# 只允许单独 direct live 临时排障时跳过 WSS；release readiness --require-direct 会直接拒绝，正式切流必须保持 false。
+GENARRATIVE_PINGORA_DIRECT_SKIP_WSS=false
+
+# 仅本机自签证书 smoke 使用；生产必须保持 false。
+GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS=false
+
+GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS=5000
+
+# release readiness --require-direct 会先跑 direct-entry preflight；提供 env 文件后会强制检查 TLS/redirect/cert/key 配置。
+GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE=/etc/genarrative/pingora-gateway.env
+GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT=true
+GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE=true
+GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE=true
+GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE=true
+GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE=true
+GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE=true
+
+# release readiness --require-direct 必须复核健康巡检 env，避免切直连后巡检仍按 Nginx 模式误报。
+GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE=/etc/genarrative/health-patrol.env
diff --git a/deploy/logrotate/genarrative-pingora-gateway b/deploy/logrotate/genarrative-pingora-gateway
new file mode 100644
index 000000000..660bbd380
--- /dev/null
+++ b/deploy/logrotate/genarrative-pingora-gateway
@@ -0,0 +1,10 @@
+/var/log/genarrative/pingora-gateway.access.log {
+    daily
+    rotate 14
+    missingok
+    notifempty
+    compress
+    delaycompress
+    copytruncate
+    create 0640 genarrative genarrative
+}
diff --git a/deploy/nginx/README.md b/deploy/nginx/README.md
index 054734dee..98cddbc0d 100644
--- a/deploy/nginx/README.md
+++ b/deploy/nginx/README.md
@@ -13,15 +13,69 @@
 - `deploy/nginx/genarrative.conf` 与 `deploy/nginx/genarrative-dev-http.conf` 默认开启 gzip。
 - 覆盖 `application/json`，用于降低 `/api/runtime/*/gallery` 这类 JSON 列表接口的公网带宽占用。
 - 当前推荐等级为 `gzip_comp_level 5`，兼顾 2C/2G 服务器 CPU 与压缩收益。
+- Pingora 影子网关已通过 `GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED=true`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5` 与 `GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024` 承接 gzip parity；网关会把压缩算法收敛到 gzip allowlist，并按 `gzip_min_length 1024` 避免压缩小响应，同时沿用 Nginx `gzip_types` 边界不压缩图片资源。改动后必须运行 `npm run check:pingora-gateway-smoke` 验证小响应不压缩、图片资源不压缩，以及 `Accept-Encoding: gzip` 和 `Accept-Encoding: br, gzip` 的大响应都返回 gzip。
 
 ## Brotli
 
 - Brotli 只在目标服务器 Nginx 接受 brotli 指令时开启。
+- Pingora 当前正式化口径固定为 gzip-only，不承接 Brotli；做 Nginx -> Pingora canary 时，Brotli 仍由 Nginx 或更前置代理决定是否启用。直连 Pingora 时，不把 Brotli parity 作为切换门禁，避免使用 Pingora 0.8.1 里尚未通过可解压端到端验证的 Brotli compressor 路径。
 - Ubuntu / apt 系统的 `Genarrative-Server-Provision` 会安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`；非 apt 系统暂不自动安装，仍按下面的能力探测结果决定是否启用。
 - Provision 脚本通过临时配置执行 `nginx -t` 做能力探测；探测配置会先 `include /etc/nginx/modules-enabled/*.conf`，避免 Ubuntu 动态模块已安装但测试配置未加载模块导致误判。可用时把模板中的 `# __GENARRATIVE_BROTLI_DIRECTIVES__` 替换为 brotli 指令，不可用时保留注释说明。
 - 不要直接在静态模板里无条件写 `brotli on;`，否则没有 brotli 模块的服务器会 `nginx -t` 失败并回滚。
 - 不要用 `nginx -V | grep brotli` 判断 brotli 是否可用；Ubuntu apt 安装的 brotli 是动态模块，不会出现在普通编译参数里。应检查包、`/etc/nginx/modules-enabled/` 的 `load_module` 配置，或用包含 `include /etc/nginx/modules-enabled/*.conf` 的临时配置执行 `nginx -t`。
 
+## Pingora upstream timeouts
+
+- Pingora 影子网关已显式配置上游连接 / 读 / 写 timeout，避免正式 canary 时依赖 Pingora 默认值。
+- 默认连接超时为 `3000ms`；没有 Nginx 显式长超时的代理路由读取超时为 `60s`。
+- 通用 `/api`、公开列表 / 详情和 SpacetimeDB subscribe 读取超时为 `3600s`，写上游超时为 `3600s`，对齐当前 Nginx `proxy_read_timeout` / `proxy_send_timeout` 口径。
+- 超时会返回 JSON `504 GATEWAY_UPSTREAM_TIMEOUT`，由 `npm run check:pingora-gateway-smoke` 覆盖。
+
+## Pingora static cache policy
+
+- Pingora 直连静态响应会显式写入 `Cache-Control`，避免公网入口切换后 HTML 入口页或 Vite 指纹资源依赖框架默认头。
+- 默认 `GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL=no-cache`，覆盖 `index.html`、`admin/index.html`、目录 index 和 SPA fallback。
+- 默认 `GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL=public, max-age=31536000, immutable`，只覆盖 `/assets/*` 与 `/admin/assets/*` 中带 Vite 指纹文件名的资源；非指纹静态和 ACME challenge 默认 `GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL=no-cache`。
+- Pingora 静态响应同时写入弱 `ETag`、`Last-Modified` 与 `Accept-Ranges: bytes`，并对 `If-None-Match` / `If-Modified-Since` 返回 `304`；这层只负责浏览器协商缓存，不改变上面的 `Cache-Control` 分档。
+- Pingora 静态文件支持单段 `Range: bytes=`：合法范围返回 `206` 与 `Content-Range`，越界范围返回 `416` 与 `Content-Range: bytes */<len>`，`HEAD + Range` 只返回头。多段 range 暂按完整文件返回，不启用 multipart 响应。`If-Range` 日期匹配时继续返回局部内容，日期旧于文件或弱 ETag 校验器时回完整 `200`。`206` / `304` / `416` 均不做 gzip 压缩，避免局部内容语义和 `Content-Range` 漂移。
+- Pingora 静态路由只允许 `GET` / `HEAD`。非读取方法命中静态候选时返回 `405` 与 `Allow: GET, HEAD`；缺失文件仍返回 `404`，避免错误客户端把静态入口当作可写接口。
+- `npm run check:pingora-gateway-smoke` 会用固定 `X-Request-Id` 对账静态 `304` / `405` / `206` / `416` 的 Pingora access log 行，并同时校验 method / path / status；该 smoke 还会让 direct live 自动发现首页里的普通静态资源和 Vite 指纹资源，确认指纹资源 GET / HEAD / `If-None-Match` 304 / `Range: bytes=0-0` 以及 `public, max-age=31536000, immutable` 缓存头，确保本地静态响应状态和指纹 chunk 长缓存都可进入直连切换证据链。direct live JSON 只给静态 GET / HEAD / 304 / Range 写入白名单 `headers`，包括 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`，便于证据包归档后复盘静态缓存与 Range 响应头。
+
+## Pingora TLS / redirect
+
+- Pingora 网关默认仍只监听本机 shadow 端口，不绑定公网 `80/443`。
+- 需要评估直连入口时，显式配置 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` 和 `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`；网关只读取现有证书文件，不负责 Certbot / ACME 自动续期。
+- 需要 HTTP 到 HTTPS 跳转时，再显式配置 `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`；该入口除 `/.well-known/acme-challenge/*` 外统一 301 到 HTTPS，ACME challenge 仍从 `GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT` 精确读取。
+- 同一公网 IP 上还承载 `git.genarrative.world` 时，直连前必须配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world` 与 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`，让命中 Gitea Host 的请求整站转发到 Gitea；该路由不走应用维护页、API body limit 或网关接流保护，避免影响 git clone / push。当前 Pingora TLS listener 只加载一组 cert/key；如果直连 443 同时服务 `dev.genarrative.world` 和 `git.genarrative.world`，证书必须同时覆盖两个域名，不能使用只有单域名 SAN 的证书。
+- API release 必须把 `api-server.sha256`、可选 `pingora-gateway.sha256`、`scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs`、`scripts/check-pingora-canary-access-log-parity.mjs`、`scripts/ops/pingora-current-release-audit.mjs`、`scripts/ops/pingora-direct-rehearsal-status.mjs`、`scripts/ops/pingora-cutover-status-snapshot.mjs`、`scripts/ops/pingora-cutover-evidence-bundle.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/check-production-health-patrol-env.mjs`、`scripts/deploy/pingora-health-patrol-env-switch.mjs`、`scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`scripts/deploy/pingora-tls-cert-sync.mjs`、`deploy/systemd/`、`deploy/env/` 和 `deploy/pingora/` 一起复制到 `/opt/genarrative/current`；current release 自审、直连彩排状态、直连启用、health patrol env 切换、Pingora gateway env shadow 切换、TLS 证书同步、canary live、access log 对账、cutover 状态快照和证据包脚本都从 current release 推导依赖路径，切换窗口不得依赖 Jenkins 工作区或目标机源码 checkout。
+- 目标机如果使用 Certbot / Let’s Encrypt 证书，不要直接放宽 `/etc/letsencrypt/live` 或 `archive` 的目录 / 私钥权限。先用随包脚本把 root 可读的 live symlink 解析并复制到 Pingora 私有目录，例如 `sudo -n node -- /opt/genarrative/current/scripts/deploy/pingora-tls-cert-sync.mjs --apply --source-cert-file /etc/letsencrypt/live/<域名>/fullchain.pem --source-key-file /etc/letsencrypt/live/<域名>/privkey.pem --target-dir /etc/genarrative/pingora-tls/<域名>`；脚本默认 dry-run，`--apply` 才原子写入 `fullchain.pem` / `privkey.pem`，目标目录默认 `root:genarrative 0750`，文件默认 `root:genarrative 0640`，并复核 `genarrative` 服务用户可读。随后把 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE` 指向 `/etc/genarrative/pingora-tls/<域名>/` 下的副本。
+- 默认 systemd service 以 `genarrative` 非 root 用户运行，不具备绑定 `80/443` 的能力。Server-Provision 只安装 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 作为人工启用模板；切直连低端口时必须先确认 `genarrative` 可读证书文件、Nginx 已释放 `80/443`，再执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；脚本会先执行随包 current release 自审，确认 `pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release，失败时不会安装 drop-in。自审通过后才安装 drop-in、`systemctl daemon-reload` 并重启 Pingora；脚本会用 `systemctl cat` 确认 `CAP_NET_BIND_SERVICE` drop-in 已进入 systemd 最终配置，用 `systemctl show ... ExecStart` 确认最终 service 指向随包主 service 模板中的 current release `pingora-gateway`，用 `systemctl is-active` 确认 Pingora active，并执行 direct live smoke，强制覆盖 HTTPS / HTTP redirect / ACME / WSS 101 和 Pingora access log request_id 落盘。
+- `npm run check:pingora-gateway-smoke` 会用临时自签证书覆盖 TLS 直连、HTTP redirect 和 WSS subscribe 行为；正式公网切换前仍必须先走 Nginx canary 和 release readiness 门禁。
+- 目标机直连入口启用前先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，证明 TLS 文件、service env、current release 二进制和低端口释放都满足切流条件；启用后再运行 `npm run check:pingora-direct-live`，检查 HTTPS 根路径、HTTP/2 ALPN、代表性 API、SpacetimeDB identity、WSS subscribe 握手、generated 拒绝、公开 `/healthz` 拒绝、可选 shadow probe，以及 HTTP 301 / ACME challenge；真实 SpacetimeDB 对 `GET /v1/identity` 返回 `405 Method Not Allowed` 属于可接受语义，direct live 只把它作为路径转发代表，不要求该 GET 创建 identity；release readiness 可用 `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable` 强制纳入同一条启用后门禁，漏掉 direct HTTP base URL、正式域名 Host/SNI、redirect Location host、目标 SpacetimeDB 库、Pingora access log request_id 落盘、health patrol env direct 模式复核、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户 / systemd 服务用户证书可读检查或 service 二进制可执行检查都会直接失败；启用后 `--require-direct` 复核不再要求端口空闲，因为此时 `80/443` 应由 Pingora 占用。高端口 rehearsal 如果通过 `https://127.0.0.1:18443` 打入、但 Pingora 应返回正式域名默认 HTTPS Location，可额外传 `--direct-redirect-base-url https://<域名>`；`--direct-redirect-host` 仍必须保留，用于直连切换 Host 一致性约束。
+- direct live 在 HTTPS 根路径返回 `200` 且 HTML 中发现 `/assets/` 或 `/admin/assets/` 引用时，会自动请求该静态资源，确认 `Cache-Control`、`ETag`、`Last-Modified`、`Accept-Ranges: bytes`、`HEAD` 头响应、`If-None-Match` / `If-Modified-Since` 的 `304` 响应和 `Range: bytes=0-0` 的 `206 + Content-Range` 响应，并纳入 Pingora access log method/path/status 对账；若首页引用 Vite 指纹资源，还会额外确认 `Cache-Control: public, max-age=31536000, immutable` 以及指纹资源 GET / HEAD / 304 / Range access log 证据。维护模式、非 HTML 或发布包首页没有资产引用时该项标记为 skipped，不阻断维护窗口。
+- 直连启用前先 dry-run `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status`；验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`，脚本会先运行 `nginx -t`，通过后移除 direct-entry drop-in、重启 Pingora，用 `systemctl cat` 确认 `CAP_NET_BIND_SERVICE` 已从 systemd 最终配置中移除，用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，并 reload Nginx、确认 Nginx service 仍为 `active`，最后用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时还会要求响应体包含该片段。回退 smoke 的 URL 与 body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`；若 smoke URL 打本机地址，再显式追加 `--nginx-smoke-host <域名>` 避免命中默认 vhost。仓库工作区可用 `npm run deploy:pingora-direct-enable -- --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log` 和 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`。两个脚本默认 dry-run；启用脚本 `--apply` 必须先通过 current release 自审，并带 env、证书可读、service EnvironmentFile 一致性、服务用户证书可读、service 二进制可执行、端口释放预检、direct live 参数和 Pingora access log 参数，回退脚本 `--apply` 必须带 `--reload-nginx` 和 `--nginx-smoke-url`；如果 health patrol env 已预先切回 Nginx，也可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 让回退脚本在 Nginx smoke 后复核 `gateway mode=nginx` 且 public base URL / Host 已恢复，若切换前 Nginx 巡检本来需要 Host 覆盖，则把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`；如果还要同时证明 shadow 高端口仍健康，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应包含 `gateway=pingora-shadow`。本机 `npm run check:pingora-direct-enable` / `npm run check:pingora-direct-rollback` 会验证 dry-run 不会安装或删除临时 drop-in、current release 自审失败时启用脚本不会安装 drop-in，并展示启用 / 回退后的 systemd 最终配置核验、ExecStart 指向核验、Pingora active 核验、direct live smoke、Nginx 语法检查、reload 状态核验、Nginx smoke 及响应体片段核验、可选 health patrol env 复核和可选 shadow probe 复核。
+- rollback apply 前必须先执行 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env`，把 active Pingora env 恢复为 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081`，并清空 `TLS_LISTEN`、`HTTP_REDIRECT_LISTEN`、`TLS_CERT_FILE` 和 `TLS_KEY_FILE`；只移除 systemd direct-entry drop-in 而不恢复 env，会让回退后的 Pingora shadow 继续按 direct 低端口或半 TLS 配置启动。
+- `npm run check:pingora-current-release-audit` 会烟测 current release 自审脚本；正式直连 runbook 会先执行 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`，只读确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、`release-manifest.api-server.json` 已登记 `pingora-gateway`、`pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release。
+- `npm run check:pingora-cutover-status-snapshot` 会烟测状态快照脚本，`npm run check:pingora-cutover-evidence-bundle` 会烟测证据包脚本；正式切换窗口与 release readiness 使用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 归档切换前 / 启用后 / 回退后三个阶段的 `manifest.json`、`snapshot.json`、stdout / stderr 和命令记录。直连 runbook 的三个证据包阶段都会向状态快照透传 `--require-pingora-gateway`，在 `checks.current-release-audit` 中保存 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果；启用后证据包还会通过 `--run-direct-live` 保存 `direct-live.json`、direct live stdout / stderr、命令记录、Pingora access log `request_id` 反查结果，以及静态响应头白名单证据。`post-enable` 证据包必须传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包必须传 `--expected-pingora-env-mode shadow`。`manifest.summary.directLiveAccessLog` 会提升 checked / matched / missing / mismatch 对账摘要，`manifest.summary.directLiveStaticHeaders` 会提升普通静态和 Vite 指纹静态的缓存头、校验头、Range `Content-Range` 和 304 状态摘要，`manifest.summary.pingoraEnvShadow` 会提升 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode` 和 `shadowReady`，便于值班人员不打开 `direct-live.json` 或 `snapshot.json` 也能先判断证据是否完整；如果 direct live 已输出静态资产结果但摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，证据包会记为 `CRITICAL`。最终总审计还会带 `--require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-phase-pingora-env-shadow post-rollback`，防止缺少 access log 对账摘要、静态头摘要或回退后 shadow env 摘要的旧证据包混入正式归档。快照脚本只读采集状态，证据包脚本只写指定证据目录，不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora。
+- 最终证据根目录总审计 JSON 先看 `summary.status`、`summary.failedItems[]` 和 `summary.directLiveEvidence[]`：失败时这里会直接指出阶段 / 命令 / 根目录问题，以及 `post-enable` access log 或静态头摘要的短 reason；`phases[]`、`commands[]` 和 `timeline` 继续作为完整机器归档。
+- 最终证据根目录总审计必须同时带五条 `--require-command-executable`：`enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs` 和 `rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，避免只证明有命令证据，却没有证明真实执行的是 current release 随包切换脚本。
+- `npm run check:production-api-release` 会动态生成 API release，并检查发布包 README 与随包 `scripts/check-pingora-release-readiness.mjs --dry-run-cutover` 输出的最终总审计步骤都保留上述五条 `--require-command-executable` 要求，避免源码文档正确但发布包操作口径漂移。
+- 直连接管后用 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply --env-file /etc/genarrative/health-patrol.env --gateway-mode pingora-direct --public-base-url <直连HTTPS入口> --public-host <域名>` 切换 health patrol env；该脚本只改 gateway mode、public base URL 和 public Host，并先用临时目标 env 调用随包 `check-production-health-patrol-env.mjs` 复核，复核通过后才原子替换真实 env，复核失败不会落盘。回退到 Nginx 前用同一脚本改回 `--gateway-mode nginx --public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检不需要 Host 覆盖则传 `--clear-public-host`，需要 Host 覆盖则传 `--public-host <切换前Host>`；随后 rollback 脚本和独立 env 复核会再次阻断 public base URL / Host 漂移。`plan:pingora-direct-cutover` 会在 JSON runbook 中列出 direct / nginx 两个方向的 env 切换脚本和 env 复核步骤，并先输出 Host 与回退巡检入口确认；正式切换 runbook 会拒绝 `--direct-redirect-host` 或 `--rollback-nginx-smoke-host` 与 `--direct-host` 使用不同 hostname，且必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退计划把现场巡检入口覆盖成仓库默认值。若切换计划希望回退后同时证明 Pingora shadow 高端口仍健康，可给 runbook 追加 `--rollback-pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --rollback-pingora-shadow-probe-token <token>`；JSON 输出会隐藏 token 原文，并把对应参数传给 rollback dry-run / apply 步骤。
+
+## Pingora canary
+
+- `deploy/nginx/snippets/genarrative-pingora-canary.conf` 是默认不启用的人工前缀 canary 入口，只在需要验证 Nginx -> Pingora handoff 时临时 include。它使用 `/__genarrative_pingora_canary/` 前缀改写后转发到 `127.0.0.1:18081`，并返回 `X-Genarrative-Nginx-Handoff: pingora-canary`。
+- `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 是前缀 canary 之后、direct 直连之前的真实路径 canary。它只能在 Nginx `http` 上下文人工 include，默认监听 `127.0.0.1:18083`，覆盖 `/api/creation-entry/config`、`/v1/identity`、`/v1/database/<db>/subscribe`、`/assets/app.js` 和拒绝入口，并写入独立 `/var/log/nginx/genarrative-pingora-realpath-canary.access.log`；不要把它 include 到生产 `443` server 内作为 location 覆盖。
+- 真实路径 canary 片段使用 `access_log ... genarrative_upstream`，如果以独立文件放入 `/etc/nginx/conf.d/`，文件加载顺序必须晚于定义 `log_format genarrative_upstream` 的主站配置。当前目标机可使用 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`；若站点把 `log_format` 移到全局 Nginx 配置，则需确保它仍在所有 `conf.d` server include 之前加载。启用前必须先跑 `nginx -t`，不要用会早于 `genarrative.conf` 加载的文件名。
+- 启用 Nginx canary 前，目标机必须已经有持久 `genarrative-pingora-gateway.service` 运行在 `127.0.0.1:18081`，且带真实 `api-server`、SpacetimeDB、静态目录和 `/var/log/genarrative/pingora-gateway.access.log` 完成本机 shadow 验收；不要从一次性 `/tmp` 网关进程直接切到 Nginx handoff。
+- 启用前必须运行 `npm run check:nginx-pingora-canary`；目标 agent 有 Nginx 时运行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`，同时做两个 snippet 的静态护栏和真实 `nginx -t`。本机或 CI 可运行 `npm run check:pingora-canary-docker`，用 Docker Nginx、真实 Pingora 和 mock 上游复现前缀 canary 与真实路径 canary 两条 handoff 链路。
+- 前缀 canary reload 后运行 `GENARRATIVE_PINGORA_CANARY_BASE_URL=http://127.0.0.1 GENARRATIVE_PINGORA_CANARY_HOST=<域名> npm run check:pingora-canary-live`，再用 `scripts/check-pingora-canary-access-log-parity.mjs` 对账 `/var/log/nginx/genarrative.access.log` 与 `/var/log/genarrative/pingora-gateway.access.log`。
+- 真实路径 canary 不再手工编辑 `/etc/nginx/conf.d/`。目标机从 current release 执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083`；脚本会渲染到 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`，保持晚于主站 `log_format genarrative_upstream` 加载，执行 `nginx -t`、reload Nginx，并默认运行 realpath live smoke。`nginx -t`、reload 或 live smoke 任一失败都会恢复写入前配置。关闭时执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply`，脚本会删除该 `zz-...` 文件，执行 `nginx -t` 和 reload，失败时恢复删除前配置。
+- `npm run check:pingora-release-readiness` 默认包含 `npm run check:pingora-realpath-canary-toggle`，用临时 Nginx 目录和 fake `nginx` / `systemctl` / live smoke 验证 realpath canary 启停脚本默认 dry-run、apply 写入、失败回滚和 disable 恢复逻辑；不再把这条脚本护栏留成单独可选项。
+- 真实路径 canary reload 后可再次运行 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`，再运行 `node -- /opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_realpath_canary/healthz --path /api/creation-entry/config --path /v1/identity --path /assets/app.js`。真实路径模式除 healthz 探针外要求 Nginx path 与 Pingora path 完全一致。
+- 正式切换前在源码 checkout / CI / 构建环境跑聚合门禁，并按目标机已启用的 canary 入口选择参数：前缀 canary 已启用时使用 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；真实路径 canary 已启用时追加或单独使用 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。如果现场只启用了真实路径 canary，不要同时传 `--require-live`。
+- 目标机 `/opt/genarrative/current` 只能跑随包 runtime-only 门禁，并同样按现场已启用入口选择：前缀 canary 用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；真实路径 canary 用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；验证 Pingora 直连入口时再追加 `--require-direct ...` 参数。未带 `--require-direct` 的 runtime-only 基础门禁会自动执行直连彩排状态复核，确认公网 `80/443` 仍由 Nginx 接流、Pingora shadow `127.0.0.1:18081`、realpath canary `127.0.0.1:18083` 和 current release 自审均通过；启用后 `--require-direct` 复核不再要求 Nginx 接公网彩排状态。生成正式直连切换 runbook 时，`--direct-redirect-host` 和回退 smoke Host 必须与 `--direct-host` 同 hostname，只允许端口不同。
+
 ## 验证
 
 ```bash
diff --git a/deploy/nginx/snippets/genarrative-pingora-canary.conf b/deploy/nginx/snippets/genarrative-pingora-canary.conf
new file mode 100644
index 000000000..e38e9f162
--- /dev/null
+++ b/deploy/nginx/snippets/genarrative-pingora-canary.conf
@@ -0,0 +1,64 @@
+# Pingora canary handoff snippet.
+# 中文注释：本文件只提供人工 include 后的 Nginx -> Pingora 试跑入口，不默认承接公网流量。
+# 启用前复制到目标机并替换 __GENARRATIVE_PINGORA_PROBE_TOKEN__，确认只允许可信来源访问。
+
+location = /__genarrative_pingora_canary/healthz {
+    allow 127.0.0.1;
+    allow ::1;
+    deny all;
+
+    proxy_http_version 1.1;
+    proxy_set_header Connection "";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Request-Id $request_id;
+    proxy_set_header X-Genarrative-Pingora-Probe "__GENARRATIVE_PINGORA_PROBE_TOKEN__";
+    add_header X-Genarrative-Nginx-Handoff pingora-canary always;
+    proxy_pass http://127.0.0.1:18081/__genarrative_pingora/healthz;
+}
+
+location ~ ^/__genarrative_pingora_canary/v1/database/[^/]+/subscribe$ {
+    allow 127.0.0.1;
+    allow ::1;
+    deny all;
+
+    rewrite ^/__genarrative_pingora_canary(/.*)$ $1 break;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "Upgrade";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Request-Id $request_id;
+    proxy_read_timeout 3600s;
+    add_header X-Genarrative-Nginx-Handoff pingora-canary always;
+    proxy_pass http://127.0.0.1:18081;
+}
+
+location /__genarrative_pingora_canary/ {
+    allow 127.0.0.1;
+    allow ::1;
+    deny all;
+
+    rewrite ^/__genarrative_pingora_canary(/.*)$ $1 break;
+    proxy_http_version 1.1;
+    proxy_buffering off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_set_header Connection "";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Request-Id $request_id;
+    proxy_set_header X-Genarrative-Pingora-Canary "nginx-prefixed";
+    add_header X-Accel-Buffering no always;
+    add_header X-Genarrative-Nginx-Handoff pingora-canary always;
+    proxy_pass http://127.0.0.1:18081;
+}
diff --git a/deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf b/deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf
new file mode 100644
index 000000000..9ba6f5b2f
--- /dev/null
+++ b/deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf
@@ -0,0 +1,90 @@
+# Pingora real-path canary handoff server.
+# 中文注释：本文件只提供人工 include 后的本机真实路径 canary，不默认承接公网流量。
+# 启用前复制到目标机并替换 __GENARRATIVE_PINGORA_PROBE_TOKEN__，只能在 nginx http 上下文 include。
+
+server {
+    listen 127.0.0.1:18083;
+    server_name genarrative-pingora-realpath-canary.local;
+    access_log /var/log/nginx/genarrative-pingora-realpath-canary.access.log genarrative_upstream;
+    error_log /var/log/nginx/genarrative-pingora-realpath-canary.error.log warn;
+
+    allow 127.0.0.1;
+    allow ::1;
+    deny all;
+
+    location = /__genarrative_pingora_realpath_canary/healthz {
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Request-Id $request_id;
+        proxy_set_header X-Genarrative-Pingora-Probe "__GENARRATIVE_PINGORA_PROBE_TOKEN__";
+        add_header X-Genarrative-Nginx-Handoff pingora-realpath-canary always;
+        proxy_pass http://127.0.0.1:18081/__genarrative_pingora/healthz;
+    }
+
+    location = /api/creation-entry/config {
+        default_type application/json;
+        proxy_http_version 1.1;
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        proxy_set_header Connection "";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Request-Id $request_id;
+        proxy_set_header X-Genarrative-Pingora-Canary "nginx-realpath";
+        add_header X-Accel-Buffering no always;
+        add_header X-Genarrative-Nginx-Handoff pingora-realpath-canary always;
+        proxy_pass http://127.0.0.1:18081;
+    }
+
+    location ~ ^/v1/database/[^/]+/subscribe$ {
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "Upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Request-Id $request_id;
+        proxy_read_timeout 3600s;
+        add_header X-Genarrative-Nginx-Handoff pingora-realpath-canary always;
+        proxy_pass http://127.0.0.1:18081;
+    }
+
+    location ^~ /v1/identity {
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "Upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Request-Id $request_id;
+        add_header X-Genarrative-Nginx-Handoff pingora-realpath-canary always;
+        proxy_pass http://127.0.0.1:18081;
+    }
+
+    location = /assets/app.js {
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host $host;
+        proxy_set_header X-Request-Id $request_id;
+        add_header X-Genarrative-Nginx-Handoff pingora-realpath-canary always;
+        proxy_pass http://127.0.0.1:18081;
+    }
+
+    location = /generated-pingora-canary-smoke {
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host $host;
+        proxy_set_header X-Request-Id $request_id;
+        add_header X-Genarrative-Nginx-Handoff pingora-realpath-canary always;
+        proxy_pass http://127.0.0.1:18081;
+    }
+
+    location / {
+        return 404;
+    }
+}
diff --git a/deploy/pingora/nginx-route-parity.matrix.json b/deploy/pingora/nginx-route-parity.matrix.json
new file mode 100644
index 000000000..8642b8651
--- /dev/null
+++ b/deploy/pingora/nginx-route-parity.matrix.json
@@ -0,0 +1,375 @@
+{
+  "version": 1,
+  "description": "Pingora shadow gateway routes that must stay aligned with the current Genarrative Nginx production/development templates before any public cutover.",
+  "routes": [
+    {
+      "id": "acme_challenge",
+      "samplePath": "/.well-known/acme-challenge/token",
+      "expect": {
+        "kind": "static",
+        "root": "acme",
+        "mode": "exact"
+      },
+      "nginx": {
+        "production": [
+          "location /.well-known/acme-challenge/",
+          "root /var/www/html;"
+        ]
+      },
+      "docs": ["`/.well-known/acme-challenge/*`"]
+    },
+    {
+      "id": "shadow_probe",
+      "samplePath": "/__genarrative_pingora/healthz",
+      "expect": {
+        "kind": "shadow_probe"
+      },
+      "docs": ["`/__genarrative_pingora/healthz`"]
+    },
+    {
+      "id": "admin_redirect",
+      "samplePath": "/admin",
+      "expect": {
+        "kind": "redirect_permanent",
+        "location": "/admin/"
+      },
+      "nginx": {
+        "production": ["location = /admin", "return 301 /admin/;"],
+        "development": ["location = /admin", "return 301 /admin/;"]
+      },
+      "docs": ["`/admin`", "301 到 `/admin/`"]
+    },
+    {
+      "id": "admin_api_proxy",
+      "samplePath": "/admin/api/users",
+      "expect": {
+        "kind": "proxy",
+        "target": "api",
+        "bodyLimit": null,
+        "protectionClass": "admin_api"
+      },
+      "nginx": {
+        "production": [
+          "location ^~ /admin/api/",
+          "proxy_pass http://genarrative_api/admin/api/;",
+          "limit_conn genarrative_api_conn 64;",
+          "limit_req zone=genarrative_admin_rps burst=16 nodelay;"
+        ],
+        "development": [
+          "location ^~ /admin/api/",
+          "proxy_pass http://genarrative_api/admin/api/;",
+          "limit_conn genarrative_api_conn 64;",
+          "limit_req zone=genarrative_admin_rps burst=16 nodelay;"
+        ]
+      },
+      "docs": ["`/admin/api/*`"]
+    },
+    {
+      "id": "admin_assets",
+      "samplePath": "/admin/assets/index.js",
+      "expect": {
+        "kind": "static",
+        "root": "web",
+        "mode": "exact"
+      },
+      "nginx": {
+        "production": ["location ^~ /admin/assets/", "try_files $uri =404;"],
+        "development": ["location ^~ /admin/assets/", "try_files $uri =404;"]
+      },
+      "docs": ["`/admin/assets/*`"]
+    },
+    {
+      "id": "admin_spa_fallback",
+      "samplePath": "/admin/settings",
+      "expect": {
+        "kind": "static",
+        "root": "web",
+        "mode": "spa_fallback"
+      },
+      "nginx": {
+        "production": [
+          "location ^~ /admin/",
+          "try_files $uri $uri/ /admin/index.html;"
+        ],
+        "development": [
+          "location ^~ /admin/",
+          "try_files $uri $uri/ /admin/index.html;"
+        ]
+      },
+      "docs": ["`/admin/*`"]
+    },
+    {
+      "id": "web_assets",
+      "samplePath": "/assets/app.js",
+      "expect": {
+        "kind": "static",
+        "root": "web",
+        "mode": "exact"
+      },
+      "nginx": {
+        "production": ["location ^~ /assets/", "try_files $uri =404;"],
+        "development": ["location ^~ /assets/", "try_files $uri =404;"]
+      },
+      "docs": ["`/assets/*`"]
+    },
+    {
+      "id": "puzzle_gallery_list",
+      "samplePath": "/api/runtime/puzzle/gallery",
+      "expect": {
+        "kind": "proxy",
+        "target": "api",
+        "bodyLimit": null,
+        "protectionClass": "gallery_list"
+      },
+      "nginx": {
+        "production": [
+          "location = /api/runtime/puzzle/gallery",
+          "limit_conn genarrative_api_conn 320;",
+          "limit_req zone=genarrative_gallery_rps burst=4096 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ],
+        "development": [
+          "location = /api/runtime/puzzle/gallery",
+          "limit_conn genarrative_api_conn 320;",
+          "limit_req zone=genarrative_gallery_rps burst=4096 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ]
+      },
+      "docs": ["`/api/runtime/puzzle/gallery`"]
+    },
+    {
+      "id": "custom_world_gallery_list",
+      "samplePath": "/api/runtime/custom-world-gallery",
+      "expect": {
+        "kind": "proxy",
+        "target": "api",
+        "bodyLimit": null,
+        "protectionClass": "gallery_list"
+      },
+      "nginx": {
+        "production": [
+          "location = /api/runtime/custom-world-gallery",
+          "limit_conn genarrative_api_conn 320;",
+          "limit_req zone=genarrative_gallery_rps burst=4096 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ],
+        "development": [
+          "location = /api/runtime/custom-world-gallery",
+          "limit_conn genarrative_api_conn 320;",
+          "limit_req zone=genarrative_gallery_rps burst=4096 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ]
+      },
+      "docs": ["`/api/runtime/custom-world-gallery`"]
+    },
+    {
+      "id": "puzzle_gallery_detail",
+      "samplePath": "/api/runtime/puzzle/gallery/work-a",
+      "expect": {
+        "kind": "proxy",
+        "target": "api",
+        "bodyLimit": null,
+        "protectionClass": "gallery_detail"
+      },
+      "nginx": {
+        "production": [
+          "location ~ ^/api/runtime/puzzle/gallery/[^/]+$",
+          "limit_conn genarrative_api_conn 32;",
+          "limit_req zone=genarrative_api_rps burst=32 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ],
+        "development": [
+          "location ~ ^/api/runtime/puzzle/gallery/[^/]+$",
+          "limit_conn genarrative_api_conn 32;",
+          "limit_req zone=genarrative_api_rps burst=32 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ]
+      },
+      "docs": ["`/api/runtime/puzzle/gallery/{id}`"]
+    },
+    {
+      "id": "custom_world_gallery_detail",
+      "samplePath": "/api/runtime/custom-world-gallery/profile-a/owner-b",
+      "expect": {
+        "kind": "proxy",
+        "target": "api",
+        "bodyLimit": null,
+        "protectionClass": "gallery_detail"
+      },
+      "nginx": {
+        "production": [
+          "location ~ ^/api/runtime/custom-world-gallery/[^/]+/[^/]+$",
+          "limit_conn genarrative_api_conn 32;",
+          "limit_req zone=genarrative_api_rps burst=32 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ],
+        "development": [
+          "location ~ ^/api/runtime/custom-world-gallery/[^/]+/[^/]+$",
+          "limit_conn genarrative_api_conn 32;",
+          "limit_req zone=genarrative_api_rps burst=32 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ]
+      },
+      "docs": ["`/api/runtime/custom-world-gallery/{profile}/{owner}`"]
+    },
+    {
+      "id": "generic_api_proxy",
+      "samplePath": "/api/creation-entry/config",
+      "expect": {
+        "kind": "proxy",
+        "target": "api",
+        "bodyLimit": "default",
+        "protectionClass": "api"
+      },
+      "nginx": {
+        "production": [
+          "location ~ ^/api(?:/|$)",
+          "client_max_body_size 64m;",
+          "limit_conn genarrative_api_conn 64;",
+          "limit_req zone=genarrative_api_rps burst=64 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ],
+        "development": [
+          "location ~ ^/api(?:/|$)",
+          "client_max_body_size 64m;",
+          "limit_conn genarrative_api_conn 64;",
+          "limit_req zone=genarrative_api_rps burst=64 nodelay;",
+          "add_header X-Accel-Buffering no always;"
+        ]
+      },
+      "docs": ["`/api`、`/api/*`"]
+    },
+    {
+      "id": "spacetime_subscribe",
+      "samplePath": "/v1/database/genarrative/subscribe",
+      "expect": {
+        "kind": "proxy",
+        "target": "spacetime",
+        "bodyLimit": null,
+        "protectionClass": "spacetime"
+      },
+      "nginx": {
+        "production": [
+          "location ~ ^/v1/database/[^/]+/subscribe$",
+          "proxy_pass http://127.0.0.1:3101;",
+          "proxy_set_header Upgrade $http_upgrade;",
+          "proxy_set_header Connection \"Upgrade\";",
+          "proxy_read_timeout 3600s;"
+        ],
+        "development": [
+          "location ~ ^/v1/database/[^/]+/subscribe$",
+          "proxy_pass http://127.0.0.1:3101;",
+          "proxy_set_header Upgrade $http_upgrade;",
+          "proxy_set_header Connection \"Upgrade\";",
+          "proxy_read_timeout 3600s;"
+        ]
+      },
+      "docs": ["`/v1/database/{db}/subscribe`"]
+    },
+    {
+      "id": "spacetime_identity",
+      "samplePath": "/v1/identity",
+      "expect": {
+        "kind": "proxy",
+        "target": "spacetime",
+        "bodyLimit": null,
+        "protectionClass": "spacetime"
+      },
+      "nginx": {
+        "production": [
+          "location ^~ /v1/identity",
+          "proxy_pass http://127.0.0.1:3101;",
+          "proxy_set_header Upgrade $http_upgrade;",
+          "proxy_set_header Connection \"Upgrade\";"
+        ],
+        "development": [
+          "location ^~ /v1/identity",
+          "proxy_pass http://127.0.0.1:3101;",
+          "proxy_set_header Upgrade $http_upgrade;",
+          "proxy_set_header Connection \"Upgrade\";"
+        ]
+      },
+      "docs": ["`/v1/identity*`"]
+    },
+    {
+      "id": "v1_forbidden",
+      "samplePath": "/v1/ping",
+      "expect": {
+        "kind": "not_found"
+      },
+      "nginx": {
+        "production": ["location ^~ /v1/", "return 404;"],
+        "development": ["location ^~ /v1/", "return 404;"]
+      },
+      "docs": ["`/v1/*`"]
+    },
+    {
+      "id": "healthz_forbidden",
+      "samplePath": "/healthz",
+      "expect": {
+        "kind": "not_found"
+      },
+      "nginx": {
+        "production": [
+          "location ~ ^/(generated-|healthz|readyz)",
+          "return 404;"
+        ],
+        "development": [
+          "location ~ ^/(generated-|healthz|readyz)",
+          "return 404;"
+        ]
+      },
+      "docs": ["`/healthz*`"]
+    },
+    {
+      "id": "readyz_forbidden",
+      "samplePath": "/readyz",
+      "expect": {
+        "kind": "not_found"
+      },
+      "nginx": {
+        "production": [
+          "location ~ ^/(generated-|healthz|readyz)",
+          "return 404;"
+        ],
+        "development": [
+          "location ~ ^/(generated-|healthz|readyz)",
+          "return 404;"
+        ]
+      },
+      "docs": ["`/readyz*`"]
+    },
+    {
+      "id": "generated_assets_forbidden",
+      "samplePath": "/generated-puzzle-assets/foo.webp",
+      "expect": {
+        "kind": "not_found"
+      },
+      "nginx": {
+        "production": [
+          "location ~ ^/(generated-|healthz|readyz)",
+          "return 404;"
+        ],
+        "development": [
+          "location ~ ^/(generated-|healthz|readyz)",
+          "return 404;"
+        ]
+      },
+      "docs": ["`/generated-*`"]
+    },
+    {
+      "id": "web_spa_fallback",
+      "samplePath": "/some/spa/path",
+      "expect": {
+        "kind": "static",
+        "root": "web",
+        "mode": "spa_fallback"
+      },
+      "nginx": {
+        "production": ["location /", "try_files $uri $uri/ /index.html;"],
+        "development": ["location /", "try_files $uri $uri/ /index.html;"]
+      },
+      "docs": ["其它路径", "失败回退 `/index.html`"]
+    }
+  ]
+}
diff --git a/deploy/pingora/pingora-gateway.env.example b/deploy/pingora/pingora-gateway.env.example
new file mode 100644
index 000000000..67b1bc3ff
--- /dev/null
+++ b/deploy/pingora/pingora-gateway.env.example
@@ -0,0 +1,81 @@
+# Pingora 独立网关试点配置示例。
+# 当前只用于本机影子验证，不绑定 80/443，也不替代生产 Nginx。
+# systemd 模板默认读取 /etc/genarrative/pingora-gateway.env。
+
+GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081
+# 可选：直连 HTTPS 入口。默认关闭；启用时必须同时配置 cert/key，并把 FORWARDED_PROTO 设为 https。
+# cert/key 必须允许 genarrative 用户读取；不要直接 chmod Let's Encrypt live/archive 原始目录。
+# 可先用随包 scripts/deploy/pingora-tls-cert-sync.mjs 把证书同步到 /etc/genarrative/pingora-tls/<host>/。
+# 80/443 必须先从 Nginx 或其它进程释放；高端口 loopback 演练可先使用 127.0.0.1:18443 / 127.0.0.1:18080。
+# 如果要绑定 443/80，必须另行人工启用 systemd direct-entry drop-in 授予 CAP_NET_BIND_SERVICE。
+# GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=0.0.0.0:18443
+# GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/etc/genarrative/pingora-tls/genarrative.world/fullchain.pem
+# GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/etc/genarrative/pingora-tls/genarrative.world/privkey.pem
+# 可选：直连 HTTP 只做 301 到 HTTPS；启用时必须已经配置 TLS_LISTEN，ACME challenge 仍从 ACME_ROOT 静态读取。
+# GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=0.0.0.0:18080
+# GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_TARGET_SCHEME=https
+GENARRATIVE_PINGORA_GATEWAY_API_UPSTREAM=127.0.0.1:8082
+GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM=127.0.0.1:3101
+# 可选：同一公网 IP 上还承载 Gitea 时，按 Host 整站转发到 Gitea。
+# 命中这些 Host 的请求不走应用维护页、API body limit 或网关接流保护，避免影响 git clone / push。
+# 直连 443 如果要同时服务这些域名，当前单 listener TLS 配置必须使用覆盖全部 Host 的同一张证书。
+# GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world
+# GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000
+
+GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT=/srv/genarrative/web
+GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT=/var/www/html
+GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE=/var/lib/genarrative/maintenance/enabled
+
+GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=http
+GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES=67108864
+# gzip 默认开启；等级和最小响应长度对齐 Nginx gzip_comp_level 5 / gzip_min_length 1024。
+# Pingora 正式化口径固定为 gzip-only；br / zstd 不进入当前网关，Brotli 继续由 Nginx / 前置代理承担。
+GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip
+GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED=true
+GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5
+GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024
+
+# 静态响应缓存头：HTML / SPA fallback 保持 no-cache，Vite 指纹资源长缓存，其它静态资源保守 no-cache。
+# 网关会额外写入 ETag / Last-Modified 并支持 304 协商缓存；下面三项只控制 Cache-Control。
+GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL=no-cache
+GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL=public, max-age=31536000, immutable
+GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL=no-cache
+
+# 上游超时默认对齐当前 Nginx 模板：普通无显式长超时路由 60 秒，/api、公开列表/详情和 subscribe 为 3600 秒。
+GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_CONNECT_TIMEOUT_MS=3000
+GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS=60
+GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS=3600
+GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_LONG_READ_TIMEOUT_SECONDS=3600
+GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_WRITE_TIMEOUT_SECONDS=3600
+
+# 默认只信任 TCP 对端 IP；只有确认前置 Nginx / LB 会清洗 X-Forwarded-For 后才打开。
+GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=false
+# 打开 TRUST_X_FORWARDED_FOR 前必须显式确认；否则网关会拒绝启动。
+GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=false
+
+# 单进程内接流保护；默认值对齐当前 Nginx limit_conn / limit_req 口径。
+# INSTANCE_COUNT 默认 1；若横向运行多个 Pingora 实例且仍启用网关接流保护，必须先落地共享保护层并显式确认。
+GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT=1
+GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=false
+GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true
+GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_MAX_CONCURRENT=64
+GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_RATE_PER_SECOND=30
+GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_BURST=16
+GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_MAX_CONCURRENT=320
+GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_RATE_PER_SECOND=5000
+GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_BURST=4096
+GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_MAX_CONCURRENT=32
+GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_RATE_PER_SECOND=300
+GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_BURST=32
+GENARRATIVE_PINGORA_GATEWAY_API_MAX_CONCURRENT=64
+GENARRATIVE_PINGORA_GATEWAY_API_RATE_PER_SECOND=300
+GENARRATIVE_PINGORA_GATEWAY_API_BURST=64
+GENARRATIVE_PINGORA_GATEWAY_SPACETIME_MAX_CONCURRENT=256
+GENARRATIVE_PINGORA_GATEWAY_SPACETIME_RATE_PER_SECOND=1000
+GENARRATIVE_PINGORA_GATEWAY_SPACETIME_BURST=256
+# 仅供本机影子探针使用；为空时 /__genarrative_pingora/healthz 一律返回 404。
+GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN=
+
+GENARRATIVE_PINGORA_GATEWAY_LOG=info,pingora=info,pingora_gateway=info
+GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE=/var/log/genarrative/pingora-gateway.access.log
+GENARRATIVE_PINGORA_GATEWAY_OTEL_ENABLED=false
diff --git a/deploy/systemd/genarrative-database-backup.service b/deploy/systemd/genarrative-database-backup.service
index a19481b64..18c5b7e7c 100644
--- a/deploy/systemd/genarrative-database-backup.service
+++ b/deploy/systemd/genarrative-database-backup.service
@@ -9,7 +9,7 @@ User=root
 Group=root
 WorkingDirectory=/opt/genarrative/current
 EnvironmentFile=/etc/genarrative/api-server.env
-ExecStart=/usr/bin/node /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --stop-service spacetimedb.service --restart-service-after genarrative-api.service
+ExecStart=/usr/bin/node -- /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --stop-service spacetimedb.service --restart-service-after genarrative-api.service
 
 # 备份需要停止 / 启动 spacetimedb.service，并读取 /stdb、写入 /var/lib/genarrative/database-backups。
 PrivateTmp=true
diff --git a/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf b/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf
new file mode 100644
index 000000000..6cb0e6d8f
--- /dev/null
+++ b/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf
@@ -0,0 +1,17 @@
+# Pingora 直连公网入口的 systemd drop-in 模板。
+# 默认 provision 只把本文件安装到 /etc/genarrative/pingora/ 作为人工启用材料；
+# 需要低端口 80/443 时，才复制到：
+# /etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf
+#
+# 启用前必须同时在 /etc/genarrative/pingora-gateway.env 中显式配置：
+# GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=0.0.0.0:443
+# GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=0.0.0.0:80
+# GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=...
+# GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=...
+# 证书链和私钥必须允许 genarrative 用户读取；80/443 必须先从 Nginx 或其它进程释放。
+
+[Service]
+# 仅授予非 root genarrative 用户绑定 80/443 所需的最小 capability。
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
diff --git a/deploy/systemd/genarrative-pingora-gateway.service b/deploy/systemd/genarrative-pingora-gateway.service
new file mode 100644
index 000000000..751130e57
--- /dev/null
+++ b/deploy/systemd/genarrative-pingora-gateway.service
@@ -0,0 +1,31 @@
+[Unit]
+Description=Genarrative Pingora Shadow Gateway
+After=network-online.target genarrative-api.service spacetimedb.service
+Wants=network-online.target
+Requires=genarrative-api.service spacetimedb.service
+
+[Service]
+Type=simple
+User=genarrative
+Group=genarrative
+WorkingDirectory=/opt/genarrative/current
+EnvironmentFile=/etc/genarrative/pingora-gateway.env
+ExecStartPre=/usr/bin/test -d /srv/genarrative/web
+ExecStartPre=/usr/bin/test -d /var/www/html
+ExecStart=/opt/genarrative/current/pingora-gateway
+Restart=always
+RestartSec=5
+KillSignal=SIGINT
+TimeoutStopSec=60
+LimitNOFILE=65535
+TasksMax=2048
+
+# 影子网关只监听本机高端口，公网入口继续由 Nginx 承接。
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ReadOnlyPaths=/srv/genarrative/web /var/www/html
+ReadWritePaths=/var/lib/genarrative /var/log/genarrative
+
+[Install]
+WantedBy=multi-user.target
diff --git a/docs/README.md b/docs/README.md
index fc92fc358..acbd05333 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,7 +23,7 @@
 
 本地通过 SSH alias 管理多台服务器、查看硬件 / systemd / HTTP 健康状态并执行受控服务启停的 egui 桌面工具见 [【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md](./technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md)。
 
-生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
+生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。Pingora 只作为独立二进制影子网关试点时，边界、路由口径与替换前验收见 [【开发运维】Pingora独立网关试点-2026-06-11.md](./technical/【开发运维】Pingora独立网关试点-2026-06-11.md)。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
 
 SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)。
 
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index d37951164..41afe3d73 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -16,6 +16,89 @@
 
 ---
 
+## 2026-06-13 Pingora 低端口直连只通过显式 systemd drop-in 启用
+
+- 背景：`genarrative-pingora-gateway.service` 默认以 `genarrative` 非 root 用户运行，shadow 阶段只监听本机高端口；如果正式评估让 Pingora 直接绑定公网 `80/443`，需要低端口绑定能力，但不能让 Server-Provision 或默认 service 自动改变接流边界。
+- 决策：主 systemd service 保持 shadow 口径，不携带 `CAP_NET_BIND_SERVICE`。仓库提供 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf` 作为人工启用 drop-in 模板，Server-Provision 只安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 备查和手动覆盖；正式切换窗口从 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 执行时默认读取 current release 随包的 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，不依赖 `/etc` 参考模板、Jenkins 工作区或源码 checkout。直连切换前先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成 JSON runbook，逐条审阅 Host 与回退巡检入口确认、current release preflight、启用前基础门禁、direct enable dry-run、direct enable apply（通过命令证据脚本归档 stdout / stderr / 退出码）、切换后 health patrol 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后 `--require-direct` 复核、rollback dry-run、rollback apply（通过命令证据脚本归档 stdout / stderr / 退出码）、回退后 health patrol 切回 `nginx` 并恢复切换前 public base URL / Host、回退后 health patrol env Nginx 模式复核；启用前基础门禁不带 `--require-direct`，因为 systemd drop-in 尚未生效，启用后复核必须带 `--require-direct`。正式切换 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 和回退 smoke 分别验证到不同入口；还必须显式传 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，切换前 Nginx 巡检需要 Host 覆盖时再传 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 覆盖现场原有巡检入口。若需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文并把参数传给 rollback dry-run / apply。只有切换窗口通过 `pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名>` 先跑 current release 自审，确认发布包自包含、`pingora-gateway` 可执行且 systemd `ExecStart` 指向随包网关，失败时不安装 drop-in；随后跑 direct preflight，确认当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都可读取证书链 / 私钥，确认 service 模板与 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含本次 `/etc/genarrative/pingora-gateway.env`，并确认 service `ExecStart=` 指向的 current release `pingora-gateway` 存在且可执行，再安装到 `/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf`、执行 `systemctl daemon-reload`、重启 Pingora，并用 `systemctl cat` 核验 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl is-active` 确认服务 active、用 direct live smoke 验证 HTTPS / HTTP redirect / ACME / WSS 101 后，才视为授予低端口能力成功。启用前还必须显式配置 TLS / redirect env 和真实证书，并确认 current release 已落盘可执行 `pingora-gateway`、Nginx 或其它进程已释放 `80/443`；启用后仍必须跑 release readiness 门禁；验证失败时统一执行 `pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 回到 shadow / Nginx 入口，回退脚本会先运行 `nginx -t`，通过后移除 direct-entry drop-in、重启 Pingora，再用 `systemctl cat` 确认两条低端口 capability 均已从最终 unit 配置中移除，用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，并 reload Nginx、确认 Nginx service 仍为 `active`，最后用 curl smoke URL 证明 Nginx 入口真实可访问；回退 smoke URL/body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`。回退脚本 `--apply` 必须同时带 `--reload-nginx` 和 `--nginx-smoke-url`，避免只撤掉 Pingora 低端口能力却没有证明 Nginx 已重新接流；本机打 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 必须带 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免命中默认 vhost。回退后必须复核 health patrol env 已切回 `nginx` 且 public base URL / Host 恢复为切换前记录值；如果 env 已预先修正，rollback 脚本可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 自动执行这项复核，切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若需证明 Pingora 仍以 shadow 高端口存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应包含 `gateway=pingora-shadow`。
+- 决策补充：health patrol env 的直连/回退切换不再靠人工编辑三行变量；正式 runbook 使用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply`，只更新 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST` 并立即调用随包 `check-production-health-patrol-env.mjs` 复核。Pingora direct 使用本机 public base URL 时脚本必须带 `--public-host <域名>`；回退到 Nginx 时根据切换前记录传 `--clear-public-host` 或 `--public-host <切换前Host>`。生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 必须严格解析，非法值直接失败，不得静默按 false 继续；env 复核脚本的 `--env-file` 与 env 切换脚本的 `--env-file` / `--check-script` 必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。Node 22 已内置 `--env-file` 启动参数，凡是用 Node 启动项目脚本且要把业务 `--env-file` 传给脚本时，必须写成 `node -- <script> --env-file ...`；systemd / shell / release readiness runbook 中的这类 Node 调用都必须保留 `--` 分隔符。
+- 写入语义补充：`pingora-health-patrol-env-switch.mjs --apply` 必须先对权限固定为 `0600` 的临时目标 env 运行随包 env 复核脚本，复核通过后才按真实 `/etc/genarrative/health-patrol.env` 原权限和 owner/group 原子替换；复核失败时不得写入真实 env，避免切换窗口留下半坏巡检配置。`--apply` 时 `--env-file` 必须直接指向真实普通文件，不能是符号链接；若现场 env 是链接，先确认真实目标路径后再传给脚本，避免替换链接本身或写入非预期目标。
+- 顺序补充：正式 runbook 中 health patrol 的 Nginx 回退 env 必须在 `rollback apply` 前预置，随后 `pingora-direct-rollback.sh --apply` 会用 `--health-patrol-expected-public-base-url` 和 `--health-patrol-expected-public-host` / `--health-patrol-require-empty-public-host` 在 Nginx smoke 后复核该 env；最后仍保留独立的回退后 health patrol env 复核步骤。
+- 顺序补充：正式 runbook 中 Pingora 自身 env 的 shadow 回退也必须在 `rollback apply` 前预置。真实直连会把 `/etc/genarrative/pingora-gateway.env` 提升为 `0.0.0.0:80/443` direct 配置；回退脚本移除 `CAP_NET_BIND_SERVICE` 后会重启 Pingora，如果 env 仍保留低端口监听，服务可能按预期失败而不是回到 shadow。因此 rollback apply 前必须用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 先确认 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081`，并清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` 和 `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`，避免保留证书路径但无 TLS listener 的半直连 env。
+- 安全补充：直连公网地址时 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR` 必须保持 `false`；只有 Pingora 前方仍有会清洗 `X-Forwarded-For` 的受控代理且监听为 loopback / 受控入口时，才允许配合 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true` 使用转发 IP 作为接流保护 client key。目标机 direct preflight 必须在公网监听加 `TRUST_X_FORWARDED_FOR=true` 时失败，且这两个 gateway env 布尔值也必须严格解析，非法值直接失败，避免公网用户伪造限流 key 或拼写错误被当成 false。
+- 发布补充：`npm run check:production-api-release` 继续验证 API release 自包含和显式 include 的假二进制布局；`npm run check:pingora-production-release-build` 必须额外走真实 `cargo build -p pingora-gateway --release --target x86_64-unknown-linux-gnu`，并用假 `api-server` 验证 `--include-pingora-gateway` 发布包包含可执行 `pingora-gateway`、`pingora-gateway.sha256` 和 manifest 登记。`check:pingora-release-readiness` 默认纳入该真实构建 smoke，避免正式切换前只验证发布包布局而没有验证 Pingora release 二进制可构建。
+- 发布安全补充：API release 和 deploy 动态烟测必须复核 `deploy/pingora/pingora-gateway.env.example` 随包后的生产安全默认值，至少包括 `COMPRESSION_ALGORITHMS=gzip`、`TRUST_X_FORWARDED_FOR=false`、`TRUSTED_FRONT_PROXY_CONFIRMED=false`、`PROTECTION_ENABLED=true` 和空 `PROBE_TOKEN`；这些值漂移时应在构建 / 部署门禁中失败，而不是等切换窗口人工审查。
+- 自审补充：正式直连 runbook 的 current release 自审不只看文件存在和可执行；还必须复核 `api-server.sha256` / `pingora-gateway.sha256` 与当前文件匹配，并读取 `release-manifest.api-server.json` 或 `release-manifest.json` 确认 `component_type=api-server` 且 manifest 已登记 `pingora-gateway` 与 `pingora-gateway.sha256`。checksum 或 manifest 漂移属于 `CRITICAL`，应先修发布包或 deploy 复制链路，再继续切换。
+- 证据补充：current release 自审、状态快照和证据包脚本的显式 `--timeout-ms`，以及 `GENARRATIVE_PINGORA_CURRENT_RELEASE_TIMEOUT_MS` / `GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS` 必须是正整数；这些脚本读取的布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值。非法值直接失败，不得静默回退默认超时或 false。自审、状态快照和证据包的 `--release-root` 都不能是文件系统根目录，状态快照的 `--health-patrol-env-file` / `--pingora-env-file` 以及证据包所有显式路径参数也不能是文件系统根目录；状态快照自身还必须拒绝带换行或 NUL 的 release/env 路径，并在执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前复核子命令参数；证据包在执行状态快照或 direct live 子命令前还必须拒绝任何带换行或 NUL 字符的子命令参数，避免污染后的结构化 `args[]` 先进入 manifest / command 证据再等最终总审计兜底；`--output-root` 及其已存在上级路径不能是符号链接，已存在的 `--output-root` 必须是真实目录；路径异常时必须在执行状态快照前失败，避免把切换证据写入非预期软链目标。
+- current release 自审安全补充：`pingora-current-release-audit.mjs` 的 `--release-root` 和 `--systemd-service` 不能包含换行或 NUL 字符；启用 `--systemd-show` 时，脚本必须在执行 `systemctl show` 前复核子命令可执行文件和所有参数不含换行或 NUL，避免污染参数进入只读自审命令。
+- direct preflight 安全补充：`check-pingora-direct-preflight.mjs` 的 `--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值不能包含换行或 NUL 字符；执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前必须复核子命令可执行文件和所有参数不含换行或 NUL，避免污染参数进入目标机直连预检命令。
+- API 代理头补充：Pingora 直连接管前必须证明上游 `api-server` 收到的代理头仍对齐 Nginx。网关透传 `Host`，写入 `X-Forwarded-Host`、配置化的 `X-Forwarded-Proto`、TCP 对端 IP 作为 `X-Real-IP`，并把 TCP 对端 IP 追加到 `X-Forwarded-For`；`GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR` 只影响接流保护 client key，不改变上游归因头。`npm run check:pingora-gateway-smoke` 必须用 mock 上游回显并断言这些头，避免直连后回调 URL、鉴权来源或日志归因漂移。
+- 静态缓存补充：Pingora 直连静态响应必须同时保留 `Cache-Control` 分档和浏览器协商缓存能力。HTML / SPA fallback 默认 `no-cache`，Vite 指纹资源默认 `public, max-age=31536000, immutable`，其它静态资源和 ACME 默认 `no-cache`；所有静态文件响应写入弱 `ETag` 与 `Last-Modified`，并对 `GET` / `HEAD` 的 `If-None-Match`、`If-Modified-Since` 返回 `304`。`npm run check:pingora-gateway-smoke` 必须覆盖静态 `HEAD`、ETag 304 和 Last-Modified 304，避免直连后旧浏览器缓存体验或 HTML 入口刷新语义漂移。
+- 静态 Range 补充：Pingora 直连静态响应必须声明 `Accept-Ranges: bytes`，支持单段 `Range: bytes=` 返回 `206 + Content-Range`，越界范围返回 `416 + Content-Range: bytes */<len>`，`HEAD + Range` 只返回头且保留正确 `Content-Length`。多段 range 暂按完整文件返回，不引入 multipart 响应；条件请求优先于 Range，命中时仍返回 `304`；`If-Range` 日期匹配时继续返回 `206`，日期旧于文件或弱 ETag 校验器时回完整 `200`；`206` / `304` / `416` 不做 gzip 压缩，避免局部内容语义漂移。`npm run check:pingora-gateway-smoke` 必须覆盖 206、suffix range、416、HEAD range、If-Range 匹配和 If-Range 回完整文件。
+- 静态方法补充：Pingora 静态路由只允许 `GET` / `HEAD` 读取；非读取方法命中静态候选时返回 `405` 并写入 `Allow: GET, HEAD`，缺失文件仍返回 `404`。`npm run check:pingora-gateway-smoke` 必须覆盖该行为，避免直连后错误客户端把静态入口当作可写接口。
+- direct live 静态资产补充：`check-pingora-direct-live.mjs` 在 HTTPS 根路径返回 `200` 且 HTML 中发现 `/assets/` 或 `/admin/assets/` 引用时，必须额外请求该静态资源，校验 `Cache-Control`、`ETag`、`Last-Modified`、`Accept-Ranges: bytes`，再用 `HEAD` 验证头响应，用 `If-None-Match` / `If-Modified-Since` 验证 `304` 协商缓存，用 `Range: bytes=0-0` 验证 `206 + Content-Range` 且不压缩，并把这些 request_id 都纳入 `direct-access-log` method/path/status 对账；如果首页引用 Vite 指纹资源，还必须额外验证 `Cache-Control: public, max-age=31536000, immutable`，并把指纹资源 GET / HEAD / 304 / Range request_id 纳入同一 access log method/path/status 对账。静态 GET / HEAD / 304 / Range 的 `direct-live.json` 结果必须写入白名单 `headers`，只保留 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`，让证据包复盘时能直接确认缓存分档、校验器和 Range 语义；API / WSS 检查不落原始响应头。证据包 `manifest.summary.directLiveStaticHeaders` 必须把普通静态和 Vite 指纹静态的缓存头、校验头、Range `Content-Range` 与 304 状态提升出来；如果 direct live 已输出静态资产结果但摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，整包记为 `CRITICAL`。维护模式、非 HTML 或首页没有构建资产引用时该项允许标记为 skipped。这样直连切换证据不只覆盖 API / WSS / redirect，也覆盖当前发布包前端静态资源可读、协商缓存和旧 tab chunk 长缓存口径。
+- 快照补充：状态快照必须把 `--pingora-env-file` 与 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 精确匹配，支持 `EnvironmentFile=-/path` 和一行多个文件，但不能用路径前缀误判；未包含本次 pingora env 时 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile=false` 并标记 `CRITICAL`，避免证据包读取一份 env 而真实 Pingora 服务读取另一份 env。
+- 快照补充：状态快照支持 `--expected-pingora-env-mode shadow|direct`。正式 cutover runbook 的 `post-enable` 证据包必须传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包必须传 `--expected-pingora-env-mode shadow`；若 active env 姿态与期望不一致，证据包应标记 `CRITICAL`，不能只依赖 health patrol gateway mode 或 systemd drop-in 判断切流状态。
+- 证据验真补充：`scripts/ops/pingora-cutover-evidence-verify.mjs` 只接受 `schemaVersion=1` 的 manifest，并把 `manifest.files` 视为闭集，证据目录中除 `manifest.json` 和 manifest 已登记文件外，任何未登记普通文件、目录或符号链接都默认失败；`--allow-extra-files` 只用于人工排障显式放行，正式切换归档不使用。正式 runbook 的五个即时验真步骤都必须追加 `--require-summary-ok`，让 `pre-cutover`、`enable-apply`、`post-enable`、`rollback-apply`、`post-rollback` 证据在生成后立即要求 `manifest.summary.status=OK`；缺少 summary 或状态非 OK 时先修现场状态或重采证据，不等最终总审计才发现。
+- 正式 runbook 安全补充：`--warn-only`、`--allow-extra-files` 和 `--allow-extra-root-entries` 只允许在 runbook 外作为人工排障命令使用；`plan:pingora-direct-cutover` 生成的正式切换计划不得携带这些放行参数。需要使用放行参数时，先修现场状态、证据目录或重新归档，不能把人工排障口径带入正式切换计划。
+- 证据根目录补充：`scripts/ops/pingora-cutover-evidence-audit.mjs` 默认把证据根目录也视为闭集，只允许带 `manifest.json` 的证据目录；根目录普通文件、无 manifest 子目录和符号链接都会失败。`--allow-extra-root-entries` 只用于人工排障显式放行，正式切换归档不使用。
+- 证据总审计补充：三阶段 `pre-cutover` / `post-enable` / `post-rollback` 证据包分别验真，且 `enable-apply` / `rollback-apply` 命令证据生成后，正式 runbook 还必须执行 current release 随包 `scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000`。runbook 会自动生成或接受显式 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、五条真实切换命令证据和最终总审计；该脚本只读扫描证据根目录，按 `manifest.phase` 选择每个阶段最新证据目录、按 `manifest.phase + manifest.commandName` 选择真实切换命令证据，并复用随包 verifier 验真；所有候选 manifest 必须是 `schemaVersion=1`，最新证据选择和时间线证明只接受合法且规范的 UTC 毫秒 `manifest.generatedAt`，命令记录 `startedAt` / `finishedAt` 也必须使用 `new Date().toISOString()` 形式；缺失、非法或省略毫秒 / 本地时区格式时直接失败，不能用目录 mtime 兜底；`post-enable` 阶段还必须带可判定的 `manifest.summary.directLiveAccessLog` 与 `manifest.summary.directLiveStaticHeaders`，否则总审计失败，避免旧启用后证据包缺少 request_id 对账、静态缓存、校验器、Range 或 304 复盘入口；缺阶段、缺命令证据、最新证据损坏、阶段 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`、命令证据缺少或漂移 `manifest.expectedExecutable` / `manifest.command.executable` / 独立 `command-record.json` executable、命令证据缺少必需 `--apply` 参数、`manifest.command` 与 `command-record.json` 关键字段不一致、命令 stdout / stderr 引用与 `manifest.files` 不一致、命令 args / command 漂移、命令记录时间线不合法、标准八段证据任一条目审计状态非 `OK`、标准八段证据 `manifest.generatedAt` 顺序不满足 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`、标准八段证据跨度超过默认 24 小时、要求 `--require-cutover-run-id` 时任一阶段或命令缺少同一 `manifest.cutoverRunId`、证据根目录或 verifier 路径不安全、证据 verifier / 总审计入口路径或 manifest 登记文件名含换行 / NUL、证据根目录内出现坏 manifest / 符号链接时都应失败。确需更长维护窗口时，通过 release readiness runbook 参数 `--cutover-evidence-timeline-max-span-ms <ms>` 显式放宽，并让最终总审计 JSON 留下 `requiredCutoverRunId`、`requiredCommandExecutables`、`requiredCommandArgs`、`timeline.maxSpanMs` / `timeline.spanMs`。
+- 证据总审计补充：最终审计 JSON 的 `summary` 是值班人员优先入口；`summary.status` 给出 `OK` / `CRITICAL`，`summary.failedItems[]` 聚合根目录、阶段、命令和时间线失败，`summary.directLiveEvidence[]` 聚合 `post-enable` 的 access log 与静态头要求、ok 状态、短 reason 和摘要。现场先看 summary 定位，再展开 `phases[]`、`commands[]`、`timeline` 深挖。
+- 证据总审计补充：证据包会把状态快照里的 Pingora env 监听摘要提升到 `manifest.summary.pingoraEnvShadow`，包含 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode`、`shadowReady` 和 `ok`。正式 runbook 的最终总审计必须追加 `--require-phase-pingora-env-shadow post-rollback`，要求 `post-rollback` 证明 `listen=127.0.0.1:18081`、`mode=shadow`、`shadowReady=true`，且 TLS / HTTP redirect 低端口监听和证书路径均为空；最终审计 JSON 的 `summary.pingoraEnvShadowEvidence[]` 会聚合该要求、ok 状态、短 reason 和摘要，避免回退后 active env 仍残留 direct 低端口配置或 cert/key 半直连配置。
+- 文档门禁补充：Pingora 技术文档里的最终证据根目录总审计命令示例也必须包含 enable apply、health patrol direct env switch、Pingora gateway shadow env switch、health patrol nginx env switch 和 rollback apply 五条 `--require-command-executable`，`npm run check:pingora-release-readiness-plan` 会读取文档并阻断示例落后于真实 runbook 的情况；`npm run check:production-api-release` 还必须动态生成 API release，检查发布包 README 和随包 `scripts/check-pingora-release-readiness.mjs --dry-run-cutover` 输出的最终总审计步骤也保留这五条 current release 脚本身份要求。
+- 证据总审计补充：同一阶段或同一命令的最新 `manifest.generatedAt` 必须唯一。若多个候选共享最新时间戳，`pingora-cutover-evidence-audit.mjs` 必须输出 `AMBIGUOUS_LATEST` 并列出重复目录，不能按目录名排序打平；处理方式是重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。
+- 证据总审计补充：标准八段时间线只要任一阶段或命令证据声明了 `manifest.cutoverRunId`，八段就必须全部声明同一个值；顺序固定为 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`。缺字段或混入其它批次时，即使没有显式传 `--require-cutover-run-id`，总审计也必须失败，避免人工临时审计把不同切换批次拼成一条时间线。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。
+- 证据总审计输出补充：标准八段时间线失败时，`timeline.failedCount` 按具体失败项累计，`timeline.failureBreakdown` 分别记录 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded`，用于把多个失败证据或多个时间线问题拆成可操作排障项。
+- 命令证据身份补充：正式 runbook 的 `enable-apply` / `rollback-apply` 命令证据必须传 `--expected-executable <current release 随包脚本绝对路径>` 和 `--require-arg --apply`，分别绑定 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 和 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并在执行前要求真实命令参数包含 `--apply`。命令证据脚本会在创建正式命令证据前拒绝真实命令与预期脚本不一致、缺少必需 apply 参数，或任一真实命令参数包含换行 / NUL 字符，并把 `expectedExecutable` 写入 manifest / command-record；最终证据根目录总审计再用 `--require-command-executable` 复核 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` executable，并用 `--require-command-arg ...:--apply` 复核 `manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，同时拒绝 args 数组中任何带换行或 NUL 字符的结构化参数。总审计传入的 `--require-command-executable` executable 段也必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符，且会写入 `requiredCommandExecutables` 供复盘。总审计还会要求顶层 `manifest.commandName` 与内嵌 `manifest.command.name` 只要存在就各自是安全非空命令名，且两者同时存在时必须一致，并比较 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / name / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段；两份命令记录的 `schemaVersion` 都必须是 `1`，stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作；命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`；这些参数会隐式要求对应命令证据存在；`commandName` 只用于审计分类，不能替代真实脚本身份和真实 apply 参数校验。
+- 命令证据字段补充：`manifest.expectedExecutable` 和 `manifest.command.expectedExecutable` 只要出现，就必须是安全绝对路径；空字符串、相对路径、文件系统根目录或包含换行 / NUL 的值必须按坏 manifest 失败，不能用 `||` 等兜底逻辑把坏字段吞掉。命令证据生成端的 `--expected-executable` 同样必须在执行真实命令前拒绝相对路径、文件系统根目录和带换行 / NUL 的路径。
+- 命令证据身份补充：只要命令证据声明了 `expectedExecutable`，`manifest.command.executable` 和独立 `command-record.json.executable` 就必须同时是同一个安全绝对路径；即使人工总审计漏传 `--require-command-executable`，真实 executable 与 expectedExecutable 漂移也必须失败。
+- 命令证据字段补充：正式命令证据必须在 `manifest.command.executable` 和 `command-record.json.executable` 中同时记录真实可执行文件绝对路径；只保留可读 `command` 字符串、缺少结构化 executable 或 executable 不是绝对路径，都必须失败。
+- 命令证据生成补充：`pingora-cutover-command-evidence.mjs` 的 `-- <command>` 必须直接传真实命令绝对路径，不能传 PATH 裸命令名；生成端会在执行前拒绝非绝对路径，避免写出最终总审计天然会拒绝的 command-record。
+- 路径安全补充：切换窗口覆盖 `pingora-direct-enable.sh` 的 `--preflight-script`、`--direct-live-script`、`--current-release-audit-script`、`--template-path`、`--service-unit-path`、`--dropin-path` 或 env 文件路径时必须使用绝对路径，且不能指向文件系统根目录，避免 current release、Jenkins 工作区和现场 cwd 混用；`--apply` 必须在安装 direct-entry drop-in 前确认 current release 自审、direct preflight 和 direct live smoke 脚本都真实存在，任一脚本缺失时直接失败且不改 systemd。启用脚本还必须在 current release 自审、preflight、drop-in 写入和 systemctl 前拒绝 service、路径、URL、Host、probe token、access log、数据库名、tail 行数和 timeout 参数中的换行或 NUL 字符，并在安装前拒绝符号链接形式的 drop-in 目录或 drop-in 目标文件、拒绝已存在但不是普通文件的目标，避免把低端口 capability 写入非预期 systemd 位置。`pingora-direct-rollback.sh --apply` 也必须在 `nginx -t`、删除 drop-in、reload Nginx 或 health patrol / shadow probe 复核前拒绝 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override 中的换行或 NUL 字符，并拒绝 service unit、drop-in、health patrol env、复核脚本和路径形式二进制 override 指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件、拒绝已存在但不是普通文件的目标，避免回退窗口误删或误判非预期 systemd 位置。`pingora-direct-rollback.sh` 覆盖 `--nginx-binary` 或 `--curl-binary` 时允许裸命令名走 `PATH`，但只要值包含路径分隔符就必须是绝对路径，避免回退窗口从 cwd 运行相对二进制；`--nginx-smoke-url` 必须是 `http(s)` URL，非法值在移除 drop-in 前失败。
+- 直连日志证据补充：Pingora 直连接管不能只看 HTTPS / HTTP redirect / ACME / WSS 响应成功；`pingora-direct-enable.sh --apply` 和 release readiness `--require-direct` 必须显式提供 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。direct live smoke 会给每个请求生成 `X-Request-Id`，再反查 Pingora access log 尾部记录，缺少对应 `request_id`、方法、路径或状态漂移都应阻断启用后复核。启用脚本 apply 后必须以 `--json` 运行 direct live 并解析 stdout 中的 `direct-access-log` 结构化结果；缺少该结果、`matchedCount != checked`、`missingCount != 0` 或 `mismatchCount != 0` 都让启用失败，避免 direct live 子进程退出 0 但 access log 证据缺失时误判切换成功。正式 runbook 的启用后证据包必须额外传 `--run-direct-live`，把 `direct-live.json`、stdout / stderr、命令记录、direct-access-log 检查结果和静态响应头白名单证据写入同一证据目录，不能只依赖启用脚本或 release readiness 的终端输出；`direct-live.json` 中的 `direct-access-log` 必须保留 `scannedLineCount`、`matchedCount`、`missing[]`、`mismatches[]` 以及每个 `request_id` 的预期 / 实际 method、path 与 status，静态资源检查还必须保留 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding` 白名单头，避免复盘时只看到 count 或终端 stderr。证据包还必须把 `directLiveAccessLog` 和 `directLiveStaticHeaders` 摘要提升到 `manifest.summary`，让值班人员先从 manifest 快速看到普通静态 / 指纹静态的 `Cache-Control`、`ETag`、`Last-Modified`、`Content-Length`、Range `Content-Range` 与 304 状态证据；缺少 `direct-access-log` 结构化结果、缺少可判定的静态头摘要，或静态头摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 / Last-Modified 304 证据时整包记为 `CRITICAL`。若 snapshot 或 direct live stdout 无法解析，证据包必须保留 `snapshot-parse-error.txt` 或 `direct-live-parse-error.txt`，并在 manifest / 最终 stdout 中索引错误文件。`deploy/env/pingora-direct-live.env.example` 必须保留 `GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG` 和 `GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES`，让目标机和 CI 使用同一口径。
+- 影响范围：`deploy/systemd/genarrative-pingora-gateway.service`、`deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`deploy/env/`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`scripts/deploy/pingora-health-patrol-env-switch.mjs`、`scripts/jenkins-server-provision.sh`、API release / Jenkins 归档链路、生产运维护栏、Pingora 试点文档、Nginx README 和生产护栏。
+- 验证方式：`npm run check:production-ops` 确认主 service 仍是 shadow、drop-in 具备最小 capability、Provision 只安装人工启用模板且 release 携带启用 / 回退脚本，并确认 enable 脚本默认模板路径指向 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`plan:pingora-direct-cutover` 入口存在；`npm run check:pingora-direct-enable` 和 `npm run check:pingora-direct-rollback` 确认脚本默认 dry-run 不修改 drop-in、会打印命令、release layout 默认读取随包 direct-entry 模板、拒绝相对路径、非法 Nginx smoke URL、路径形式的二进制 override、enable / rollback 控制字符参数、符号链接 drop-in 目录 / 目标以及非普通 drop-in 目标，enable current release 自审失败、direct preflight 脚本缺失或 direct live smoke 脚本缺失时不会安装 drop-in，direct live 退出 0 但缺少 `direct-access-log` JSON 证据时启用失败，rollback drop-in 路径异常或控制字符参数时不会继续执行 `nginx -t` 或删除真实目标，enable `--apply` 缺少 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 或 `--direct-spacetime-database` 会失败，rollback `--apply` 缺少 `--reload-nginx` 或 `--nginx-smoke-url` 会失败，且启用 / 回退后都会核验 systemd 最终配置和 `ExecStart` 指向 current release；`npm run check:pingora-cutover-status-snapshot` 必须覆盖 `systemctl cat` 读取另一份 Pingora env 时快照标记 `CRITICAL`；`npm run check:pingora-release-readiness-plan` 必须覆盖 `--dry-run-cutover` runbook、Host 一致性确认、redirect Host / rollback smoke Host 漂移负例、缺少 `--require-direct` 的负例、缺少 `--rollback-health-patrol-public-base-url` 的负例、enable / rollback apply 步骤和回退后 health patrol env Nginx 模式复核；enable 必须确认 Pingora active 并执行 direct live smoke，direct live 失败或 access log 结构化证据缺失时整次启用失败；rollback 必须先跑 `nginx -t`，失败时不能先删除 drop-in，重启后必须确认 `ExecStart` 没有漂到旧 release，reload 后必须确认 Nginx active 并执行 smoke URL，curl 失败时整次回退失败；可选 health patrol env 复核必须拒绝 `pingora-direct` 残留或 public base URL / Host 漂移；可选 shadow probe 复核必须拒绝 URL / token 缺任一项、非法 URL 或非 `pingora-shadow` 响应；`npm run check:pingora-release-readiness` 默认会串起 direct-entry 静态预检、启用 / 回退 dry-run 与生产护栏；切换窗口先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再运行 release readiness `--require-direct`；验证失败时先 dry-run 回退脚本，再用 `--apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 执行，并确认回退脚本未报告 capability 残留、ExecStart 漂移、Nginx 非 active 或 smoke 失败，最后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 运行 health patrol env nginx 模式复核。
+- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
+
+## 2026-06-13 Pingora direct live 必须覆盖 WSS subscribe
+
+- 背景：Pingora 已具备显式 TLS / HTTP redirect 直连入口，但 SpacetimeDB 前端订阅依赖 `/v1/database/<db>/subscribe` 的 WebSocket 长连接；只检查 HTTPS 普通请求无法证明直连入口能替代 Nginx 的 WebSocket 透传。
+- 决策：`check-pingora-direct-live.mjs` 默认先通过 TLS ALPN 确认 HTTPS 可协商 `h2`，再对 `wss://<direct>/v1/database/<database>/subscribe` 发起握手，并使用 SpacetimeDB SDK 2.4.1 默认子协议 `v2.bsatn.spacetimedb`；成功 101 时必须保留该子协议和 `X-Genarrative-Gateway: pingora-shadow`。release readiness `--require-direct` 会自动要求 WSS subscribe 返回 101，并强制要求 `--direct-http-base-url` / `GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL`、`--direct-host` / `GENARRATIVE_PINGORA_DIRECT_HOST`、`--direct-redirect-host` / `GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST`、`--direct-pingora-access-log` / `GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG`、`--direct-preflight-systemd` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT=true`、`--direct-preflight-check-cert-readable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE=true`、`--direct-preflight-check-service-env-file` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE=true`、`--direct-preflight-check-service-user-cert-readable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE=true`、`--direct-preflight-check-service-binary-executable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE=true` 和 `--direct-spacetime-database` / `GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE` 和 `--direct-health-patrol-env-file` / `GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE`，确保 HTTP/2 ALPN、HTTP 301、ACME challenge、正式域名 Host/SNI、redirect Location host、Pingora access log 的 request_id 落盘、systemd drop-in 生效、service EnvironmentFile 一致性、当前用户证书可读性、服务用户证书可读性、current release 二进制可执行性、health patrol direct 模式和目标库 WSS subscribe 都进入直连硬门禁；单独运行 direct live smoke 时可用 `--require-wss-upgrade` 强制同一口径。本机 `--host <域名>` 验证正式证书时，该 host 同时用于 HTTP Host 和 TLS SNI，`--redirect-host <域名或host:port>` 则用于校验 HTTP redirect `Location`。`--skip-wss` 只允许单独 direct live 临时排障；release readiness `--require-direct` 会直接拒绝。
+- 影响范围：`scripts/check-pingora-direct-live.mjs`、`scripts/check-pingora-gateway-smoke.mjs`、`scripts/check-pingora-release-readiness.mjs`、`deploy/env/pingora-direct-live.env.example`、生产运维护栏、Pingora 试点文档和 Nginx README。
+- 验证方式：`node --check scripts/check-pingora-direct-live.mjs scripts/check-pingora-release-readiness.mjs scripts/check-pingora-release-readiness-plan.mjs`、`npm run check:pingora-gateway-smoke`、`npm run check:pingora-release-readiness-plan`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
+- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
+
+## 2026-06-13 Pingora 直连入口先做显式配置能力
+
+- 背景：Pingora shadow 已覆盖 Nginx handoff、gzip、timeout 和接流保护；继续接近正式版时需要验证是否具备不经 Nginx 的 HTTPS 入口能力，但不能让默认 shadow 部署误绑定公网 `80/443`。
+- 决策：`pingora-gateway` 默认仍只监听 `GENARRATIVE_PINGORA_GATEWAY_LISTEN`；只有显式配置 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`TLS_CERT_FILE`、`TLS_KEY_FILE` 时才额外挂载 Rustls HTTPS listener。只有在 TLS 入口已配置时才允许配置 `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`，该 HTTP listener 除 ACME challenge 外统一 301 到 HTTPS。证书申请和续期仍由 Certbot / 外部自动化承担，Pingora 只读取现有证书文件。目标机直连入口验收使用 `npm run check:pingora-direct-live` 或 release readiness 的 `--require-direct`，默认 shadow / Nginx canary 门禁不强制直连。
+- 影响范围：`server-rs/crates/pingora-gateway`、`deploy/pingora/pingora-gateway.env.example`、`scripts/check-pingora-gateway-smoke.mjs`、`scripts/check-pingora-direct-live.mjs`、生产运维护栏、Pingora 试点文档和 Nginx README。
+- 验证方式：`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
+- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
+
+## 2026-06-13 Pingora shadow 网关显式承接上游 timeout
+
+- 背景：Pingora shadow 已覆盖路由、接流保护、gzip 和 canary handoff，但上游连接 / 读 / 写 timeout 若继续依赖框架默认值，正式 canary 时可能和 Nginx 的 `proxy_read_timeout` / `proxy_send_timeout` 口径漂移。
+- 决策：`pingora-gateway` 在 `HttpPeer` 上显式设置 timeout：连接默认 `3000ms`，没有 Nginx 显式长超时的代理路由读取默认 `60s`，通用 `/api`、公开列表 / 详情和 SpacetimeDB subscribe 读取默认 `3600s`，写上游默认 `3600s`。读 / 写 / 连接超时统一映射为 JSON `504 GATEWAY_UPSTREAM_TIMEOUT`。所有 `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_*TIMEOUT*` 配置必须大于 `0`。
+- 影响范围：`server-rs/crates/pingora-gateway`、`deploy/pingora/pingora-gateway.env.example`、`scripts/check-pingora-gateway-smoke.mjs`、生产运维护栏、Pingora 试点文档和 Nginx README。
+- 验证方式：`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
+- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
+
+## 2026-06-13 Pingora shadow 网关先补齐 gzip parity
+
+- 背景：Pingora 影子网关已经覆盖核心路由、接流保护和 Nginx handoff smoke，但旧口径仍把 gzip 和 Brotli 一起列为未承接能力，正式切换前需要先补齐 Nginx 当前已启用的 gzip 行为，同时避免未验收算法被 Pingora 默认行为隐式打开。
+- 决策：`pingora-gateway` 默认启用 Pingora response compression，`GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED=true`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024` 对齐 Nginx `gzip_comp_level 5` / `gzip_min_length 1024`；进入 compression 模块前把 `Accept-Encoding` 收敛成 gzip allowlist，避免未验收的 `br` / `zstd` 被隐式打开，并避免小响应被额外压缩。smoke 还必须覆盖图片资源不压缩，保持 Nginx `gzip_types` 边界。`GZIP_LEVEL` 必须在 `0..=9`，`GZIP_MIN_LENGTH_BYTES` 必须大于 `0`，越界启动失败；`COMPRESSION_ALGORITHMS` 当前只允许 `gzip`。Pingora 正式化口径固定为 gzip-only；Brotli 不进入当前 Pingora 直连门禁，仍由 Nginx / 前置代理能力探测承担。
+- 影响范围：`server-rs/crates/pingora-gateway`、`deploy/pingora/pingora-gateway.env.example`、`scripts/check-pingora-gateway-smoke.mjs`、生产运维护栏、Pingora 试点文档和 Nginx 压缩文档。
+- 验证方式：`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
+- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
+
+## 2026-06-13 Pingora canary handoff 先本机容器复现再目标机 live 验证
+
+- 背景：Pingora 影子网关已覆盖核心 Nginx 路由 parity，但只靠静态 snippet 检查和目标机手工 live canary，无法在本机 / CI 中复现真实 Nginx -> Pingora handoff 链路。
+- 决策：新增 `npm run check:pingora-canary-docker` 作为正式切换前的本机容器验收：脚本启动 Docker Nginx、真实 `pingora-gateway`、mock `api-server` 和 mock SpacetimeDB，渲染同一份 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 后复用 live canary 断言。Docker Nginx 必须写入生产同口径 access log，并在 live smoke 后复用 `scripts/check-pingora-canary-access-log-parity.mjs` 按同一 `request_id` 对账 canary healthz、代表性 API、SpacetimeDB identity 和静态资源路径，避免本机 / CI 只验证 handoff 响应头。默认 Docker 或镜像缺失时跳过，CI / 目标 agent 用 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull` 强制执行；目标机人工 include 后仍必须跑 `npm run check:pingora-canary-live`。同时新增 `npm run check:pingora-release-readiness` 作为正式切换聚合门禁，默认适合本机提交前检查；切换窗口必须用 `--require-docker --pull-docker --require-nginx --require-live` 强制 Docker handoff、目标机 `nginx -t` 和 live canary 全部通过，且 `--require-live` 必须显式提供 `--live-host`，避免只打到 Nginx 默认 vhost。
+- 真实路径补充：前缀 canary 通过后、Pingora direct 直连前，使用 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 做真实路径 canary。该 snippet 必须作为独立本机 `server` include 到 Nginx `http` 上下文，默认监听 `127.0.0.1:18083` 并写独立 `genarrative-pingora-realpath-canary.access.log`，不能 include 到生产 `443` server 内覆盖正式 location。`check-pingora-canary-live.mjs --realpath` 和 `check-pingora-canary-access-log-parity.mjs --realpath` 负责验证真实 `/api`、`/v1`、`/assets` 路径；release readiness 默认执行 `check:pingora-realpath-canary-toggle`，验证 realpath canary 启停脚本 dry-run、apply、失败回滚和 disable 恢复逻辑，目标机 runtime-only 用 `--require-realpath-live` 把已启用真实路径 canary 纳入门禁。
+- 影响范围：`scripts/check-pingora-canary-docker.mjs`、`scripts/check-pingora-release-readiness.mjs`、`package.json`、生产运维护栏、Nginx README、Pingora 试点文档和生产运维文档。
+- 验证方式：`node --check scripts/check-pingora-canary-docker.mjs scripts/check-pingora-release-readiness.mjs scripts/check-pingora-release-readiness-plan.mjs scripts/check-pingora-realpath-canary-toggle.mjs`、`npm run check:pingora-realpath-canary-toggle`、`npm run check:pingora-canary-docker`、`npm run check:pingora-release-readiness`、`npm run check:nginx-pingora-canary`、`npm run check:production-ops`；有 Docker 镜像或允许拉取时追加 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull`，目标机切换窗口追加 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名>`。
+- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
 ## 2026-06-15 SpacetimeDB 本地 skills 只保留 CLI / Concepts / Rust
 
 - 背景：本仓库的 SpacetimeDB 接入已固定为 `server-rs + Axum + SpacetimeDB`，本地 skill 需要从上游 SpacetimeDB `skills/` 更新到 2.5 口径，同时避免继续维护当前项目不使用的 TypeScript server/client、C# 和 Unity 专用 skill。
@@ -2247,6 +2330,39 @@
 - 验证方式：`GET /api/creation-entry/config` 中各玩法 `unifiedCreationSpec.title` 等于已保存契约内容；后台只修改入口名称时不应隐式改写已保存的统一创作页表头。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 2026-06-11 Pingora 网关先独立二进制试点
+
+- 背景：评估 Pingora 是否逐步替代当前生产 Nginx 时，需要先验证 Genarrative 的现有反向代理、静态资源、维护模式和最小 SpacetimeDB 公网路由口径。
+- 决策：新增 `server-rs/crates/pingora-gateway` 作为独立 binary crate，默认监听 `127.0.0.1:18081` 做影子网关；当前不绑定 `80/443`，不替代 `deploy/nginx/genarrative.conf`，生产仍以 Nginx 为公网入口。
+- 影响范围：Rust workspace、Pingora 依赖、网关环境变量、`deploy/pingora/pingora-gateway.env.example` 和运维技术方案。
+- 验证方式：先执行 `cargo fmt --manifest-path server-rs/Cargo.toml -p pingora-gateway`、`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`；替换前必须补齐路由 parity、压缩、TLS、限流、systemd、Jenkins 和健康巡检。
+- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+- 决策补充：`/api` 通用路由必须同时检查 `Content-Length` 与实际流式请求体累计字节数；缺少长度头时超过上限也返回统一 `PAYLOAD_TOO_LARGE` JSON。影子部署模板使用 `deploy/systemd/genarrative-pingora-gateway.service`，默认读取 `/etc/genarrative/pingora-gateway.env`，仍只监听本机高端口；`/__genarrative_pingora/healthz` 只在配置并匹配 `X-Genarrative-Pingora-Probe` token 时返回 shadow JSON。
+- 决策补充：生产 `genarrative-health-patrol.service` 只在显式配置 `GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL` 与 `GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN` 时检查 Pingora shadow probe；未配置时巡检口径不变。Pingora shadow 日志必须保留 request/route/upstream/body 字段，方便和 Nginx access log 做 canary 对照。
+- 决策补充：生产健康巡检的公网入口模式必须显式区分 `nginx` 和 `pingora-direct`。默认 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 检查 API、SpacetimeDB 和 Nginx；Pingora 直连接管公网后切到 `pingora-direct`，改为检查 API、SpacetimeDB 和 `genarrative-pingora-gateway.service`，不再要求 `nginx.service` active。目标机本机探测 `127.0.0.1` 时用 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>` 保留正式 Host / vhost 语义。
+- 决策补充：Pingora 影子网关产物不进入默认 API release；只有显式传 `--include-pingora-gateway` 或在 `Genarrative-Api-Build` 勾选 `INCLUDE_PINGORA_GATEWAY` 时，才构建并打包 `pingora-gateway` / `pingora-gateway.sha256`。真实构建 Pingora 前必须先检查 `cmake`、C 编译器和 C++ 编译器；Jenkins 勾选 `INCLUDE_PINGORA_GATEWAY` 时也要先 fail-fast 检查这些工具，避免进入 Cargo 后才因 `libz-ng-sys` 构建依赖缺失失败。`production-api-deploy.sh` 仅在两者同时存在时校验并复制到 current release，避免现有 API 流水线被 Pingora 构建依赖影响。发布包包含 Pingora 时，API deploy 会在提升 release 前读取 `systemctl cat genarrative-pingora-gateway.service` 和其 `EnvironmentFile`，拒绝 direct-entry `CAP_NET_BIND_SERVICE`、拒绝非 `127.0.0.1:18081` 的 shadow listen、拒绝 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，确认仍是本机 shadow 高端口后才切换 current；切换后执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，让 shadow / canary 机器加载同一份 current release 网关二进制。该自动拉起不会启用公网 `80/443` 直连入口；已经进入 direct-entry 状态的机器应走正式直连 runbook 或先回退到 shadow。`npm run check:production-api-release` 必须同时验证默认 API release 不登记 Pingora，以及显式 `--include-pingora-gateway --skip-pingora-gateway-build` 时发布包包含 `pingora-gateway`、`pingora-gateway.sha256` 并写入 manifest。
+- 决策补充：生产健康巡检的显式 `--timeout-ms`、`--slow-ms`、`GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS` 和 `GENARRATIVE_HEALTH_PATROL_SLOW_MS` 必须是正整数，非法值直接失败，不静默回退默认 `5000ms` / `3000ms`。Pingora canary live 的 `--timeout-ms` / `GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS`、direct live 的 `--timeout-ms` / `GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS`、canary access log 对账的 `--since-lines` / `GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES` 也必须正整数。Pingora direct live 和 release readiness 读取的直连布尔 env 必须严格解析，只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败，避免 `REQUIRE_WSS_UPGRADE`、preflight 开关或 `SKIP_WSS` 因拼写错误被当成 false。canary live 的 base URL、prefix、Host、额外 path 和 timeout 不能包含换行或 NUL；脚本必须在发起 canary 请求前失败，避免污染参数进入 URL、Host header 或 JSON 输出。canary access log 对账的日志路径、prefix、必需路径、tail 行数以及日志行中解析出的 URI / path 也不能包含换行或 NUL；脚本必须失败并给出对应参数或日志行诊断，不能把污染值写入 JSON 对账输出。direct live 的 HTTPS / HTTP base URL、Host、redirect Host、probe token、额外 path、SpacetimeDB 数据库名、access log 路径、timeout 和布尔 env 都不能包含换行或 NUL；脚本必须在发起 HTTPS / HTTP / WSS 请求前失败，避免污染参数进入请求头、URL、日志对账或 JSON 证据。Pingora 切换窗口调整巡检、live smoke、日志对账阈值或直连布尔开关时，把参数解析失败视为配置错误，而不是继续执行检查。
+- 决策补充：即使不打包 Pingora 二进制，API release 也必须随包携带 Pingora release readiness 聚合门禁、直连启用 / 回退 / preflight / live smoke / current release 自审脚本、直连彩排状态脚本，以及 `deploy/systemd/`、`deploy/pingora/` 支撑配置；`pingora-direct-enable.sh` 和正式 cutover runbook 默认从 `/opt/genarrative/current` 推导这些路径，启用前 release readiness 基础门禁和启用后 `--require-direct` 复核也必须调用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs`，切换窗口不得依赖 Jenkins 工作区或目标机源码 checkout。API release 还必须携带 `build/<version>/scripts/deploy/production-api-deploy.sh` 和同目录 `maintenance-on.sh` / `maintenance-off.sh`；`Genarrative-Api-Deploy` 只能复制并执行 build 产物内的 deploy 脚本，禁止继续执行部署工作区根部脚本，避免 workspace 中的旧脚本掩盖发布包布局缺陷。`production-api-deploy.sh` 对数据库备份脚本、健康巡检脚本和 Pingora 直连依赖都执行 fail-fast，发布产物缺失时保持维护模式并停止部署，不再从部署工作区兜底复制；API deploy 必须要求 `--release-root`、`--current-link`、`--api-env-file` 使用绝对路径，且 `--version` 必须以数字或字母开头并拒绝点目录，再先写 `${RELEASE_ROOT}/.${VERSION}.staging.$`，全部复制完成后再用非合并语义提升为 `${RELEASE_ROOT}/${VERSION}`，并用固定替换语义切换 current 符号链接，同版本 release 已存在、提升前竞态出现或 current 路径不是符号链接时拒绝覆盖 / 合并，失败时清理 staging 且不留下正式 release；`npm run check:production-api-release` 与 `npm run check:production-api-deploy` 必须进入 `check:pingora-release-readiness` 聚合门禁，前者用临时 `CARGO_TARGET_DIR` 和假 `api-server` release binary 验证 `build-production-release.sh --component api-server --skip-api-build` 产物自包含，后者用临时 release 和 fake `systemctl` / `curl` 验证从发布产物内执行 deploy 脚本后 current release 自包含，并覆盖缺少备份脚本、健康巡检脚本、release readiness 聚合门禁脚本、current release 自审脚本、直连彩排状态脚本、direct live smoke 脚本、相对 release root / current link / api env file、点目录或点开头 version、既有 release 目录、目录型 current 或提升前 release 目录竞态时的失败维护模式。
+- 决策补充：正式直连 runbook 在采集状态快照前必须先执行 current release 自审：`/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`。该脚本只读检查发布包自包含、`pingora-gateway` 可执行，以及 systemd `ExecStart` 是否指向 current release 网关二进制；失败时应先修发布包、Jenkins 归档过滤、deploy 复制或 systemd 指向，再继续切换。
+- 决策补充：直连前的 dev / release 彩排状态使用 `/opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs --release-root /opt/genarrative/current --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical`。该脚本只读读取 health patrol env、Pingora env、`systemctl`、`ss -H -ltnp`、realpath canary 配置和 current release 自审结果；`nginx` 期望模式要求公网 `80/443` 仍由 Nginx 监听，Pingora 只在 `127.0.0.1:18081` shadow，realpath canary 在 `127.0.0.1:18083`，不会写 `/etc`、reload systemd 或修改 Nginx / Pingora。
+- 决策补充：Pingora 切换证据链正式纳入 `npm run check:pingora-current-release-audit`、`npm run check:pingora-cutover-status-snapshot`、`npm run check:pingora-cutover-evidence-bundle`、`npm run check:pingora-cutover-command-evidence`、`npm run check:pingora-cutover-evidence-verify`、`/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs`、`/opt/genarrative/current/scripts/ops/pingora-cutover-status-snapshot.mjs`、`/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 与 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs`。状态快照按 `pre-cutover`、`post-enable`、`post-rollback` 三个阶段输出只读 JSON evidence，收录 `summary`、`healthPatrolEnv`、`pingoraEnv`、`releaseArtifacts`、`systemd` 和 `checks`；直连 runbook 的三个证据包阶段都显式透传绝对路径 `--output-root` 和 `--require-pingora-gateway`，让 `checks.current-release-audit.details` 同步归档 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果；证据包脚本把快照 JSON、stdout、stderr、命令记录和 manifest 写入 `--output-root` 下的新证据目录，manifest 对已生成 snapshot、direct live、stdout / stderr、命令记录和 parse-error 文件记录 `path`、`sizeBytes` 与 `sha256`；每个阶段证据目录生成、复制或归档后，都必须用随包 verifier 按 `manifest.files` 只读复核文件存在、大小和 sha256，路径逃逸、符号链接证据目录、非目录证据路径、缺文件、大小漂移或 sha256 漂移都应失败。命令证据脚本把 direct enable apply / rollback apply 的真实 stdout、stderr、退出码、脱敏命令记录和 manifest 写入同一证据根目录，命令记录同时保留脱敏后的可读命令和结构化 `executable` / `args[]`，manifest 对 `command.stdout.txt`、`command.stderr.txt` 和 `command-record.json` 同样记录 `path`、`sizeBytes` 与 `sha256`，便于切换窗口后复核归档文件未漂移；runbook 必须在命令证据生成后立即用随包 verifier 验真 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>`，再继续 health patrol 切换、回退后 env 复核或最终总审计，且 `--phase` 只允许 ASCII 字母、数字、点、下划线和短横线，非法阶段名直接失败，不做隐式清洗。自审和快照只读采集，证据包只写归档目录且不覆盖既有文件，证据验真脚本只读 manifest 和证据文件，命令证据脚本只执行 `--` 后面的真实命令并归档输出，证据目录权限固定为 `0750`，证据文件权限固定为 `0640`，这些脚本都不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora；probe token 和其他 env 敏感值只允许以是否存在或 `<redacted>` 的形式进入证据链，聚合门禁真实执行日志、dry-run plan、cutover runbook、直连启用脚本 direct live 命令日志、直连回退脚本 shadow probe 命令日志、gateway smoke 命令日志和证据包命令记录都不得输出 token 原文，状态快照在收录健康巡检、current release 自审等子检查 stdout / stderr 前必须按 env 敏感值脱敏，状态快照、证据包、命令证据和证据验真自测必须确认 token 原文不会进入 stdout、snapshot、manifest、命令记录或子检查输出；正式 runbook 应在 `--fail-on-critical` 下把自审、快照、证据包和 manifest 验真当成阻断证据，避免把发布包 checksum / manifest 漂移、env 漂移、systemd capability 残留、巡检失败或归档文件损坏带入后续阶段。
+- 决策补充：正式直连 runbook 的即时证据 verifier 和最终证据根目录总审计内部复用 verifier 时，都必须使用 `--require-summary-ok`；总审计不能退化成只验 `manifest.files` hash，还要把 `manifest.summary.status=OK` 作为底层 verifier 严格模式的一部分。
+- 决策补充：Pingora 切换命令证据生成端必须在执行前约束真实命令身份：`-- <command>` 本身必须是绝对路径，不能是文件系统根目录；真实命令和每个真实命令参数都不能包含换行或 NUL 字符。正式 runbook 因此直接执行 current release 随包 enable / rollback 脚本绝对路径，禁止用 `node`、`bash`、脚本名或其它 PATH 裸命令名包装。
+- 决策补充：Pingora release readiness、canary access log 对账、direct live、direct preflight 和 cutover evidence bundle 的显式日志 / env 文件路径必须是绝对路径且不能是文件系统根目录。`--live-nginx-access-log`、`--live-pingora-access-log`、`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、canary 对账脚本的 `--nginx-log-file` / `--pingora-log-file`、direct live 的 `--pingora-access-log`、direct preflight 的 `--env-file` 与 evidence bundle `--run-direct-live` 的 `--direct-pingora-access-log` 都不能指向 `/`，避免切换窗口把日志扫描或 env 复核误绑到根目录。证据包 `--run-direct-live` 的 direct URL、Host、probe token、SpacetimeDB 数据库名、Pingora access log 路径和 access log tail 行数还必须在配置层拒绝换行或 NUL，避免污染参数进入状态快照或 direct live 子命令后才失败。
+- 决策补充：证据根目录总审计按 `--require-phase` 查找阶段证据时，只接受不带 `manifest.commandName` 的状态快照证据包；enable / rollback apply 的命令证据只能通过 `--require-command`、`--require-command-executable` 和 `--require-command-arg` 审计，不能冒充同名 phase 的阶段证据。
+- 决策补充：直连回退的 Nginx smoke 不能只看 `curl --fail` / HTTP 200。`pingora-direct-rollback.sh` 支持 `--nginx-smoke-expect-body <片段>`；正式 cutover runbook 必须显式传入切换前真实 Nginx 入口和响应片段，不再默认假定 `/healthz` 会返回 `"ok":true`。dev 真实直连验证确认公网 Nginx 首页 `https://dev.genarrative.world/` 与 `<!doctype html>` 是可用 smoke，而固定 `http://127.0.0.1/healthz` / `"ok":true` 可能误卡回退或验证到错误入口。
+- 决策补充：`check-pingora-release-readiness.mjs --require-direct` 是启用后直连复核，不再强制要求 `--direct-preflight-check-ports-free`；`--dry-run-cutover` 和启用前 preflight 仍必须要求端口空闲，用于证明 Nginx、Gitea 等占用 `80/443` 的进程已释放。dev 真实 direct 接管 `80/443` 后，启用后复核应看到端口由 Pingora 占用而不是空闲。
+- 决策补充：Pingora 网关行为变更必须运行 `npm run check:pingora-gateway-smoke`；该脚本用临时 mock 上游验证静态路由、API 代理头、请求体限制、429 接流保护、上游断连 JSON 错误、维护模式和 SpacetimeDB WebSocket Upgrade，避免只靠单元测试遗漏接流路径。代理路径的上游失败必须返回稳定 JSON code，例如 `GATEWAY_UPSTREAM_ERROR` / `GATEWAY_UPSTREAM_TIMEOUT`。静态协商缓存、非读取方法和 Range 边界请求必须用固定 `X-Request-Id` 反查 Pingora access log，确认 `304`、`405`、`206`、`416` 这些本地响应状态也可进入切换证据链。
+- 决策补充：Nginx 到 Pingora 的 canary 先采用 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 的前缀手动入口，Server-Provision 只安装 snippet，不默认 include；启用时必须替换 probe token、限制来源，并用 `X-Genarrative-Nginx-Handoff: pingora-canary` 与 Pingora shadow 日志证明请求确实经过 handoff。
+- 决策补充：Pingora shadow / canary 必须配置可落盘 access log，默认示例为 `/var/log/genarrative/pingora-gateway.access.log`；Server-Provision 创建 `/var/log/genarrative`、安装 `deploy/logrotate/genarrative-pingora-gateway`，并让 systemd 沙箱允许写该目录。canary 对照时同时看 Nginx access log、Pingora access log 与 tracing 日志。
+- 决策补充：Pingora 前缀 canary live 通过后不能只看 `X-Genarrative-Nginx-Handoff` 响应头，还必须运行 current release 随包 `scripts/check-pingora-canary-access-log-parity.mjs` 按 `request_id` 对照 Nginx handoff access log 和 Pingora access log，确认 method/status/path 没有漂移。Nginx canary exact `/healthz` 按真实 snippet 映射到 Pingora shadow `/__genarrative_pingora/healthz`，其余 canary 前缀路径按 rewrite 后路径比对；该脚本只读日志，不修改日志、不 reload Nginx 或 Pingora。
+- 决策补充：Pingora 启动必须 fail fast 拒绝不安全配置。`GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN` 不能是占位值或短 token；开启 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true` 时必须同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true` 并确认前置代理已清洗 `X-Forwarded-For`；接流保护 `BURST>0` 时对应 `RATE_PER_SECOND` 不能为 `0`。当前接流保护默认只覆盖单进程单实例；`GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 时，必须先落地共享限流 / 共享并发保护层并设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则网关启动和 direct preflight 都要失败；关闭网关保护后的多实例必须明确由前置 Nginx / LB 承担全局接流保护。
+- 决策补充：Pingora Nginx canary snippet 变更必须运行 `npm run check:nginx-pingora-canary`；该脚本静态校验本机来源限制、handoff 响应头、probe token 占位、前缀 rewrite、低缓冲和 SpacetimeDB WebSocket Upgrade。目标 agent 或 CI 有 Nginx 时必须运行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`，把 snippet 包进临时 `server {}` 强制执行 `nginx -t`。
+- 决策补充：Pingora 与 Nginx 的核心路由 parity 以 `deploy/pingora/nginx-route-parity.matrix.json` 为共享检查输入；涉及 Nginx 模板、Pingora 路由、限流分组或路由文档时必须同步更新矩阵，并运行 `npm run check:pingora-route-parity` 与 `cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix`。Rust 单测读取同一份矩阵验证 `classify_path`、body limit 和接流保护分组，Node 检查同时覆盖生产 / 开发 Nginx 模板和试点文档片段。
+- 决策补充：Pingora 前缀 canary 在目标 Nginx 中人工 include 并 reload 后，必须运行 `npm run check:pingora-canary-live`；该脚本只读访问 `__genarrative_pingora_canary` 前缀下的 healthz、代表性 API、SpacetimeDB identity、静态资源和拒绝入口，并强制校验 `X-Genarrative-Nginx-Handoff: pingora-canary`，避免只通过 snippet 静态检查却没有证明真实 handoff 链路可用。
+- 决策补充：Pingora release readiness 分为源码全量门禁和 current release runtime-only 门禁。源码 checkout / CI / 构建环境继续运行默认 `check-pingora-release-readiness.mjs`，覆盖 Cargo、npm、Docker、Nginx 静态 / 真机校验和发布包构建烟测；目标机 `/opt/genarrative/current` 的启用前基础门禁和启用后 `--require-direct` 复核必须调用随包 `scripts/check-pingora-release-readiness.mjs --release-runtime-only`，只执行 current release 自审、启用前直连彩排状态、live canary、access log 对账、direct preflight、health patrol env 复核和 direct live smoke。未带 `--require-direct` 时 runtime-only 必须自动运行随包 `scripts/ops/pingora-direct-rehearsal-status.mjs --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical`，确认公网 `80/443` 仍由 Nginx 接流、Pingora shadow `127.0.0.1:18081`、realpath canary `127.0.0.1:18083` 和 current release 自审均通过；启用后 `--require-direct` 复核不再要求 Nginx 接公网彩排状态，改为检查 direct preflight、health patrol 直连模式和 direct live smoke。API release / current release 必须随包携带 `scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs`、canary access log 对账脚本、直连彩排状态脚本和 direct preflight / live 子脚本；runtime-only 模式不得依赖源码 checkout、npm project root、Docker 或目标机 Nginx 静态校验。
+- 决策补充：Pingora 直连静态响应必须显式写入缓存头。HTML、目录 index 和 SPA fallback 默认 `Cache-Control: no-cache`；`/assets/*` 与 `/admin/assets/*` 中带 Vite 指纹文件名的资源默认 `Cache-Control: public, max-age=31536000, immutable`；非指纹静态和 ACME challenge 默认 `no-cache`。三档由 `GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL`、`GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL` 和 `GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL` 覆盖，配置值不能包含换行或 NUL；`npm run check:pingora-gateway-smoke` 必须覆盖这些缓存头，避免直连后入口 HTML 被长期缓存或指纹资源失去长期缓存收益。
+- 决策补充：Pingora 直连同一公网 IP 上的多域名时，必须先保住非主站域名的 Host 语义。dev 上 `dev.genarrative.world` 与 `git.genarrative.world` 共用 `80/443`，因此 direct env 必须配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world` 和 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`，命中 Gitea Host 的请求整站代理到 Gitea，且不走应用维护页、API body limit 或网关接流保护。当前 Pingora TLS listener 只加载一组 cert/key；同时接管 `dev.genarrative.world` 和 `git.genarrative.world` 前，证书必须覆盖两个域名，不能使用单域名 SAN 证书。
 ## 2026-06-11 资产计费边界改为 fail-closed 并补偿退款
 
 - 背景：图片 / 资产生成入口曾在钱包或 SpacetimeDB 预扣费连通性异常时允许继续生成，且失败后同步退款如果遇到 SpacetimeDB 短暂不可用缺少本地补偿；拼图首图后台任务还使用 api-server 进程内 HashSet 互斥，多实例下不能防重复。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 983c77463..fb61d2332 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -1,4 +1,4 @@
-# 踩坑与排障记录
+# 踩坑与排障记录
 
 > 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。
 
@@ -15,6 +15,55 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## Pingora 直连 80/443 不能只改 env
+
+- 现象：`/etc/genarrative/pingora-gateway.env` 已把 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `HTTP_REDIRECT_LISTEN` 改到 `0.0.0.0:443` / `0.0.0.0:80`，但 `genarrative-pingora-gateway.service` 启动失败，日志出现低端口绑定权限错误。
+- 原因：默认 service 用非 root `genarrative` 用户运行，并且主模板为了保持 shadow 安全边界不带 `CAP_NET_BIND_SERVICE`。低端口直连必须通过显式 systemd drop-in 单独授予 capability；同时 Certbot 私钥默认未必允许 `genarrative` 读取，Nginx 也可能仍占用 `80/443`。另一个常见误区是 API release 只带 `pingora-direct-enable.sh` / rollback 壳脚本，却漏带 `pingora-current-release-audit.mjs`、`pingora-direct-rehearsal-status.mjs`、`check-pingora-direct-preflight.mjs`、`check-pingora-direct-live.mjs`、`deploy/systemd/`、`deploy/env/` 或 `deploy/pingora/`，导致从 `/opt/genarrative/current` 启用时依赖 Jenkins 工作区、源码 checkout 或 `/etc` 里某份参考模板；或者 release 已经包含新版 `pingora-gateway`，但已运行的 shadow / canary / direct service 没有随 `current` 链接切换重启，仍在跑旧二进制。Server-Provision 安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 的 drop-in 只用于人工审阅和显式覆盖；直连启用脚本默认必须读取 current release 随包 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，否则旧 `/etc` 模板会掩盖发布包缺失。API deploy 脚本本身也不能继续用部署工作区根部的 `scripts/deploy/production-api-deploy.sh`，否则 Jenkins workspace 里的脚本会掩盖 `build/<version>` 发布包缺少 deploy / maintenance 同目录脚本的问题；备份脚本、健康巡检脚本和 env 示例目录同样不能从部署工作区兜底，切换命令证据脚本也不能从部署工作区兜底，否则 current release 会和上游构建归档漂移。Pingora 直连依赖、备份脚本、巡检脚本、env 示例目录和 API deploy 执行入口都必须来自上游发布产物；随包 `api-server.sha256` 和可选 `pingora-gateway.sha256` 也必须复制进 current release，供随包 current release 自审校验二进制；随包 `deploy/pingora/pingora-gateway.env.example` 也不能只检查存在，还要保持 gzip-only、不信任 XFF、前置代理确认关闭、接流保护开启和空 probe token 这些生产安全默认值；`production-api-deploy.sh` 发现缺失时应 fail-fast 并保持维护模式，不应从部署工作区兜底补齐；所有 API 发布包都必须携带 `release-manifest.json` 且登记 `api-server` artifact，发布包包含 Pingora 时还必须登记 `pingora-gateway` artifact，否则 deploy 应在切换 current 前失败；deploy 必须要求 release root、current link 和 api env file 都是绝对路径，release version 以数字或字母开头并拒绝点目录，再先写 staging release，全部复制完成后用非合并语义提升为正式 release，失败时清理 staging 且不留下正式 release，同版本 release 已存在、提升前竞态出现或 current 路径不是符号链接时拒绝覆盖 / 合并，避免旧文件混入 current；发布包包含 Pingora 时，deploy 必须先确认 systemd 最终配置没有 direct-entry `CAP_NET_BIND_SERVICE`、env 仍是 `127.0.0.1:18081` shadow 且未配置 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，再提升 release、切换 current 并 `restart` Pingora shadow；配置不安全时必须在切换 current 前失败并保持维护模式。
+- 处理：确认真实 TLS 证书和 redirect env 已写入 `/etc/genarrative/pingora-gateway.env`、service 模板和 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含这份 env、当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都能读取证书链 / 私钥、current release 的 `pingora-gateway` 已存在且可执行、Nginx 或其它进程已释放 `80/443` 后，先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成只读 JSON runbook，并逐条审阅 Host 与回退巡检入口确认、current release 自包含自审、current release preflight、启用前基础 readiness、direct enable dry-run、direct enable apply、启用后 `--require-direct` 复核、rollback dry-run、rollback apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；runbook 只用于审阅，不修改系统。正式 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 或回退 smoke 各自验证到不同入口；同时必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 把现场巡检入口覆盖成仓库默认值；如需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文。随后先执行 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`，再 dry-run `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status`，最后执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，由脚本先跑 direct preflight，再安装 drop-in、reload systemd、重启 Pingora，并用 `systemctl cat` 核验 capability 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板里的 current release `pingora-gateway`、用 `systemctl is-active` 确认服务 active，再以 JSON 模式执行 direct live smoke，验证 HTTPS / HTTP redirect / ACME / WSS 101 和 Pingora access log request_id 落盘，并要求 `direct-access-log` 结构化结果 `matchedCount == checked`、`missingCount=0`、`mismatchCount=0`；如果 direct live 退出 0 但缺少该结构化证据，也必须视为启用失败。直连启用后同步调整 `/etc/genarrative/health-patrol.env`：设置 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，本机打 `127.0.0.1` 时设置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`，否则巡检会继续按 Nginx 模式误报。验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 或 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`；回退脚本先跑 `nginx -t`，通过后才移除 drop-in、reload systemd、重启 Pingora，并用 `systemctl cat` 核验 capability 已移除、用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板里的 current release `pingora-gateway`，随后 reload Nginx、确认 Nginx service 仍为 active，并用 curl smoke URL 证明公网入口已回到 Nginx；回退 smoke URL/body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`；回退脚本 `--apply` 不允许省略 `--reload-nginx` 或 `--nginx-smoke-url`，当 smoke URL 指向本机地址时必须同时提供 `--nginx-smoke-host <域名>`，且 host 值不能包含 URL、路径或查询；回退后把 health patrol gateway mode 改回 `nginx`，恢复切换前 public base URL / Host，并用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs --env-file /etc/genarrative/health-patrol.env --expected-gateway-mode nginx --expected-public-base-url <切换前Nginx巡检入口> --require-empty-public-host` 复核；若切换前 Nginx 巡检需要 Host 覆盖，则把 `--require-empty-public-host` 换成 `--expected-public-host <切换前Host>`。若 env 已在回退命令前切回 Nginx，也可给 rollback 脚本追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 让它在 Nginx smoke 后自动复核；切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若要同时证明 Pingora shadow 高端口仍活着，追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应为 `gateway=pingora-shadow`。
+- 处理补充：不要直接 chmod `/etc/letsencrypt/live` 或 `archive` 来让 Pingora 读取证书；Certbot live 路径通常是 symlink，即使 `stat -L` 看起来是普通文件，父目录权限也会让非 root `genarrative` 用户不可达。先用随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-tls-cert-sync.mjs --apply --source-cert-file /etc/letsencrypt/live/<域名>/fullchain.pem --source-key-file /etc/letsencrypt/live/<域名>/privkey.pem --target-dir /etc/genarrative/pingora-tls/<域名>` 把证书同步到 Pingora 私有目录，再让 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE` 指向 `/etc/genarrative/pingora-tls/<域名>/fullchain.pem` 和 `privkey.pem`。脚本默认 dry-run，`--apply` 才写入，目标目录默认 `root:genarrative 0750`，文件默认 `root:genarrative 0640`，并拒绝符号链接目标目录或目标文件。
+- 处理补充：不要在切换窗口手工编辑 `/etc/genarrative/health-patrol.env` 的三项网关变量；使用 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply --env-file /etc/genarrative/health-patrol.env --gateway-mode pingora-direct --public-base-url <直连HTTPS入口> --public-host <域名>` 切到直连，回退前用同一脚本传 `--gateway-mode nginx --public-base-url <切换前Nginx巡检入口>` 并按切换前记录选择 `--clear-public-host` 或 `--public-host <切换前Host>`。脚本只改 gateway mode / public base URL / public Host，并立即复用随包 env 复核脚本，减少空 Host 和旧值残留；生产巡检、env 复核和 env 切换脚本读取的布尔 env 都必须是明确布尔值，非法值直接失败，不能把拼写错误当成 false；env 复核脚本的 `--env-file` 与 env 切换脚本的 `--env-file` / `--check-script` 必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。Node 22 已内置 `--env-file` 启动参数，直接用 `node script.mjs --env-file ...` 或 shebang 执行 `.mjs --env-file ...` 都可能让 Node 抢走业务参数；所有这类命令都必须写成 `node -- script.mjs --env-file ...`，或通过已内置 `node --` 的 npm script 执行。
+- 踩坑补充：health patrol env 切换脚本必须先复核权限固定为 `0600` 的临时目标 env 再写真实文件，真实 env 原子替换时保持原文件权限和 owner/group；如果随包 env 复核脚本失败，`--apply` 应失败且真实 env 保持原样，避免“切换脚本失败但巡检配置已半改”的状态。`--apply` 的 `--env-file` 必须直接指向真实普通文件，不能传符号链接；如果 `/etc/genarrative/health-patrol.env` 是链接，先确认真实目标路径后再传给脚本，避免替换链接本身或写入非预期目标。
+- 踩坑补充：直连启用脚本的 `--preflight-script`、`--direct-live-script`、`--current-release-audit-script`、`--template-path`、`--service-unit-path`、`--dropin-path` 和 env 文件参数都必须使用绝对路径；不要在切换窗口传相对脚本路径，否则会把 current release、Jenkins 工作区或现场 cwd 混在一起。`--apply` 会在安装 direct-entry drop-in 前确认 current release 自审、direct preflight 和 direct live smoke 脚本存在，缺脚本时应先修发布包或复制链路，不要手工改成工作区相对路径绕过。启用脚本还会在任何自审、preflight、drop-in 写入或 systemctl 前拒绝 service、路径、URL、Host、probe token、access log、数据库名、tail 行数和 timeout 参数中的换行或 NUL 字符；遇到这类失败先修 runbook 参数来源或现场 env，不要手工绕过脚本。启用脚本还会拒绝符号链接形式的 drop-in 目录或 drop-in 目标文件，以及已存在但不是普通文件的目标；如果现场 systemd 目录被软链改写，应先修正真实路径，不要让脚本把低端口 capability 写入非预期位置。回退脚本 `--apply` 同样会在 `nginx -t` 和删除 drop-in 前拒绝 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override 中的换行或 NUL 字符，并拒绝符号链接 drop-in 目录 / 目标以及非普通 drop-in 目标；如果现场路径或参数异常，应先修正 systemd 路径、runbook 参数或现场 env，不要手工删 drop-in、绕过 `nginx -t` 或把删除 symlink 当成已回退真实低端口能力。回退脚本覆盖 `--nginx-binary` 或 `--curl-binary` 时也不要传 `./nginx`、`tools/curl` 这类相对路径；裸命令名可以走 `PATH`，路径形式必须使用绝对路径。`--nginx-smoke-url` 必须带 `http://` 或 `https://`，不要只写 host/path，否则脚本会在移除 drop-in 前失败。
+- 踩坑补充：回退到 Nginx 后不要只把 `curl --fail` / HTTP 200 当作 Nginx 已接回的证据；正式 runbook 必须给 rollback dry-run / apply 显式传切换前真实 Nginx smoke URL 和响应体片段，例如 `--nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`。不要继续用固定 `/healthz` 与 `"ok":true`，否则要么误卡回退，要么只验证到了错误入口。
+- 踩坑修正：上述 `/healthz` 与 `"ok":true` 只能算旧示例，不再是正式 runbook 默认。dev 真实直连 `80/443` 测试确认回退 smoke 必须从切换前真实 Nginx 入口取样，例如 `https://dev.genarrative.world/` 与 `<!doctype html>`；固定 `http://127.0.0.1/healthz` 可能返回 301/404 或命中错误 vhost。回退前还必须把 `/etc/genarrative/pingora-gateway.env` 从 direct 低端口配置恢复为 shadow 高端口配置，否则回退脚本移除 capability 后重启 Pingora 可能继续按 `80/443` 配置失败；恢复 shadow 时不能只清 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，也必须清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE`，避免留下证书路径但无 TLS listener 的半直连 env。
+- 踩坑补充：直连彩排状态脚本不是修复动作。`node -- /opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs --release-root /opt/genarrative/current --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical` 只读检查公网端口归属、health patrol 模式、Pingora shadow、realpath canary、systemd 和 current release 自审；如果它报 `CRITICAL`，应先修发布包、端口归属、canary 配置、health patrol env 或 systemd 指向，不要把它当成会自动启用 canary、停止 Nginx 或修复 current release 的脚本。
+- 踩坑补充：Pingora current release 自审和切换证据链都不是修复动作，`npm run check:pingora-current-release-audit` / `scripts/ops/pingora-current-release-audit.mjs` 只负责只读确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、release manifest 登记了当前要接流的 Pingora 产物、`pingora-gateway` 可执行和 systemd `ExecStart` 指向；`npm run check:pingora-cutover-status-snapshot` / `scripts/ops/pingora-cutover-status-snapshot.mjs` 只负责输出 `pre-cutover`、`post-enable`、`post-rollback` 三阶段只读 JSON evidence，并在直连 runbook 中通过 `--require-pingora-gateway` 把上述自审结果收录到 `checks.current-release-audit.details`；快照还必须确认 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 精确包含本次 `--pingora-env-file`，否则 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile=false` 且标记 `CRITICAL`，避免证据包读到一份 env、真实服务读另一份 env。正式切换窗口用 `scripts/ops/pingora-cutover-evidence-bundle.mjs` 把快照 JSON、stdout、stderr、命令记录和 manifest 写入 `--output-root` 下的新证据目录，证据包 manifest 必须记录已生成 snapshot、direct live、stdout / stderr、命令记录和 parse-error 文件的 `path`、`sizeBytes` 与 `sha256`，便于归档后复核；证据目录生成、复制或归档后必须用随包 `scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <bundleDir>` 做只读验真，确认 `manifest.files` 登记的文件未缺失、大小未漂移、sha256 未漂移，且证据目录不是符号链接或非目录；三阶段证据分别验真后，还必须用随包 `scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback` 做只读总审计，自动选择每个阶段最新 bundle 并复用 verifier，缺阶段、最新证据损坏、坏 manifest 或符号链接条目都应失败。direct enable apply / rollback apply 必须通过 `scripts/ops/pingora-cutover-command-evidence.mjs` 包装真实脚本，单独保存命令 stdout、stderr、退出码、脱敏命令记录和 manifest，runbook 必须显式传绝对路径 `--output-root`，且该路径不能是文件系统根目录、符号链接或包含换行 / NUL 字符；命令记录必须同时保留脱敏后的可读命令和结构化 `executable` / `args[]`，命令证据 manifest 也必须记录 `command.stdout.txt`、`command.stderr.txt` 和 `command-record.json` 的 `sizeBytes` 与 `sha256`；命令证据生成后也要立即把 stdout 中的 `bundleDir` 填入随包 verifier 的 `<enable-apply-bundle-dir>` 或 `<rollback-apply-bundle-dir>` 占位符做只读验真，不能只等最终根目录总审计才发现 command-record 或 stdout/stderr 归档漂移。启用后证据包必须额外运行随包 direct live smoke，并写入 `direct-live.json`、`direct-live.stdout.txt`、`direct-live.stderr.txt`、`direct-live-command.json` 和 manifest summary 的 `directLiveStatus`，让 Pingora access log `request_id` 反查结果可复盘；`direct-live.json` 的 `direct-access-log` 结果必须保留扫描行数、匹配数量、缺失明细以及 method/path/status 漂移明细，不要只保留 count 或依赖 stderr。证据包 manifest summary 还必须包含 `directLiveAccessLog` 摘要；如果 direct live JSON 缺少 `direct-access-log` 结构化结果，整包应记为 `CRITICAL`。若 snapshot 或 direct live stdout 解析失败，必须保留 `snapshot-parse-error.txt` 或 `direct-live-parse-error.txt` 并在 manifest / 最终 stdout 中给出路径；不要只截图或复制 `pingora-direct-enable.sh` / release readiness 的终端输出当作直连证据。证据阶段名只能使用 ASCII 字母、数字、点、下划线和短横线，非法 `--phase` 会直接失败，不会被清洗后继续落盘；自审、状态快照和证据包的 `--release-root` 都不能是文件系统根目录，状态快照的 `--health-patrol-env-file` / `--pingora-env-file` 以及证据包所有显式路径参数也不能是文件系统根目录，状态快照自身还必须拒绝带换行或 NUL 的 release/env 路径，并在执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前复核子命令参数，证据包执行状态快照或 direct live 子命令前也必须拒绝任何带换行或 NUL 字符的子命令参数，避免污染后的结构化 `args[]` 先进入正式证据再等总审计兜底，`--output-root` 及其已存在上级路径不能是符号链接，已存在的 `--output-root` 必须是真实目录，路径异常时会在执行状态快照前失败，避免把证据写入非预期软链目标；current release 自审、状态快照和证据包的显式 `--timeout-ms` 及对应 env 必须是正整数，生产健康巡检的 `--timeout-ms`、`--slow-ms`、`GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS` 和 `GENARRATIVE_HEALTH_PATROL_SLOW_MS`，canary / direct live smoke 的 `--timeout-ms` 及对应 env，canary access log 对账的 `--since-lines` 及对应 env 也必须是正整数，直连 live / release readiness 的布尔 env 也必须是明确布尔值，非法值都会失败，不再静默回退默认值或 false。自审、快照、证据包、证据验真和证据总审计脚本都不修改 `/etc`、systemd、Nginx 或 Pingora；命令证据脚本只执行 `--` 后面的真实命令并归档输出，不自行理解 systemd / Nginx；证据包和命令证据目录必须是 `0750`，证据文件必须是 `0640`，且不能覆盖既有文件；probe token 和其他 env 敏感值只能记录是否存在或显示 `<redacted>`，不能把 env 原文写入终端执行日志、gateway smoke / direct live / direct rollback shadow probe 命令日志、stdout、snapshot、manifest、命令记录或子检查 stdout / stderr；如果自审、快照、direct live 或总审计证据里出现 `CRITICAL`，应先修发布包、Jenkins 归档过滤、deploy 复制、env、systemd capability、直连入口、巡检状态或证据归档，再继续下一阶段，不要把自审、快照或证据包当成可自动修复的烟测。
+- 踩坑补充：直连 Pingora 后不要让静态缓存头继续依赖框架默认值。HTML、目录 index 和 SPA fallback 必须保持 `Cache-Control: no-cache`，否则旧入口页可能长期引用已经切换的 chunk；带 Vite 指纹的 `/assets/*` 和 `/admin/assets/*` 才能使用 `public, max-age=31536000, immutable`；普通非指纹静态和 ACME challenge 继续保守 `no-cache`。如果需要临时覆盖 `GENARRATIVE_PINGORA_GATEWAY_*_CACHE_CONTROL`，值不能包含换行或 NUL，修改后必须跑 `npm run check:pingora-gateway-smoke` 确认 HTML、普通静态和指纹资源三类响应头没有漂移。
+- 踩坑补充：直连 Pingora 后也不能只验证整文件静态读取。浏览器、媒体探测和线上签名 URL 排障都可能使用 `Range: bytes=`；Pingora 静态文件必须支持单段 range 的 `206 + Content-Range` 和越界 range 的 `416 + Content-Range: bytes */<len>`，同时给静态响应写入 `Accept-Ranges: bytes`。`If-Range` 不能被忽略：日期匹配才继续给局部内容，旧日期或弱 ETag 校验器应回完整 `200`，避免客户端拿旧校验器拼接错误文件片段。`206`、`304`、`416` 不应被 gzip 压缩，否则 `Content-Range` 指向的字节区间会和实际响应体不一致。多段 range 暂按完整文件处理，不要在切换窗口临时拼 multipart 响应。
+- 踩坑补充：直连 Pingora 后不要让静态路由接受非读取方法。`POST /assets/app.js` 或 `POST /some/deep/link` 这类请求不应返回静态内容；命中静态候选时返回 `405 + Allow: GET, HEAD`，缺失文件仍返回 `404`。修改静态路由后跑 `npm run check:pingora-gateway-smoke`，确认 405 没有被压缩或误写成 JSON 代理错误。
+- 踩坑补充：静态响应不是代理路径，也必须有 access log 证据。修改静态协商缓存、方法限制或 Range 行为后，smoke 要用固定 `X-Request-Id` 反查 Pingora access log 中同一行的 `path`、`status` 和 `proxy_target=Local`，至少覆盖 `304`、`405`、`206`、`416`；否则直连切换证据包可能只能证明 API / WSS 代理路径，排查浏览器缓存或媒体 Range 问题时缺少本地响应状态证据。
+- 踩坑补充：直连 live smoke 不能只证明根 HTML 返回 `200`。正式发布包的首页通常会引用 `/assets/` 或 `/admin/assets/` 构建产物，direct live 应自动发现静态资源，验证静态缓存 / 校验头、`HEAD` 头响应、`If-None-Match` / `If-Modified-Since` 304 和 `Range: bytes=0-0`，并纳入 access log method/path/status 对账；如果首页存在 Vite 指纹资源，还必须额外证明 `Cache-Control: public, max-age=31536000, immutable` 以及指纹资源 GET / HEAD / 304 / Range 的 access log method/path/status 证据，避免只验证普通 `/assets/app.js` 却漏掉旧 tab chunk 长缓存口径。如果该项显示 skipped，要确认是维护模式、非 HTML，还是发布包首页确实没有资产引用，不要把 skipped 当作已经验证前端静态资源可读。
+- 踩坑补充：不要把 `direct-live.json` 当成只有状态码的摘要。静态 GET / HEAD / 304 / Range 检查必须保留白名单 `headers`，至少能复盘 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`；证据包自测要确认普通静态和 Vite 指纹资源的 `Cache-Control`、`Content-Range` 都被归档。API / WSS 检查不要落原始响应头，避免把认证、Cookie 或上游细节带进切换证据。
+- 踩坑补充：切流证据包不能只把静态头部藏在 `direct-live.json`。`manifest.summary.directLiveStaticHeaders` 必须提升普通静态和 Vite 指纹静态的缓存头、校验头、Range `Content-Range` 和 304 状态摘要，方便切换窗口先扫 manifest 判断证据是否完整；如果 direct live 已输出静态资产结果但摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，证据包会直接记为 `CRITICAL`。遇到摘要缺失或 diagnostics 非空时，应重新生成启用后证据包或修复 direct live / 静态响应头，不要手工改 manifest。
+- 踩坑补充：最终证据根目录总审计必须带 `--require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-phase-pingora-env-shadow post-rollback`，正式 runbook 已默认生成这些参数。`post-enable` 证据包还必须传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包必须传 `--expected-pingora-env-mode shadow`，否则 health patrol 模式正确也不能证明 active Pingora env 姿态正确。若旧 `post-enable` bundle 虽然 `manifest.summary.status=OK` 但没有 `directLiveAccessLog` 或 `directLiveStaticHeaders`，或旧 `post-rollback` bundle 没有 `manifest.summary.pingoraEnvShadow`、没有 `mode=shadow` / `shadowReady=true`、仍残留 `tlsCertFile` / `tlsKeyFile`，总审计也应失败；处理方式是用新版 current release 重新生成对应阶段证据包，不要把旧包混进正式归档。
+- 踩坑补充：最终证据根目录总审计失败时先看 JSON 顶层 `summary`，不要直接在长 `phases[]` / `commands[]` 里翻。`summary.failedItems[]` 会聚合失败阶段、命令、根目录或时间线诊断，`summary.directLiveEvidence[]` 会直接给出 `post-enable` 的 `accessLog.ok/reason` 与 `staticHeaders.ok/reason`；reason 指向缺摘要或字段不完整时，应重新生成启用后证据包，而不是手工补 manifest。
+- 踩坑补充：最终证据根目录总审计命令示例也必须包含五条 `--require-command-executable`，分别绑定 current release 随包 `pingora-direct-enable.sh`、`pingora-health-patrol-env-switch.mjs`、`pingora-gateway-env-shadow-switch.mjs`、`pingora-health-patrol-env-switch.mjs` 和 `pingora-direct-rollback.sh`。不要只写 `--require-command` 和 `--require-command-arg --apply`，否则只能证明有命令证据和参数，不能证明真实执行的是本次 current release 脚本。发布包级 `npm run check:production-api-release` 会同时检查生成 README 和随包 readiness dry-run cutover 输出，若这里失败，先修发布包构建脚本或随包 readiness 脚本，不要只改源码文档。
+- 踩坑补充：直连 Pingora 后也不要只看前端页面和 access log 成功。API 上游必须继续收到 Nginx 口径代理头：`Host`、`X-Forwarded-Host`、配置化 `X-Forwarded-Proto`、TCP 对端 IP 的 `X-Real-IP`，以及追加 TCP 对端 IP 的 `X-Forwarded-For`。`TRUST_X_FORWARDED_FOR` 只用于接流保护 client key；如果误以为它会改变上游 `X-Real-IP` 或覆盖上游 `X-Forwarded-For`，容易造成回调 URL、鉴权来源或日志归因排查漂移。修改代理头逻辑后先跑 `npm run check:pingora-gateway-smoke`，让 mock 上游回显这些头。
+- 踩坑补充：current release 自审开启 `--systemd-show` 时，带换行或 NUL 的 `--release-root` / `--systemd-service` 必须在执行 `systemctl show` 前失败，不能把污染参数写进子命令或后续证据链。遇到这类失败先修 runbook 参数来源，不要用 `--warn-only` 继续采集。
+- 踩坑补充：canary live 的 `--base-url`、`--prefix`、`--host`、`--path`、`--timeout-ms` 和对应 env 如果包含换行或 NUL，必须在发起 canary 请求前失败，不能让污染参数进入 URL、Host header 或 JSON 输出。遇到这类失败先修目标机 env、runbook 参数来源或手工命令，不要用只看 `X-Genarrative-Nginx-Handoff` 的 curl 替代完整 `npm run check:pingora-canary-live`。
+- 踩坑补充：真实路径 canary 不能为了“更像生产”而 include 到生产 `443` server 里写 `/api`、`/v1` 或 `/assets` location；那会覆盖当前 Nginx 正式路由。只能把 `genarrative-pingora-realpath-canary.conf` 作为独立 loopback `server` include 到 `http` 上下文，使用 `127.0.0.1:18083` 和独立 `genarrative-pingora-realpath-canary.access.log` 验证，再用 release readiness 的 `--require-realpath-live` 纳入门禁。
+- 踩坑补充：direct preflight 的 `--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值如果包含换行或 NUL，必须在执行 `systemctl cat`、`sudo -u ... test -r ...`、证书可读检查或端口监听检查前失败。遇到这类失败先修目标机 env 或 runbook 参数来源，不要临时改成手工 systemctl / sudo 命令绕过。
+- 踩坑补充：direct live 的 `--https-base-url`、`--http-base-url`、`--host`、`--redirect-host`、`--probe-token`、`--path`、`--spacetime-database`、`--pingora-access-log`、`--timeout-ms` 和对应 env 如果包含换行或 NUL，必须在发起 HTTPS / HTTP / WSS 请求前失败，不能让污染参数进入请求头、URL、access log 对账或 direct live JSON。遇到这类失败先修 runbook 参数来源或目标机 env，不要临时删掉 direct live smoke、改用 curl 截图或只看 `systemctl is-active`。
+- 踩坑补充：证据包 `--run-direct-live` 透传的 direct URL、Host、probe token、数据库名、Pingora access log 路径和 access log tail 行数也要在证据包配置层先拒绝换行或 NUL，`--direct-pingora-access-log` 还必须是绝对路径且不能是 `/`。遇到这类失败先修 runbook 参数或现场 env，不要把参数污染留给 direct live 子命令兜底，也不要手工改 `direct-live-command.json` 或跳过启用后证据包。
+- 踩坑补充：不要在证据目录或证据根目录里手工塞 `README`、截图、压缩包、临时目录、无 manifest 子目录或软链来“辅助说明”。证据 verifier 把 `manifest.files` 视为闭集，未登记普通文件、目录和符号链接都会默认失败；证据总审计也默认要求根目录只包含带 `manifest.json` 的证据目录。证据 verifier / 总审计的入口路径、verifier 脚本路径和 manifest 登记文件名都不能包含换行或 NUL 字符，避免污染 JSON 证据、终端输出或归档复盘。需要保留人工说明时，应放到证据根目录外部，或重新生成能把该文件纳入 manifest 元数据的正式证据，而不是在正式切换归档上使用 `--allow-extra-files` 或 `--allow-extra-root-entries`。
+- 踩坑补充：不要把即时证据验真理解成只验 hash。正式 runbook 中 `pre-cutover`、`enable-apply`、`post-enable`、`rollback-apply`、`post-rollback` 五个即时 verifier 步骤都必须带 `--require-summary-ok`，同时要求 `manifest.schemaVersion=1`、`manifest.files` 未漂移且 `manifest.summary.status=OK`；如果证据包已经记录 `CRITICAL`、缺少 schemaVersion 或缺少 summary，应先修复现场状态、发布包、env、systemd、health patrol 或 direct live 证据并重新归档，不能继续推进到最终总审计。
+- 踩坑补充：最终证据根目录总审计复用 verifier 时也必须启用 `--require-summary-ok`。如果总审计输出里 `verify.requireSummaryOk` 不是 `true`，说明脚本或随包 verifier 已经退化成宽松模式，应先修发布包脚本而不是继续切换。
+- 踩坑补充：不要用带 `manifest.commandName` 的命令证据目录满足 `--require-phase`。阶段证据必须来自状态快照证据包，命令证据必须通过 `--require-command` 单独要求；否则总审计可能把“真实执行过命令”和“某阶段状态已归档”混成一件事。
+- 踩坑补充：证据根目录总审计不能只要求三阶段状态快照，也不能只做 sha256 验真。正式 runbook 必须在 `--require-phase pre-cutover --require-phase post-enable --require-phase post-rollback` 之外，再传 `--require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply`，用 `manifest.phase + manifest.commandName` 锁定五条真实切换命令证据；缺命令证据、最新命令证据损坏、阶段或命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`、命令名不安全，或顶层 `manifest.commandName` / 内嵌 `manifest.command.name` 任一为空、非法、互不一致时都必须失败。
+- 踩坑补充：`commandName` 只能说明证据分类，不能证明真的跑了 enable / rollback 脚本。正式 runbook 的命令证据必须传 `--expected-executable` 绑定 current release 随包脚本绝对路径，并传 `--require-arg --apply` 在执行前确认真实命令参数包含 `--apply`；如果真实命令与预期脚本不一致或缺少 `--apply`，命令证据脚本应在创建正式命令证据前失败，避免把错误命令归档成正式切换证据。最终证据根目录总审计还必须传五条 `--require-command-executable` 和七条 `--require-command-arg`，覆盖 enable apply、health patrol direct env switch、Pingora gateway shadow env switch、health patrol nginx env switch 和 rollback apply，其中包含 `enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh` 以及对应 `--apply`、`pingora-direct`、`nginx` 参数要求，复核 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable，并要求 `manifest.commandName` 与 `manifest.command.name` 只要存在就各自是安全非空命令名、两者同时存在时一致、`manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的 executable 段必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符；总审计 JSON 会记录 `requiredCommandExecutables`，便于复盘本次绑定的真实 current release 随包脚本。总审计还会要求 `manifest.command` 与 `command-record.json` 关键字段一致；其中两份命令记录的 `schemaVersion` 都必须是 `1`，`stdoutPath` / `stderrPath` 必须同时与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 对齐，不能把重新计算过 hash 的 command-record 指向另一份输出文件；`args` / `command` 也必须一致，不能只保证脚本路径正确却把 `--apply` 证据改成 `--dry-run` 或其它参数；命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`；旧证据缺少 schemaVersion、缺少 expectedExecutable、缺少必需 `--apply` 参数、人工同名证据 executable 漂移、manifest 与 command-record 语义漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染、命令时间线漂移或同一命令重复绑定不同脚本路径都必须失败。
+- 踩坑补充：命令证据里 `expectedExecutable` 字段不能用空字符串或相对路径表示“未知”。`manifest.expectedExecutable` 和 `manifest.command.expectedExecutable` 只要存在就必须是安全绝对路径；否则总审计应把 manifest 判坏，避免坏顶层字段被内嵌字段兜底，或坏内嵌字段被 command-record 里的路径掩盖。生成端 `--expected-executable` 也不能填 `/` 或带换行 / NUL 的路径，脚本会在执行真实命令前失败，不能用坏 expected path 先生成证据再交给总审计兜底。
+- 踩坑补充：不能只检查 `manifest.command.executable` 与 `command-record.json.executable` 两边一致；如果命令证据已经声明 `expectedExecutable`，真实 `executable` 必须同时等于该预期路径，并且必须是绝对路径。否则人工修改两份命令记录为同一个错误脚本或相对路径，也可能伪造成一致证据。
+- 踩坑补充：命令证据的 `command` 字符串是给人读的，不是结构化身份事实。`manifest.command.executable` 和 `command-record.json.executable` 都必须存在且是绝对路径；缺少结构化 executable 时，即使 `command` 字符串看起来包含正确脚本，也不能作为正式切换证据。
+- 踩坑补充：生成命令证据时不要写 `-- node script.mjs ...`、`-- bash script.sh ...` 或 `-- pingora-direct-enable.sh ...`。`pingora-cutover-command-evidence.mjs` 现在要求 `-- <command>` 本身就是绝对路径，且不能是文件系统根目录；真实命令和每个真实命令参数都不能包含换行或 NUL 字符。正式 runbook 应直接执行 current release 随包脚本的绝对路径，让 manifest 与 command-record 的 `executable` / `args[]` 字段从源头就是可审计事实。
+- 踩坑补充：不要把 Pingora 日志、env、drop-in、脚本或 release root 路径填成 `/` 来“先跑通参数”。release readiness 的 `--live-nginx-access-log` / `--live-pingora-access-log` / `--direct-pingora-access-log` / `--direct-health-patrol-env-file` / `--direct-preflight-env-file`，canary 对账脚本的 `--nginx-log-file` / `--pingora-log-file`，direct live 的 `--pingora-access-log`，direct preflight 的 `--env-file`，以及 `pingora-direct-enable.sh` / `pingora-direct-rollback.sh` 的显式路径参数都必须是绝对文件路径且不能是文件系统根目录；如果现场不确定真实日志、env、drop-in 或脚本文件，先查 `systemctl cat`、logrotate、发布包 manifest 或服务 env，而不是用 `/` 占位。
+- 踩坑补充：证据根目录总审计选择“每类最新证据”后，还必须证明这些证据来自同一次切换时间线。最新证据选择和标准八段时间线证明只接受 `schemaVersion=1` 且带合法、规范 UTC 毫秒格式 `manifest.generatedAt` 的 manifest，命令记录 `startedAt` / `finishedAt` 也必须是 `new Date().toISOString()` 形式；缺失、非法、省略毫秒、本地时区或其它宽松可解析格式都会直接失败，不能用目录 mtime 兜底；证据目录被复制、归档或恢复后，也必须以 manifest 时间为准。同一阶段或同一命令如果出现多个候选共享最新 `manifest.generatedAt`，总审计会以 `AMBIGUOUS_LATEST` 失败并列出重复目录，不能按目录名排序打平；应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。标准八段证据都被要求时，每段审计状态都必须是 `OK`，`manifest.generatedAt` 必须满足 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`，且默认八段跨度不能超过 24 小时；非 OK、倒序或跨度过大都代表可能混入不同切换窗口遗留证据或现场状态未达标，必须失败后重新归档或清理证据根目录。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。确需跨更长维护窗口时，只能在生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让最终总审计 JSON 记录本次放宽后的 `timeline.maxSpanMs` 与实际 `timeline.spanMs`。
+- 踩坑补充：标准八段时间线失败时不要只看顶层 `ok=false` 或 `diagnostics` 文本。`timeline.failedCount` 会按具体失败项累计，`timeline.failureBreakdown` 会把非 OK 证据、缺少时间、cutoverRunId 混入、时间倒序和跨度超限拆开计数；同一次审计可能同时暴露多个证据问题，应逐项修复后重新归档。
+- 踩坑补充：同一天多次演练或切换时，只靠“最新证据”和 24 小时窗口仍可能把两轮证据拼在一起。正式 runbook 会生成或接受 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、五条真实切换命令证据和最终总审计；最终审计必须带 `--require-cutover-run-id <本次cutoverRunId>`，缺少该字段或 ID 不一致时必须失败。即使人工临时总审计忘记带 `--require-cutover-run-id`，标准八段时间线里只要任一证据声明了 `manifest.cutoverRunId`，八段也必须全部声明同一个值，否则总审计失败。
+- 验证：先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，确认 env、drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性和 80/443 已释放；`systemctl cat genarrative-pingora-gateway.service` 必须显示 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env`；启用脚本 apply 必须先通过 current release 自审，失败时不安装 direct-entry drop-in；还必须带 direct HTTPS / HTTP / Host / redirect host / SpacetimeDB database / Pingora access log 参数，并在重启后直接完成 direct live smoke 和 direct-access-log JSON 证据校验；也可用 release readiness `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable` 把 HTTPS、HTTP redirect / ACME、正式域名 Host/SNI、redirect Location host、Pingora access log request_id 落盘、env 预检、systemd drop-in、service EnvironmentFile 一致性、当前用户和服务用户证书可读、service 二进制可执行、显式目标库和 WSS 101 一起纳入硬门禁，并拒绝 `--direct-skip-wss`，避免 TLS 证书只按 `127.0.0.1` 误测、HTTP redirect Location 指错域名、service 实际读取另一份 env、root / deploy 用户可读但 systemd 服务用户不可读、current release 缺少可执行 `pingora-gateway`，或 WSS subscribe 隐式打到默认 SpacetimeDB 库。`check-pingora-release-readiness.mjs --help` 的正式直连和只生成 runbook 示例也必须带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，不要让值班人员复制示例后才被 `--require-direct` 拦截。current release 自审、状态快照和证据包的布尔 env 必须是明确布尔值，非法值会失败，不得把拼错的 run / require / fail 开关当成 false。`npm run plan:pingora-direct-cutover -- --require-direct ...` 输出必须包含 Host 与回退巡检入口确认、current release preflight、启用前不带 `--require-direct` 的基础 readiness、direct enable dry-run/apply、启用后带 `--require-direct` 的复核、rollback dry-run/apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；缺少 `--require-direct`、缺少 `--rollback-health-patrol-public-base-url`、缺少 `--direct-pingora-access-log`、redirect Host 漂移或 rollback smoke Host 漂移时必须失败，避免生成缺少正式直连硬门禁或验证不同入口的切换计划。Host 与回退巡检入口确认步骤必须展示回退后要恢复的 health patrol public base URL / Host。直连后 `genarrative-health-patrol.service` 应使用 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，状态 JSON 中 `gatewayMode` 应为 `pingora-direct`，并检查 `genarrative-pingora-gateway.service` 而不是 `nginx.service`；public probe 走 `127.0.0.1` 时应带 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`。回退后 `nginx -t` 必须先通过，`systemctl cat genarrative-pingora-gateway.service` 不应再显示这两条 capability，`systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager` 必须仍指向 current release 的 `pingora-gateway`，`systemctl is-active nginx.service` 应为 `active`，`curl --fail --max-time 5` 访问 `--nginx-smoke-url` 应成功；若 smoke URL 为本机地址必须带 `--nginx-smoke-host <域名>`，证明正式 vhost 已回到 Nginx；随后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 复核 health patrol env，必须显示 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 public base URL / Host 与切换前记录一致，shadow probe 可选复核必须返回 `gateway=pingora-shadow`。本机提交前还要运行 `npm run check:pingora-direct-enable`、`npm run check:pingora-direct-rollback`、`npm run check:production-health-patrol`、`npm run check:production-api-release`、`npm run check:pingora-production-release-build` 和 `npm run check:production-api-deploy`，确保脚本默认 dry-run 不会安装或删除 drop-in、current release 自审失败时启用脚本不会安装 drop-in、direct live 退出 0 但缺少 `direct-access-log` 结构化证据时启用失败，API release 布局自包含，真实 Pingora release 二进制能构建并进入发布包，API deploy 从发布产物内执行后 current release 自包含；缺少数据库备份脚本、健康巡检脚本、健康巡检 env 复核脚本、切换命令证据脚本、env 示例目录或 direct live smoke 脚本的发布包都必须部署失败并保持维护模式。正式直连 readiness 必须带 `--direct-health-patrol-env-file /etc/genarrative/health-patrol.env`，并用 `scripts/check-production-health-patrol-env.mjs` 阻断 health patrol 仍停在 Nginx 模式或本机 direct probe 缺少正式 Host；发布包包含 `pingora-gateway` 时，`npm run check:production-api-deploy` 必须覆盖服务 active / inactive 都会在 shadow 配置安全时执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，同时覆盖 direct-entry capability 或公网监听 env 下不会提升 release、不会切 current、不会自动 restart。
+- 顺序补充：正式 runbook 必须先通过 health patrol env 切换脚本预置回 Nginx 和切换前 public base URL / Host，再执行 `rollback apply`；回退脚本内置 env 复核和独立 env 复核都会阻断 public base URL / Host 漂移。
+- 顺序补充：正式 runbook 还必须在 `rollback apply` 前预置 Pingora shadow env。启用前和 `--dry-run-cutover` 要求 `80/443` 空闲；启用后 `--require-direct` 复核不再要求端口空闲，因为端口应由 Pingora 占用。回退时要先用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 恢复 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081` 并清空 TLS / HTTP redirect 低端口监听，再移除 direct-entry drop-in 和重启 Pingora。
+- 关联：`deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`deploy/env/health-patrol.env.example`、`deploy/env/pingora-direct-live.env.example`、`deploy/env/pingora-canary-live.env.example`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`scripts/deploy/pingora-tls-cert-sync.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/ops/pingora-cutover-command-evidence.mjs`、`scripts/ops/pingora-cutover-evidence-verify.mjs`、`scripts/ops/pingora-cutover-evidence-audit.mjs`、`scripts/jenkins-server-provision.sh`、`scripts/build-production-release.sh`、`scripts/deploy/production-api-deploy.sh`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
 ## 外部生成 worker 业务失败重试会撞上钱包扣退费幂等
 
 - 现象：同一个外部生成 job 如果第一次业务失败后退款，再用同一个业务资源 ID 自动重试并成功，钱包 `consume` ledger 可能因为同 ID 已存在而跳过，最终出现“失败已退、成功不再扣”的余额漂移。
@@ -31,6 +80,14 @@
 - 验证：`systemctl status genarrative-external-generation-controller.service 'genarrative-external-generation-worker@*.service'` 能看到 controller 和 worker 实例；queue 模式下任务被 claim 后 `worker_id` 与 `lease_expires_at` 会更新，完成后 session 进入 ready 或 failed；inline 模式下不应产生新的 `external_generation_job`。
 - 关联：`deploy/systemd/genarrative-external-generation-worker@.service`、`deploy/systemd/genarrative-external-generation-controller.service`、`deploy/env/external-generation-controller.env.example`、`server-rs/crates/spacetime-module/src/external_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## 外部生成 worker 不应等待 HTTP 认证快照恢复
+
+- 现象：`genarrative-external-generation-worker@1.service` 在 systemd 中显示 active，但 `external_generation_job` 长时间保持 `pending`；worker 日志每 5 秒出现 `export_auth_store_snapshot_from_tables` 订阅失败，例如缺少 `public_work_gallery_entry` 公开 read model 表。
+- 原因：独立 worker / controller 是非 HTTP 角色，不承接用户登录态恢复；如果启动路径复用 HTTP `api-server` 的认证快照恢复，SpacetimeDB 认证投影或公开 read model 漂移会把 worker claim 循环挡在启动前。
+- 处理：`GENARRATIVE_PROCESS_ROLE=external-generation-worker` 和 `external-generation-controller` 启动时只构建空 auth store 的 `AppState`，不调用 SpacetimeDB 认证快照导出；只有 `api` / `all` 这类 HTTP 角色需要在启动时恢复认证快照并在依赖不可用时重试或进入 503 降级。
+- 验证：重启 worker 后日志应先出现“非 HTTP 进程跳过 SpacetimeDB 认证快照恢复”，随后出现 `external generation worker 已启动`；同一时间窗口不应再因为 `export_auth_store_snapshot_from_tables` 缺表而阻止 job claim。HTTP `api-server` 的认证恢复日志和 503 降级语义保持不变。
+- 关联：`server-rs/crates/api-server/src/main.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/external_generation_worker_controller.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 外部生成 worker 业务写回必须同事务校验 lease guard
 
 - 现象：worker `complete/fail` 已校验 `worker_id + lease_token`，但如果玩法 session / work profile 写回在此之前单独调用，过期 worker 仍可能先写入业务状态，随后才在 job complete/fail 阶段失败；带计费包装的旧 worker 还可能因为 stale guard 错误触发补偿退款。
@@ -55,6 +112,46 @@
 - 验证：`systemctl cat genarrative-database-backup.service` 应包含该参数；`systemctl is-active spacetimedb.service genarrative-api.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功。
 - 关联：`deploy/systemd/genarrative-database-backup.service`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## Pingora Brotli 不能只看 Content-Encoding
+
+- 现象：在 `pingora-gateway` 中把 `GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS` 试验性改成 `gzip,br` 后，`Accept-Encoding: br, gzip` 的响应会带 `Content-Encoding: br`，但 Node `brotliDecompressSync(...)` 报 `unexpected end of file`。
+- 原因：Pingora 0.8.1 的 Brotli compressor 路径虽然存在，但端到端输出不能被 Node 按完整 Brotli 流解压；只断言响应头会误判为可用。
+- 处理：当前 Pingora shadow 只允许 `GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip`，在进入 Pingora compression 模块前把下游 `Accept-Encoding` 收敛为 gzip。Brotli 继续由 Nginx / 前置代理承担，直到补齐可解压的端到端门禁后再评估迁移。
+- 验证：`npm run check:pingora-gateway-smoke` 必须覆盖小响应不压缩、图片资源不压缩、大响应 `Accept-Encoding: gzip` 和 `Accept-Encoding: br, gzip` 都返回可解压的 gzip；`GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=br` 必须启动失败，`GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=0` 也必须启动失败。
+- 关联：`server-rs/crates/pingora-gateway/src/main.rs`、`scripts/check-pingora-gateway-smoke.mjs`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`deploy/nginx/README.md`。
+
+## Pingora 公网直连不能信任 X-Forwarded-For
+
+- 现象：公网直连 Pingora 后接流保护、access log 或 `client_ip` 似乎按用户传入的 `X-Forwarded-For` 分散，限流 key 可被客户端伪造。
+- 原因：`GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true` 只适合 Pingora 前方还有受控 Nginx / LB 且该前置层会清洗 `X-Forwarded-For` 的场景；Pingora 自己监听公网 `0.0.0.0:80/443` 时，下游请求头就是用户可控输入，不能拿来作为接流保护 client key。
+- 处理：公网直连 env 必须保持 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=false`。只有 loopback / 受控前置入口才允许配合 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true` 使用 XFF。目标机 direct preflight 会在公网监听加 `TRUST_X_FORWARDED_FOR=true` 时失败。
+- 验证：`npm run check:pingora-direct-enable` 覆盖公网监听误信任 XFF 负例；切换窗口运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env ...`，看到该错误时先改 env，再重启 Pingora。该 npm script 内部必须保持 `node -- scripts/check-pingora-direct-preflight.mjs`，避免 Node 22 抢占业务 `--env-file`。
+- 关联：`scripts/check-pingora-direct-preflight.mjs`、`deploy/pingora/pingora-gateway.env.example`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
+## Pingora canary 不能只看 handoff 响应头
+
+- 现象：目标 Nginx 前缀 canary 的 `/__genarrative_pingora_canary/healthz` 和代表性 API 都返回成功，响应也带 `X-Genarrative-Nginx-Handoff: pingora-canary`，但仍无法证明 Nginx 与 Pingora 对同一请求的 method/status/path 完全一致。
+- 原因：响应头只能证明请求经过了 canary snippet，不能证明同一 `request_id` 已在 Pingora access log 落盘，也不能发现 healthz exact location 映射、前缀 rewrite 后路径或状态码漂移。
+- 处理：本机 / CI 的 `check-pingora-canary-docker` 也必须写临时 Nginx access log，并在 live smoke 后复用 `scripts/check-pingora-canary-access-log-parity.mjs` 对账 Docker Nginx 与 Pingora access log。目标机 `--require-live` 必须在 live smoke 后继续执行同一脚本，默认读取 `/var/log/nginx/genarrative.access.log` 和 `/var/log/genarrative/pingora-gateway.access.log`，按 `request_id` 对照 `/__genarrative_pingora_canary/healthz` 与 `/__genarrative_pingora_canary/api/creation-entry/config`。Nginx canary exact `/healthz` 映射到 Pingora shadow `/__genarrative_pingora/healthz`，其它 canary 前缀路径按 rewrite 后路径比对。对账脚本的日志路径、prefix、必需路径和 `--since-lines` / `GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES` 不能包含换行或 NUL；日志行里解析出的 URI / path 含控制字符时也必须失败，避免污染值进入 JSON 对账输出。
+- 验证：本机或 CI 执行 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull` 时应同时完成临时 Nginx / Pingora access log 对账。目标机执行 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；本机执行 `npm run check:pingora-release-readiness-plan` 和 `npm run check:production-ops`，确认 live 门禁计划包含真实 access log 对账。
+- 关联：`scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-access-log-parity.mjs`、`deploy/env/pingora-canary-live.env.example`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
+## Pingora realpath canary include 要晚于 log_format
+
+- 现象：目标机把 `genarrative-pingora-realpath-canary.conf` 放进 `/etc/nginx/conf.d/` 后，`nginx -t` 失败并报 `unknown log format "genarrative_upstream"`。
+- 原因：真实路径 canary 是独立 `server` 片段，并使用 `access_log /var/log/nginx/genarrative-pingora-realpath-canary.access.log genarrative_upstream;`。Nginx 会按文件名顺序加载 `conf.d`；如果 canary 文件名早于定义 `log_format genarrative_upstream` 的主站配置，access log 行会先被解析而找不到格式。
+- 处理：真实路径 canary 启停统一用 current release 随包脚本，不再手工写 `/etc/nginx/conf.d/`。启用执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083`，脚本固定写入晚于主站配置加载的 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`，并在 `nginx -t`、reload 或 live smoke 失败时恢复写入前配置。关闭执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply`，脚本在 `nginx -t` 或 reload 失败时恢复删除前配置。另一种长期做法是把 `log_format` 放到所有 `conf.d` server 之前的全局 Nginx 配置。检查配置时不要把 probe token 原文写入记录。
+- 验证：提交前运行 `npm run check:pingora-realpath-canary-toggle` 或默认聚合门禁 `npm run check:pingora-release-readiness`，确认启停脚本的 dry-run、apply、失败回滚和 disable 恢复逻辑仍被覆盖。启用脚本通过后，再运行 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`、`node -- /opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log ...` 和 `node -- /opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-realpath-live ...`。若只启用了真实路径 canary，不要同时传 `--require-live`，否则前缀 canary 未启用时会按正式 Nginx HTTP 入口返回 301。
+- 关联：`deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf`、`deploy/nginx/README.md`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`scripts/check-pingora-release-readiness.mjs`。
+
+## Pingora release readiness 脚本不能只存在于源码 checkout
+
+- 现象：本机 runbook 能生成，但目标机切换窗口执行启用前或启用后的 release readiness 复核时，可能命中 Jenkins workspace 或源码 checkout 的 `scripts/check-pingora-release-readiness.mjs`，而不是当前发布包里的脚本。
+- 原因：API release、Jenkins Build 归档、Jenkins Deploy 复制清单都是显式文件列表；只在仓库中新增脚本或只改 runbook 相对路径，不能保证目标机 current release 自包含。另一个误区是在 `/opt/genarrative/current` 上运行默认源码全量 readiness，导致包内脚本依赖 Cargo、npm、Docker 或 Nginx 构建环境。
+- 处理：`scripts/build-production-release.sh`、`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-api-deploy` 和 `scripts/deploy/production-api-deploy.sh` 必须同时携带 `scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs`、canary access log 对账脚本以及 direct preflight / live 子脚本；正式 cutover runbook 的启用前基础门禁和启用后 `--require-direct` 复核必须调用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only`。默认不带 `--release-runtime-only` 的全量 readiness 只在源码 checkout / CI / 构建环境运行。
+- 验证：运行 `npm run check:production-api-release`、`npm run check:production-api-deploy`、`npm run check:pingora-current-release-audit`、`npm run check:pingora-release-readiness-plan` 和 `npm run check:production-ops`，确认发布包、current release、runbook 与 guardrails 都覆盖聚合脚本和 `check-pingora-canary-live.mjs`，且 runbook readiness 参数包含 `--release-runtime-only`。
+- 关联：`scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs`、`scripts/build-production-release.sh`、`scripts/deploy/production-api-deploy.sh`、`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-api-deploy`。
+
 ## SpacetimeDB 45 秒超时要看 api-server 记录的阶段
 
 - 现象：release 上 Nginx 能立刻连到 `api-server`，但 `/api/runtime/*/gallery`、`/api/creation-entry/config` 等请求在约 `GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS` 后返回 `502` / `504`。
@@ -1711,6 +1808,10 @@
 
 2026-05-22 补充：结果页关卡详情的“关卡测试”不能把单关 `draft` 传给父级再调用 `updatePuzzleWork`。`updatePuzzleWork` 会同步 `puzzle_work_profile.levels_json` 和 source session 草稿，单关快照会把整份多关卡草稿覆盖成一个关卡，退出重进后只剩最后测试的关卡且序号表现为第一关。修复口径是 `PuzzleResultView` 始终传完整 `syncedDraft`，额外用 `{ levelId }` 指定起始关卡；父级持久化完整 levels 后调用 `startLocalPuzzleRun(item, levelId)`。
 
+2026-06-18 补充：结果页点击“新增关卡”只是在本地打开一个空白占位关卡，不应立刻进入自动保存。空白占位如果被写入 `/api/runtime/puzzle/works/{profile_id}`，在作品 profile 投影尚未稳定存在时会触发 `update_puzzle_work` 404，并且后续 session/draft 回读可能把当前详情弹窗关闭。修复口径是自动保存比较和 payload 过滤掉“后端基线中不存在且完全空白”的本地关卡；用户填写名称、描述、参考图或开始生成后再保存。`mergeDraftEditStateWithIncomingState(...)` 还要保留本地空白占位，避免 incoming draft 刷新时移除正在编辑的弹窗。
+
+2026-06-18 补充：改造流的 `creative_agent` 草稿写回会用 `puzzle-session-*` 派生出的 `puzzle-profile-*` 调用 `update_puzzle_work`；如果前置 `create_puzzle_agent_session` 已写入 `puzzle_agent_session`，但派生的 `puzzle_work_profile` 草稿投影缺失，写回会报“拼图作品不存在”。首图生成或结果页保存也可能踩到同一缺口。修复口径是在 SpacetimeDB `update_puzzle_work_tx` 里只对稳定 `puzzle-profile-*` 反推同源 `puzzle-session-*`，确认 owner 匹配、session 未发布且有 draft 后恢复 draft profile，再继续更新；不要在前端重试或凭空创建任意 profile，也不要恢复已发布 session。
+
 ## 拼图上传图关闭 AI 重绘不要走首图生图
 
 - 现象：用户在拼图入口页或结果页关卡详情上传图片并关闭 AI 重绘后，生成页仍显示“生成拼图首图”，或者后端仍调用 `generate_puzzle_image_candidates` 生成第一张 1:1 候选图。
@@ -2263,6 +2364,47 @@
 - 验证：模拟首张 image2 超长耗时或超时重试时，生成页应显示真实阶段和可恢复状态；前端请求超时不应把最终成功草稿标记为失败；刷新 `/creation/jump-hop/generating?sessionId=<id>` 后应能恢复到后端真实状态；同一 session 重试不得重复生成已完成阶段。
 - 关联：`src/services/jump-hop/jumpHopClient.ts`、`src/services/miniGameDraftGenerationProgress.ts`、`server-rs/crates/api-server/src/jump_hop.rs`、`server-rs/crates/platform-image/src/vector_engine/client.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## Pingora 静态缓存不能只写 Cache-Control
+
+- 现象：直连 Pingora 后，HTML 入口虽然是 `Cache-Control: no-cache`，但浏览器每次都重新下载完整入口页或普通静态文件；或者 Vite 指纹资源长期缓存正常，但旧标签页刷新时协商缓存行为和 Nginx 直连不同。
+- 原因：`Cache-Control` 只决定缓存策略，不等于条件请求能力。Nginx 静态文件默认会按文件 metadata 提供 `ETag` / `Last-Modified`，浏览器随后可用 `If-None-Match` / `If-Modified-Since` 得到 `304`；Pingora 自实现静态读取时如果只写 body 和 `Cache-Control`，就会丢掉这层协商缓存。
+- 处理：Pingora 静态响应读取文件 metadata，写入弱 `ETag` 和 `Last-Modified`；`GET` / `HEAD` 命中 `If-None-Match` 或 `If-Modified-Since` 时直接返回 `304`，不读取或发送 body。`HEAD` 静态响应只读 metadata，仍写正确 `Content-Length`。
+- 验证：`npm run check:pingora-gateway-smoke` 必须覆盖静态 `HEAD`、`If-None-Match` 304、`If-Modified-Since` 304，并用 access log method/path/status 对账证明本地静态边界进入日志证据链；`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml` 必须覆盖 ETag 构造和匹配 helper。
+- 关联：`server-rs/crates/pingora-gateway/src/main.rs`、`scripts/check-pingora-gateway-smoke.mjs`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
+## Pingora 静态路径必须按 URL segment 解码
+
+- 现象：dev 页面里部分像素图标加载失败，浏览器直接打开 `/Icons/Admurin%27s%20Pixel%20Items/.../499_Iron_Gear.png` 返回 `200 text/html`，响应体是主站 `index.html`，但服务器磁盘上真实 PNG 文件存在。
+- 原因：浏览器请求中的空格和英文撇号会变成 `%20` / `%27`；Pingora 静态文件解析如果直接把编码后的 path 当磁盘路径查找，就会错过真实文件，并继续落到 SPA fallback，最终让图片解码看到 HTML。
+- 处理：静态路径按 `/` 拆分 URL segment 后逐段 percent-decode；解码后拒绝 `/`、`\`、NUL、`..` 和非法 `%` 编码，既能读取带空格 / 撇号的真实文件，又不重新打开目录穿越边界。
+- 验证：`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml` 必须覆盖编码空格 / 撇号、`%2e%2e`、`%2f` 和非法 `%GG`；`npm run check:pingora-gateway-smoke` 必须覆盖编码图标路径返回 `image/png`，并确认危险编码路径仍返回 `404`。dev 切换后用浏览器或 curl 直接验证对应图标 URL 的 `Content-Type` 和 PNG magic bytes。
+- 关联：`server-rs/crates/pingora-gateway/src/main.rs`、`scripts/check-pingora-gateway-smoke.mjs`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
+## dev health patrol 不能缺少公网 HTTPS 入口配置
+
+- 现象：dev 上 `genarrative-health-patrol.timer` 正常 active，但 `genarrative-health-patrol.service` 最近一次运行失败；Pingora 直连彩排状态脚本只因 `/etc/genarrative/health-patrol.env` 缺失或 public probe 命中 `http://127.0.0.1` 后被 Nginx 301 而报 `CRITICAL`。
+- 原因：health patrol systemd unit 的 `EnvironmentFile=-/etc/genarrative/health-patrol.env` 允许文件缺失，脚本会退回默认 public base URL `http://127.0.0.1`；dev / release 的 Nginx 公开入口会把 HTTP 跳到 HTTPS，巡检按非 2xx 判失败。
+- 处理：目标机应创建 `/etc/genarrative/health-patrol.env`，保持 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx`，把 `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL` 指向真实 HTTPS 域名，例如 `https://dev.genarrative.world`；Pingora shadow 巡检同时配置 `GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL=http://127.0.0.1:18081` 和与 `/etc/genarrative/pingora-gateway.env` 一致的 probe token。不要为了让彩排状态变绿把缺 env 降级成 warning。
+- 验证：先运行随包 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs --env-file /etc/genarrative/health-patrol.env --expected-gateway-mode nginx --expected-public-base-url https://dev.genarrative.world --require-empty-public-host`，再 `systemctl start genarrative-health-patrol.service`；最后运行 `node -- /opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs --release-root /opt/genarrative/current --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical`。
+- 关联：`deploy/env/health-patrol.env.example`、`scripts/ops/production-health-patrol.mjs`、`scripts/ops/pingora-direct-rehearsal-status.mjs`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
+## Pingora 高端口直连演练不要 source env 文件
+
+- 现象：在 dev 上用临时 env 启动高端口 Pingora direct 演练时，shell 报 `/tmp/pingora-direct-highport-*.env: line ...: max-age=31536000,: command not found`，或者临时演练进程启动后没有按预期监听 `18443/18080`。
+- 原因：`pingora-gateway.env` 是 systemd EnvironmentFile 口径，允许 `GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL=public, max-age=31536000, immutable` 这类带空格的值；它不是可安全 `source` 的 shell 脚本。用 shell `source` 会把空格后的内容拆成命令或参数。另一个容易误判的点是 Pingora 默认优雅退出窗口较长，停止临时 systemd unit 后可能短暂停在 `stop-sigterm`，即使监听端口已经释放。
+- 处理：高端口真实演练优先用临时 systemd unit 启动 current release 的 `/opt/genarrative/current/pingora-gateway`，通过 `systemd-run --property=EnvironmentFile=/tmp/<run>.env --property=User=genarrative --property=WorkingDirectory=/opt/genarrative/current ...` 让 systemd 解析 env；或使用显式安全 env 解析器，禁止直接 `source`。临时 env 要把正式 shadow 端口改到独立 loopback 端口，例如 `127.0.0.1:18084`，HTTPS / HTTP redirect 用 `127.0.0.1:18443` / `127.0.0.1:18080`，access log 写独立文件。演练结束先 `systemctl stop <临时unit>`，再用 `ss -ltnp` 确认高端口已释放；若临时 unit 仍停在 `deactivating/stop-sigterm` 且只剩演练进程，可对该临时 unit 执行 `systemctl kill -s SIGKILL <临时unit>` 收尾，不要碰正式 `genarrative-pingora-gateway.service`。
+- 处理补充：正式 `plan:pingora-direct-cutover` / `check-pingora-release-readiness.mjs --dry-run-cutover --require-direct` 生成的 runbook 默认读取 active `/etc/genarrative/pingora-gateway.env`，不会自动使用 `/tmp` 候选 env。若只生成了候选 direct env，必须先在维护窗口内把候选 env 提升为 active env，并确认 Nginx 已释放 `80/443`，再执行 runbook 的 direct preflight、enable dry-run 和 enable apply；否则 runbook 第 5 步仍会按 shadow env 报缺 `TLS_LISTEN`、`HTTP_REDIRECT_LISTEN`、cert/key、`FORWARDED_PROTO=https` 以及 direct-entry capability。不要把候选 env 的 loopback / 高端口预检通过误解为 active env 已满足正式直连门禁。
+- 验证：先跑 `check-pingora-direct-preflight.mjs --env-file <临时env> --require-live-env --check-cert-readable --check-service-user-cert-readable --check-ports-free --allow-loopback-only`；启动临时 unit 后跑 `check-pingora-direct-live.mjs --https-base-url https://127.0.0.1:18443 --http-base-url http://127.0.0.1:18080 --host <域名> --redirect-host <域名> --redirect-base-url https://<域名> --require-wss-upgrade --pingora-access-log <临时log> --insecure-tls --json`，要求 `OK` 且 `direct-access-log matchedCount == checked`。收尾后复核 `80/443` 仍由 Nginx 监听，正式 Pingora shadow 仍为 `127.0.0.1:18081`。
+- 关联：`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`deploy/pingora/pingora-gateway.env.example`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
+## Pingora 直连接管同 IP 多域名前先确认 Host 和证书覆盖
+
+- 现象：dev 上准备让 Pingora 直接绑定 `0.0.0.0:80/443` 时，只按 `dev.genarrative.world` 配置证书和路由会让同 IP 的 `git.genarrative.world` 也进入主站 Pingora 路由，Gitea 可能不可访问；即使补了 Gitea Host 路由，如果仍使用只覆盖 `dev.genarrative.world` 的单域名证书，浏览器和 Git 客户端访问 `git.genarrative.world` 也会遇到证书域名不匹配。
+- 原因：Nginx 原来通过多个 `server_name` vhost 承载主站和 Gitea；当前 Pingora direct listener 默认只有一组 TLS cert/key，且路径路由本身无法区分同一 IP 上的多个域名。
+- 处理：direct env 必须配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world` 与 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`；TLS 证书必须同时覆盖 `dev.genarrative.world` 和 `git.genarrative.world`，并通过 `pingora-tls-cert-sync.mjs` 同步到 Pingora 私有目录后再指向 env。不要通过“临时释放 Gitea vhost”把 Gitea 从切换窗口里牺牲掉。
+- 验证：本地 `npm run check:pingora-gateway-smoke` 必须覆盖 Gitea Host 整站转发、维护模式不拦截 Gitea Host 和 access log `proxy_target=Gitea`；dev 切换后除 `https://dev.genarrative.world/` 外，还必须验证 `https://git.genarrative.world/` 返回 Gitea，HTTP 到 HTTPS redirect 保留正确 Host，Pingora access log 中有 `host=git.genarrative.world` / `proxy_target=Gitea`。
+- 关联：`server-rs/crates/pingora-gateway/src/main.rs`、`deploy/pingora/pingora-gateway.env.example`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
 ## SpacetimeDB 连接池租约必须有 Drop 兜底，acquire 不允许无界自旋
 
 - 现象：release 上 api-server 周期性出现全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 业务超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），`/healthz` 仍 200，只有重启能恢复，过若干小时复发。
diff --git a/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md b/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md
new file mode 100644
index 000000000..4e22e53b8
--- /dev/null
+++ b/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md
@@ -0,0 +1,562 @@
+# Pingora 独立网关试点
+
+## 目标
+
+本试点新增 `server-rs/crates/pingora-gateway` 独立二进制 crate，用 Pingora 复刻当前生产 Nginx 的核心反向代理与静态路由口径。当前阶段只作为影子网关验证，不绑定公网 `80/443`，不替代 `deploy/nginx/genarrative.conf`。
+
+## 运行边界
+
+- 默认监听 `127.0.0.1:18081`，只用于本机或容器内 smoke。可选配置 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`TLS_CERT_FILE` 与 `TLS_KEY_FILE` 后会额外挂载 Rustls HTTPS 监听；可选配置 `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN` 后会额外挂载 HTTP 入口，除 ACME challenge 外统一 301 到 HTTPS。两类直连入口默认关闭，不改变 Nginx canary / shadow 路径。
+- 默认转发 `api-server` 到 `127.0.0.1:8082`。
+- 默认转发最小 SpacetimeDB 公网路由到 `127.0.0.1:3101`。
+- 默认静态目录为 `/srv/genarrative/web`，维护开关文件为 `/var/lib/genarrative/maintenance/enabled`。
+- 静态响应会显式写入 `Cache-Control`：HTML / SPA fallback 默认 `no-cache`，Vite 指纹静态资源默认 `public, max-age=31536000, immutable`，其它静态资源默认 `no-cache`。三档分别由 `GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL`、`GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL` 和 `GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL` 覆盖，配置值禁止换行或 NUL，避免响应头注入。静态文件还会按 metadata 写入弱 `ETag`、`Last-Modified` 与 `Accept-Ranges: bytes`，并对 `GET` / `HEAD` 的 `If-None-Match`、`If-Modified-Since` 返回 `304`；单段 `Range: bytes=` 返回 `206 + Content-Range`，越界范围返回 `416 + Content-Range: bytes */<len>`，保持 HTML `no-cache` 下的浏览器协商缓存和 Nginx 直连体验一致。
+- `/api` 通用路由同时按 `Content-Length` 与实际流式请求体累计字节数执行大小上限，避免客户端省略长度头绕过网关保护。
+- `GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN` 非空时，`/__genarrative_pingora/healthz` 可用同名探针 header 做本机 shadow 健康检查；未带 token 或 token 不匹配时仍返回 404。
+- `api-server` 代理响应会写入 `X-Accel-Buffering: no`，便于后续由 Nginx 反代到 Pingora canary 时继续保持 API / SSE 低缓冲口径。
+- `api-server` 代理请求会对齐当前 Nginx 头语义：透传 `Host`，写入 `X-Forwarded-Host`、配置化的 `X-Forwarded-Proto`、TCP 对端 IP 作为 `X-Real-IP`，并把 TCP 对端 IP 追加到 `X-Forwarded-For`。`TRUST_X_FORWARDED_FOR` 只影响接流保护 client key，不改变传给上游的真实 TCP 对端归因；直连公网时仍必须保持关闭。
+- 代理路径上的上游连接失败会返回统一 JSON；`502` 使用 `GATEWAY_UPSTREAM_ERROR`，`504` 使用 `GATEWAY_UPSTREAM_TIMEOUT`，避免 shadow / canary 阶段把框架默认错误页透给前端或巡检。
+- 上游超时显式配置在 Pingora peer 上：连接超时默认 `3000ms`，没有 Nginx 显式长超时的代理路由读取默认 `60s`，通用 `/api`、公开列表 / 详情和 SpacetimeDB subscribe 读取默认 `3600s`，写入超时默认 `3600s`。读 / 写 / 连接超时统一映射为 JSON `504 GATEWAY_UPSTREAM_TIMEOUT`。
+- 默认开启 gzip 响应压缩，`GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5` 和 `GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024` 对齐当前 Nginx `gzip_comp_level 5` / `gzip_min_length 1024`；`GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED=false` 时禁用。`GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip` 是当前唯一允许的压缩算法白名单；网关会在进入 Pingora compression 模块前把 `Accept-Encoding` 收敛为 gzip，避免未验收的 `br` / `zstd` 被隐式打开。压缩能力由 `check:pingora-gateway-smoke` 用小响应不压缩、图片资源不压缩、大响应 `Accept-Encoding: gzip`、`Accept-Encoding: br, gzip`、`Content-Encoding: gzip`、`Vary: Accept-Encoding` 和解压后的响应体一起验证。Brotli 不进入当前 Pingora 正式化口径，仍由 Nginx / 前置代理能力探测承担；直连 Pingora 时不把 Brotli parity 作为切换门禁。
+- 默认开启单进程内接流保护，按客户端 IP 与路由组执行并发上限、RPS 和 burst 限制。保护组默认对齐当前 Nginx：`admin_api=64/30rps/16burst`、`gallery_list=320/5000rps/4096burst`、`gallery_detail=32/300rps/32burst`、`api=64/300rps/64burst`、`spacetime=256/1000rps/256burst`。超限返回 JSON `429` 并带 `Retry-After: 1`。
+- 当前接流保护的默认正式口径是单 Pingora 实例。`GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT` 默认 `1`；若 `GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1`，必须先落地共享限流 / 共享并发保护层，并显式设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则网关启动和目标机 direct preflight 都会失败。若关闭网关保护后横向多实例运行，则全局接流保护必须由前置 Nginx / LB 承担。
+- 默认以 TCP 对端 IP 作为限流 client key；只有在 Pingora 前置代理已经清洗 `X-Forwarded-For` 时，才允许开启 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true` 使用首个转发 IP。开启时必须同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true`，否则网关会拒绝启动。若 Pingora 直接监听公网地址，`TRUST_X_FORWARDED_FOR` 必须保持 `false`，目标机 direct preflight 会在看到公网监听加该开关时失败。
+- 可选配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS` 和 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM` 后，网关会先按 `Host` 归一化匹配 Gitea 域名，命中时整站代理到 Gitea 上游。Gitea 路由不走应用维护页、API 请求体上限或网关接流保护，避免影响 git clone / push。用于同一公网 IP 同时承载 `dev.genarrative.world` 与 `git.genarrative.world` 的直连切换时，TLS 证书必须同时覆盖两个域名；当前单 listener 配置只加载一组 cert/key。
+- 网关启动会做配置校验：监听地址不能和上游地址相同，TLS 入口必须同时给出可读取的证书和私钥文件，HTTP redirect 入口必须依附已配置的 TLS 入口且不能复用同一监听地址，redirect scheme 当前只允许 `https`，`MAX_API_BODY_BYTES` 必须大于 `0`，上游 timeout 必须大于 `0`，`GZIP_LEVEL` 必须在 `0..=9`，`GZIP_MIN_LENGTH_BYTES` 必须大于 `0`，`COMPRESSION_ALGORITHMS` 当前只允许 `gzip`，shadow probe token 不能是占位值或短 token，access log 不能指向目录，`BURST>0` 时对应 `RATE_PER_SECOND` 不能为 `0`，开启网关保护时 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 必须已确认共享保护层。
+- 结构化日志会写入 `request_id`、`method`、`path`、`uri`、`host`、`client_ip`、`status`、`route`、`proxy_target`、`upstream`、`content_length`、`body_bytes_seen` 和 `elapsed_ms`，用于和 Nginx access log 对照 shadow 行为。
+- 配置 `GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE` 后，网关会额外写入 tab-separated access log。影子 systemd 模板默认允许写 `/var/log/genarrative`，Server-Provision 会安装 `deploy/logrotate/genarrative-pingora-gateway` 到 `/etc/logrotate.d/`，避免 canary 日志无限增长。
+- 当前已具备受配置保护的 TLS 监听和 HTTP 到 HTTPS 重定向入口，但默认 systemd service 仍不具备绑定低端口的 capability；需要直连 `80/443` 时必须人工启用 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf` drop-in。网关仍不承接 Certbot / ACME 自动化和跨进程 / 跨实例全局限流；Brotli 明确留在 Nginx / 前置代理，不作为 Pingora 直连接管的阻断项。Jenkins / systemd / 健康巡检默认仍按影子发布与巡检模板处理，不作为公网切换依据。
+
+## 启动命令
+
+Pingora 0.8.1 会经 `pingora-core -> flate2(zlib-ng)` 构建 `libz-ng-sys`，构建机必须预装 `cmake` 与 C/C++ 编译器；缺少 `cmake` 时 `cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml` 会停在 `libz-ng-sys` build script。
+
+本机影子验证时先启动 SpacetimeDB 与 `api-server`，再运行：
+
+```bash
+GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT=/srv/genarrative/web \
+cargo run -p pingora-gateway --manifest-path server-rs/Cargo.toml
+```
+
+不依赖完整 dev stack 的本地回归使用仓库脚本：
+
+```bash
+npm run check:pingora-gateway-smoke
+npm run check:pingora-route-parity
+npm run check:nginx-pingora-canary
+npm run check:pingora-canary-docker
+npm run check:pingora-canary-access-log-parity
+npm run check:pingora-direct-preflight
+npm run check:pingora-direct-live
+npm run check:pingora-direct-enable
+npm run check:pingora-direct-rollback
+npm run check:pingora-current-release-audit
+npm run check:pingora-direct-rehearsal-status
+npm run check:pingora-cutover-status-snapshot
+npm run check:pingora-cutover-evidence-bundle
+npm run check:pingora-cutover-evidence-verify
+npm run check:pingora-cutover-evidence-audit
+npm run check:pingora-release-readiness
+```
+
+`check:pingora-gateway-smoke` 会临时启动 mock `api-server`、mock SpacetimeDB、mock Gitea 和 `pingora-gateway`，覆盖 SPA fallback、后台静态路由、HTML / 普通静态资源 `no-cache`、Vite 指纹静态资源 immutable 缓存、静态 `ETag` / `Last-Modified` 与 `304` 协商缓存、静态 `HEAD` 响应、静态 Range、静态 access log method/path/status 对账、gzip 最小长度、小响应不压缩、图片资源不压缩、大响应压缩、ACME、TLS 直连、HTTP/2 ALPN、HTTP 到 HTTPS 重定向、内部路由拒绝、shadow probe、API 代理头（`Host` / `X-Forwarded-Host` / `X-Forwarded-Proto` / `X-Real-IP` / `X-Forwarded-For`）、Gitea Host 整站转发、请求体上限、429 接流保护、上游断连 / 超时 JSON 错误、维护模式、维护模式不拦截 Gitea Host 和 SpacetimeDB WebSocket Upgrade，并复用 `check-pingora-direct-live.mjs` 对临时 HTTPS / HTTP redirect / WSS subscribe 入口做 live smoke。该本地 fixture 会让首页同时引用普通静态资源和 Vite 指纹静态资源，direct live JSON 必须确认指纹资源 GET / HEAD / `Range: bytes=0-0` 以及 access log method/path/status 证据，避免正式直连前只证明普通静态读取。排查失败时可追加 `-- --verbose` 输出网关 stderr / stdout；已确认二进制无需重编时可追加 `-- --skip-build`。
+
+`check:pingora-route-parity` 读取 `deploy/pingora/nginx-route-parity.matrix.json`，静态确认生产 / 开发 Nginx 模板、Pingora Rust 路由单测和本文档都覆盖同一组核心路由。`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix` 会读取同一份矩阵，逐条断言 `classify_path` 的路由结果、body limit 和接流保护分组。
+
+`check:nginx-pingora-canary` 会静态校验 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 的本机来源限制、handoff 响应头、probe token 占位、前缀 rewrite、低缓冲和 WebSocket Upgrade 设置，也会校验 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 只能作为独立 loopback `server` 片段使用、默认监听 `127.0.0.1:18083`、写独立 access log、没有 rewrite、覆盖真实 `/api` / `/v1` / `/assets` 代表路径。本机安装了 Nginx 时脚本会额外把两个 snippet 包进临时 `http {}` 执行 `nginx -t`；需要在 CI / 目标 agent 上强制要求真实 Nginx 语法检查时执行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`。
+
+`check:pingora-canary-docker` 会启动 mock `api-server`、mock SpacetimeDB、真实 `pingora-gateway` 和 Docker Nginx，把前缀 canary 与真实路径 canary 两份 snippet 都渲染到临时 Nginx 中，再复用 `check:pingora-canary-live` 验证 Nginx -> Pingora -> 上游的 handoff 链路。临时 Nginx 使用生产同口径 `genarrative_upstream` access log，live smoke 后会继续调用 `scripts/check-pingora-canary-access-log-parity.mjs`，按同一 `request_id` 对账 canary healthz、代表性 API、SpacetimeDB identity 和静态资源路径；前缀模式确认 Nginx rewrite 后路径与 Pingora access log 一致，真实路径模式除 healthz 探针外要求 Nginx path 与 Pingora path 完全一致。默认不拉取镜像；缺少 Docker daemon 或 `nginx:1.27-alpine` 镜像时跳过。CI / 目标 agent 上需要把它作为硬门禁时执行 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull`。
+
+`check:pingora-canary-access-log-parity` 会烟测只读脚本 `scripts/check-pingora-canary-access-log-parity.mjs`，用于目标机 canary 后按 `request_id` 对照 Nginx handoff access log 和 Pingora tab-separated access log。真实目标机前缀 canary 执行时使用 `/opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --nginx-log-file /var/log/nginx/genarrative.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_canary/healthz --path /__genarrative_pingora_canary/api/creation-entry/config`；真实路径 canary 执行时追加 `--realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --path /__genarrative_pingora_realpath_canary/healthz --path /api/creation-entry/config --path /v1/identity --path /assets/app.js`。脚本只读日志，不修改日志、不 reload Nginx 或 Pingora。
+
+`check:pingora-direct-preflight` 默认只检查仓库内主 service、direct-entry drop-in 和 env 示例，适合本机提交前护栏。目标机直连切换窗口必须提供真实 env 并打开现场检查：
+
+```bash
+npm run check:pingora-direct-preflight -- \
+  --env-file /etc/genarrative/pingora-gateway.env \
+  --require-live-env \
+  --systemd-cat \
+  --check-cert-readable \
+  --check-service-env-file \
+  --check-service-user-cert-readable \
+  --check-service-binary-executable \
+  --check-ports-free
+```
+
+该命令只在切换窗口中用于直连入口验收，必须确认 Nginx 或其它进程已从 `80/443` 摘掉，`--check-cert-readable` 会先证明当前执行用户可读 TLS 文件，`--check-service-env-file` 会确认 service 模板读取的 `EnvironmentFile=` 包含本次 `--env-file`，并在同时启用 `--systemd-cat` 时复核 systemd 最终生效配置也读取同一份 env，`--check-service-user-cert-readable` 会按 `genarrative-pingora-gateway.service` 的 `User=` 推导服务用户并验证其可读证书链和私钥，`--check-service-binary-executable` 会从 service `ExecStart=` 推导 current release 的 `pingora-gateway` 路径并确认文件存在且可执行，`--check-ports-free` 会在授予低端口能力前证明 TLS / HTTP redirect 监听端口当前可绑定。preflight 还会复核 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT`：开启网关保护且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 时，必须同时设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则视为把进程内保护错误放大到多实例并直接失败。
+
+`check:pingora-direct-enable` 会用临时模板和 drop-in 路径验证 `pingora-direct-enable.sh` 的默认 dry-run 不安装文件、会打印安装 drop-in / `systemctl daemon-reload` / 重启 Pingora / 启用后 `systemctl cat` 生效核验命令，并覆盖启用前 direct preflight、模板 / 目标 drop-in / preflight env 相对路径负例，以及 `--apply` 缺少 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable` 或 `--preflight-check-ports-free` 时必须失败。启用脚本 apply 后会以 `--json` 运行 direct live smoke，并解析 stdout 中的 `direct-access-log` 结构化结果；缺少该结果、`matchedCount != checked`、`missingCount != 0` 或 `mismatchCount != 0` 都会让启用失败，避免只看 direct live 退出码。`check:pingora-direct-rollback` 会用临时 drop-in 文件验证 `pingora-direct-rollback.sh` 的默认 dry-run 不修改文件、会打印移除 drop-in / `systemctl daemon-reload` / 重启 Pingora / 回退后 `systemctl cat` 移除核验 / `systemctl show ... ExecStart` 指向核验 / `nginx -t` / reload Nginx / reload 后 `systemctl is-active` / Nginx smoke 命令，并覆盖相对路径负例、`--apply` 缺少 `--reload-nginx` 或 `--nginx-smoke-url` 必须失败、`nginx -t` 失败时不能先删除 drop-in、systemd `ExecStart` 指向旧 release 时必须失败，以及 Nginx smoke 失败必须失败。两类检查都不接触 `/etc/systemd`，用于保证切换启用和失败回退路径不是只停留在文档里。
+
+`check:pingora-current-release-audit` 会烟测 `scripts/ops/pingora-current-release-audit.mjs` 的只读边界、current release 必备脚本 / 配置目录、可选 `pingora-gateway` 可执行性和 `--systemd-show` 下的 `ExecStart` 指向。正式直连 runbook 会先执行 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`，在采集状态快照前确认目标机 current release 本身自包含；显式 `--timeout-ms` 和 `GENARRATIVE_PINGORA_CURRENT_RELEASE_TIMEOUT_MS` 必须是正整数，非法值直接失败，不静默回退默认 `5000`。`GENARRATIVE_PINGORA_CURRENT_RELEASE_REQUIRE_GATEWAY`、`GENARRATIVE_PINGORA_CURRENT_RELEASE_SYSTEMD_SHOW` 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败，不再按 false 继续执行；`--release-root` 必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL 字符，`--systemd-service` 同样不能包含换行或 NUL 字符；启用 `--systemd-show` 时，脚本会在执行 `systemctl show` 前复核子命令可执行文件和参数不含换行或 NUL，避免把污染参数带进只读审计命令。
+
+`check:pingora-direct-rehearsal-status` 会烟测 `scripts/ops/pingora-direct-rehearsal-status.mjs` 的只读彩排状态采集。目标机切换前可执行：
+
+```bash
+node -- /opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs \
+  --release-root /opt/genarrative/current \
+  --expect-public-gateway nginx \
+  --require-pingora-shadow \
+  --require-realpath-canary \
+  --require-current-release-gateway \
+  --fail-on-critical
+```
+
+该脚本只读读取 health patrol env、Pingora env、`systemctl`、`ss -H -ltnp`、realpath canary 配置和 current release 自审结果，输出 JSON 总览；不会写 `/etc`、不会 reload systemd，也不会修改 Nginx 或 Pingora。`--expect-public-gateway nginx` 会要求公网 `80/443` 仍由 Nginx 监听，`--require-pingora-shadow` 会要求 `127.0.0.1:18081` 由 Pingora shadow 监听，`--require-realpath-canary` 会要求 `127.0.0.1:18083` 有 Nginx realpath canary，`--require-current-release-gateway` 会复用 current release 自审确认 `pingora-gateway`、checksum、manifest 和 systemd `ExecStart`。该脚本用于直连前确认现场状态已经进入“可彩排但未切公网”的安全边界，不替代后续证据包，也不做任何启用或回退动作。
+
+`check:pingora-cutover-status-snapshot` 会烟测 `scripts/ops/pingora-cutover-status-snapshot.mjs` 的只读边界、release artifact 采集、health patrol env 复核、systemd capability / EnvironmentFile 判断和 `--fail-on-critical` 行为。正式切换窗口由 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 调用随包状态快照脚本，按 `--phase pre-cutover`、`--phase post-enable`、`--phase post-rollback` 生成时间戳证据目录，保存 `manifest.json`、`snapshot.json`、`snapshot.stdout.txt`、`snapshot.stderr.txt` 和 `snapshot-command.json`；状态快照 stdout 解析失败时保存 `snapshot-parse-error.txt` 并在 manifest / 最终 stdout 中给出路径，启用后 direct live stdout 解析失败时保存 `direct-live-parse-error.txt` 并同样索引。状态快照会把 `--pingora-env-file` 与 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 做精确匹配，支持 `EnvironmentFile=-/path` 和一行多个文件，但不接受路径前缀误判；未包含本次 pingora env 时 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile=false` 并标记 `CRITICAL`。启用后 direct live 结果中的 `direct-access-log` 必须保留 `scannedLineCount`、`matchedCount`、`missing[]`、`mismatches[]` 以及每个 `request_id` 的预期 / 实际 method、path 与 status，避免证据包只留下计数或终端 stderr；静态 GET / HEAD / 304 / Range 结果还必须在 `direct-live.json` 中保留白名单响应头，字段限于 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`，便于复盘缓存分档、校验器和 Range 语义，同时避免把 API / WSS 原始响应头落进正式证据。证据包还会把 `directLiveAccessLog` 和 `directLiveStaticHeaders` 摘要提升到 `manifest.summary`，前者用于快速确认 request_id 对账，后者用于快速确认普通静态 / Vite 指纹静态的 `Cache-Control`、`ETag`、`Last-Modified`、`Content-Length`、Range `Content-Range` 与 304 状态证据；缺少 `direct-access-log` 结构化结果、缺少可判定的静态头摘要，或静态摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 / Last-Modified 304 证据时，证据包都会直接记为 `CRITICAL`。维护模式、非 HTML 或首页确实没有构建资产引用时，direct live 会把静态检查标记为 skipped，此时允许证据包继续记录跳过原因。`snapshot-command.json` 与 manifest 的 `commands[]` 同时保留脱敏后的可读命令和结构化 `executable` / `args[]`，便于路径或参数包含空格时复盘；证据包在执行状态快照或 direct live 子命令前也会拒绝任何带换行或 NUL 字符的子命令参数，避免污染后的 `args[]` 先落盘再等总审计兜底。`--run-direct-live` 使用的 HTTPS / HTTP base URL、Host、redirect Host、probe token、SpacetimeDB 数据库名、Pingora access log 路径和 access log tail 行数也会在证据包配置层先拒绝换行或 NUL，且 `--direct-pingora-access-log` 必须是绝对路径并且不能是文件系统根目录，避免进入 snapshot 或 direct live 子命令后才暴露参数污染。`--phase` 只允许 ASCII 字母、数字、点、下划线和短横线，非法阶段名直接失败，不做隐式清洗，避免目录名和 manifest 阶段漂移；状态快照和证据包的显式 `--timeout-ms` 以及 `GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS` 必须是正整数，非法值直接失败，不再静默回退默认 `5000`。`GENARRATIVE_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST`、`GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL`、`GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_REQUIRE_PINGORA_GATEWAY`、`GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL` 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败，避免 run / require / fail 开关拼写错误后静默按 false 采集证据。状态快照脚本只读采集 `summary`、`healthPatrolEnv`、`pingoraEnv`、`releaseArtifacts`、`systemd` 和 `checks`；probe token 和其他 env 敏感值只记录是否存在，不输出原文，健康巡检、current release 自审等子检查的 stdout / stderr 在进入快照 JSON 前也必须按 env 敏感值脱敏，证据包里的 manifest、snapshot、stdout 和命令记录都必须通过自测确认不落盘 token 原文；状态快照脚本的 `--release-root`、`--health-patrol-env-file` 和 `--pingora-env-file` 都必须是绝对路径、不能是文件系统根目录，也不能包含换行或 NUL 字符，且执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前还会复核子命令参数不含换行或 NUL；证据包脚本只写 `--output-root` 下的新目录，且证据包所有显式路径参数也不能是文件系统根目录，`--output-root` 及其已存在上级路径不能是符号链接，已存在的 `--output-root` 必须是真实目录；路径异常时会在执行状态快照前失败，不写入软链目标、不覆盖既有文件，证据目录权限固定为 `0750`，证据文件权限固定为 `0640`，不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora。
+直连 runbook 的三个证据包阶段都会透传 `--require-pingora-gateway`，让 `checks.current-release-audit.details` 同步归档 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果，避免证据包只有巡检状态而缺少发布物可信度证明。每个证据包生成后都要用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <本阶段bundleDir>` 做只读验真；该脚本只接受 `schemaVersion=1` 的 manifest，并把 `manifest.files` 视为闭集，只读取 `manifest.files` 中的 `{ path, sizeBytes, sha256 }`，拒绝路径逃逸、符号链接证据目录、非目录证据目录、非元数据对象文件条目，以及任何未登记的额外普通文件、目录或符号链接，发现缺文件、大小漂移或 sha256 漂移时退出失败；`--allow-extra-files` 只用于人工排障时显式放行额外条目，正式切换归档不应使用。验真脚本不修改证据目录、不 reload systemd，也不访问 Nginx 或 Pingora。enable apply / rollback apply 的命令证据生成后也要立即用同一个随包 verifier 验真，将上一步 stdout 的 `bundleDir` 分别填入 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>`，确认 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 与 manifest 元数据一致，再继续后续 health patrol 或回退复核。三阶段证据包都生成并分别验真、enable / rollback apply 命令证据和三条 env 变更命令证据也即时验真后，还要执行 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000`，由脚本按 `manifest.phase` 找到每个阶段最新证据目录、按 `manifest.phase + manifest.commandName` 找到五条真实切换命令证据，并复核五条真实切换命令都来自 current release 随包脚本；所有候选证据都必须带合法 `manifest.generatedAt`，格式必须是 `new Date().toISOString()` 产出的 UTC 毫秒格式 `YYYY-MM-DDTHH:mm:ss.sssZ`，最新选择和后续时间线证明只使用该字段，不依赖目录 mtime；随后复用随包 verifier 的 `--require-summary-ok` 严格模式再次只读验真，输出可归档的阶段与命令总表；阶段证据必须是不带 `manifest.commandName` 的状态快照证据包，命令证据不能冒充同名 phase 的阶段证据。总审计输出会把阶段 manifest 中的 `directLiveAccessLog` 与 `directLiveStaticHeaders` 一并带到对应 `phases[]` 项，启用后阶段可直接看到 request_id 对账数量、普通静态和指纹静态的缓存头、校验头、Range `Content-Range` 与 304 状态摘要，不必再逐个打开 bundle manifest；正式 runbook 还会通过 `--require-phase-direct-live-access-log post-enable` 和 `--require-phase-direct-live-static-headers post-enable` 把缺少 request_id 对账摘要、缺少静态头摘要、摘要被跳过或摘要缺少缓存头 / 校验头 / Range / 304 证据的启用后证据判为失败，避免旧 post-enable 证据包混入最终归档。总审计的证据根目录默认只能包含带 `manifest.json` 的证据目录，夹带普通文件、无 manifest 子目录或符号链接都会失败，`--allow-extra-root-entries` 只用于人工排障显式放行，正式切换归档不应使用。总审计不只验文件 hash，还要求所有候选证据 `manifest.schemaVersion=1`，阶段证据 `manifest.summary.status=OK`，命令证据 `manifest.summary.status=OK`、`manifest.summary.exitCode=0` 且无 signal；命令证据的顶层 `manifest.commandName` 和内嵌 `manifest.command.name` 只要存在就必须各自是安全非空命令名，且两者同时存在时必须一致，否则按坏 manifest 处理；并在标准八段证据都被要求时校验每段审计状态都是 `OK`，以及 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback` 的 `manifest.generatedAt` 顺序和默认 24 小时最大跨度，防止从不同切换窗口拼出一组看似完整的最新证据；缺失、非法或非规范格式的 `manifest.generatedAt` 会直接失败，不能靠目录 mtime 兜底；最终总审计还会在 `--require-command-arg` 下要求 enable / rollback 命令证据的 `manifest.command.args` 和独立 `command-record.json.args` 都包含 `--apply`，并在 `--require-cutover-run-id` 下要求所有阶段和命令证据的 `manifest.cutoverRunId` 与本次 runbook 一致；确需跨更长维护窗口时，只能在生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让最终总审计 JSON 可见本次放宽值；证据根目录、verifier 路径、阶段名、命令名或 cutover run id 不安全时直接失败。
+
+正式 runbook 的五个即时验真步骤（`pre-cutover`、`enable-apply`、`post-enable`、`rollback-apply`、`post-rollback`）都必须在随包 verifier 后追加 `--require-summary-ok`，让刚生成的证据包除文件完整性外也立即要求 `manifest.summary.status=OK`；缺少 `summary` 或状态为 `CRITICAL` 时要先修现场状态或重新生成证据，不能等最终根目录总审计才发现。最终 `pingora-cutover-evidence-audit.mjs` 仍是证据根目录、命令身份、`--apply` 参数、时间线和 `cutoverRunId` 的二次总审计，不替代即时验真；它内部复用 verifier 时也必须启用 `--require-summary-ok`。
+
+证据根目录总审计选择每个阶段或命令的“最新证据”时，最新 `manifest.generatedAt` 必须唯一；如果同一阶段或同一命令存在两个或多个候选拥有相同的最新 `generatedAt`，总审计会输出 `AMBIGUOUS_LATEST` 并列出重复目录，不能按目录名排序打平。出现这种情况时应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后重新总审计。
+
+标准八段时间线只要任一阶段或命令证据带 `manifest.cutoverRunId`，八段就必须全部带同一个值；缺字段或混入其它 `cutoverRunId` 都会让总审计失败。八段顺序固定为 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。正式 runbook 仍必须显式传 `--require-cutover-run-id <本次cutoverRunId>`，这条一致性检查只是防止人工临时总审计忘带该参数时把不同切换批次拼在一起。
+
+标准八段时间线失败时，总审计 JSON 的 `timeline.failedCount` 不只是一个笼统红灯，而是按可操作失败项累计；`timeline.failureBreakdown` 会分别输出 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded` 数量，值班人员应按 breakdown 先修对应证据或现场状态，再重新生成总审计。
+
+最终总审计 JSON 的 `summary` 是切换窗口的人工入口：先看 `summary.status` 和 `summary.failedItems[]` 定位失败阶段、命令或根目录诊断，再看 `summary.directLiveEvidence[]` 里的 `accessLog.ok/reason` 与 `staticHeaders.ok/reason` 判断 `post-enable` 是否缺 request_id 对账或静态头证据；完整字段仍保留在 `phases[]`、`commands[]` 与 `timeline` 中供机器归档和深挖复盘。
+
+`--warn-only`、`--allow-extra-files` 和 `--allow-extra-root-entries` 只允许值班人员在正式 runbook 之外作为独立排障命令使用；`plan:pingora-direct-cutover` 生成的正式切换计划不得携带这些放行参数。若需要放行额外证据条目或忽略 `CRITICAL`，应先在证据根目录外保存人工说明、修正现场或重新生成正式证据，而不是把排障开关写进切换 runbook。
+
+`check:pingora-release-readiness` 是正式切换前的聚合门禁，默认串行执行 `cargo test -p pingora-gateway`、mock 上游 smoke、路由矩阵 parity、Nginx canary snippet 校验、Docker handoff smoke、canary access log 对账烟测、realpath canary 启停烟测、直连入口静态预检、直连启用 / 回退 dry-run 行为检查、current release 自审烟测、直连彩排状态烟测、release readiness 计划自检、生产运维护栏、Pingora cutover 状态快照烟测、Pingora cutover 证据包烟测、Pingora cutover 命令证据烟测、Pingora cutover 证据 manifest 验真烟测、Pingora cutover 证据根目录审计烟测、API release build 烟测、Pingora production release 真实构建烟测和 API deploy release 烟测。普通本机执行时 Docker / Nginx 能力仍按子脚本默认口径跳过；切换窗口或 CI 必须执行：
+
+目标机 current release 上的启用前基础门禁和启用后 `--require-direct` 复核使用同一个聚合脚本，但必须追加 `--release-runtime-only`。该模式只执行发布包内可自包含的运行时复核：current release 自审、启用前直连彩排状态复核、live canary、真实 access log 对账、direct preflight、health patrol env 复核和 direct live smoke；不会运行 Cargo、npm、Docker 或 Nginx 源码 / 构建环境门禁，并会拒绝 `--require-docker`、`--pull-docker` 与 `--require-nginx`。未带 `--require-direct` 的启用前基础门禁会自动执行 `scripts/ops/pingora-direct-rehearsal-status.mjs --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical`，确认公网 `80/443` 仍由 Nginx 接流、Pingora shadow 与 realpath canary 高端口在线；启用后 `--require-direct` 复核不再要求 Nginx 接公网的彩排状态，改为检查 direct preflight、health patrol 直连模式和 direct live smoke。
+
+正式 runbook 的 direct enable apply / rollback apply 命令证据必须额外传 `--expected-executable <current release 随包脚本绝对路径>` 和 `--require-arg --apply`；命令证据脚本会在执行前拒绝与预期脚本不一致、缺少必需 `--apply` 参数，或任一真实命令参数包含换行 / NUL 字符的真实命令，并把 `expectedExecutable` 写入 manifest / command-record。命令名只用于审计分类，不能替代真实脚本身份和真实 apply 参数校验。
+
+最终证据根目录总审计还必须传五条真实切换命令的脚本身份和关键参数要求：`--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`--require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`--require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`--require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并要求 `enable-apply:pingora-direct-enable-apply:--apply`、`post-enable:pingora-health-patrol-direct-env-switch:--apply`、`post-enable:pingora-health-patrol-direct-env-switch:pingora-direct`、`rollback-prep:pingora-gateway-shadow-env-switch:--apply`、`rollback-prep:pingora-health-patrol-nginx-env-switch:--apply`、`rollback-prep:pingora-health-patrol-nginx-env-switch:nginx`、`rollback-apply:pingora-direct-rollback-apply:--apply` 这些 `--require-command-arg` 均存在。总审计会复核命令证据里的 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable 都指向 current release 随包脚本，并要求 `manifest.command.args` 与独立 `command-record.json.args` 都包含必需参数，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的路径参数本身也必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符。总审计还要求 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / commandName / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段一致；其中两份命令记录的 `schemaVersion` 都必须是 `1`，stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作。命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`。这些参数会隐式要求对应命令证据存在；缺命令证据、旧证据缺少 `schemaVersion` 或 `expectedExecutable`、缺少必需参数、人工同名证据的 executable 漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染或命令时间线漂移都会失败。
+
+命令证据 manifest 只要出现 `manifest.expectedExecutable` 或 `manifest.command.expectedExecutable` 字段，就必须是安全绝对路径；空字符串、相对路径、文件系统根目录或包含换行 / NUL 的值都会按坏 manifest 处理，不能退化成“未声明 expectedExecutable”。生成端 `pingora-cutover-command-evidence.mjs --expected-executable` 也会在执行真实命令前拒绝相对路径、文件系统根目录和带换行 / NUL 的路径，避免先生成坏命令证据再等最终总审计失败。
+
+命令证据声明 `expectedExecutable` 后，即使最终总审计没有额外传 `--require-command-executable`，`manifest.command.executable` 和独立 `command-record.json.executable` 也必须是同一个绝对路径；二者一致但都指向相对路径，或真实 `executable` 与 `expectedExecutable` 不一致，都会失败。
+
+命令证据必须同时在 `manifest.command.executable` 和独立 `command-record.json.executable` 中记录真实可执行文件绝对路径；只保留可读 `command` 字符串、缺少结构化 `executable` 字段，或两份记录的 `executable` 任一缺失 / 非绝对路径，都不能进入正式证据链。
+
+`pingora-cutover-command-evidence.mjs` 生成证据时，`--` 后面的真实命令也必须直接传绝对路径，不能传 `node`、`bash`、脚本名等 PATH 裸命令名；真实命令不能是文件系统根目录，真实命令和每个真实命令参数都不能包含换行或 NUL 字符，否则生成端会在执行前失败，不创建正式命令证据。runbook 中的 enable / rollback apply 因此必须始终指向 current release 下的绝对脚本路径。
+
+聚合门禁、dry-run plan、cutover runbook、直连启用脚本、直连回退脚本和本机 gateway smoke 可以把 probe token 参数真实传给子脚本，但所有 JSON 输出和命令日志必须显示 `<redacted>`，不得把 direct probe token 或 rollback shadow probe token 原文写入终端、CI 日志或证据包命令记录。
+
+```bash
+node scripts/check-pingora-release-readiness.mjs \
+  --require-docker \
+  --pull-docker \
+  --require-nginx \
+  --require-live \
+  --live-base-url http://127.0.0.1 \
+  --live-host <域名> \
+  --live-nginx-access-log /var/log/nginx/genarrative.access.log \
+  --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log
+```
+
+该命令要求 Docker Nginx handoff、目标机 `nginx -t`、目标 Nginx live canary 和真实 canary access log 对账全部通过。`--require-live` 前必须已经人工 include canary snippet 并 reload Nginx；否则 live smoke 会按预期失败。`--require-live` 会强制要求 `--live-host`，避免只访问 `127.0.0.1` 命中 Nginx 默认 vhost 而不是正式域名 vhost；live smoke 成功后会立即用 `scripts/check-pingora-canary-access-log-parity.mjs` 按 `request_id` 对照 Nginx 与 Pingora access log，默认读取 `/var/log/nginx/genarrative.access.log` 和 `/var/log/genarrative/pingora-gateway.access.log`。`--live-nginx-access-log` 与 `--live-pingora-access-log` 必须是绝对路径且不能是文件系统根目录；单独运行 canary access log 对账脚本时，`--nginx-log-file` 与 `--pingora-log-file` 也遵循同一规则。
+
+Pingora 直连入口切换窗口必须追加：
+
+```bash
+node scripts/check-pingora-release-readiness.mjs \
+  --require-direct \
+  --direct-https-base-url https://127.0.0.1 \
+  --direct-http-base-url http://127.0.0.1 \
+  --direct-host <域名> \
+  --direct-redirect-host <域名或host:port> \
+  --direct-spacetime-database <库名> \
+  --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log \
+  --direct-health-patrol-env-file /etc/genarrative/health-patrol.env \
+  --direct-preflight-env-file /etc/genarrative/pingora-gateway.env \
+  --direct-preflight-systemd \
+  --direct-preflight-check-cert-readable \
+  --direct-preflight-check-service-env-file \
+  --direct-preflight-check-service-user-cert-readable \
+  --direct-preflight-check-service-binary-executable
+```
+
+`--require-direct` 用于 Pingora 已接管后的直连复核，不再要求 `--direct-preflight-check-ports-free`；切换前释放 `80/443` 的证明只放在 `--dry-run-cutover`、启用前 preflight 和 `pingora-direct-enable.sh --apply` 中。
+
+正式执行直连切换前先生成只读 runbook，供当班人员逐条审阅。该命令只打印 JSON，不启动检查、不修改 systemd：
+
+```bash
+npm run plan:pingora-direct-cutover -- \
+  --require-direct \
+  --direct-https-base-url https://127.0.0.1 \
+  --direct-http-base-url http://127.0.0.1 \
+  --direct-host <域名> \
+  --direct-redirect-host <域名或host:port> \
+  --direct-spacetime-database <库名> \
+  --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log \
+  --direct-health-patrol-env-file /etc/genarrative/health-patrol.env \
+  --direct-preflight-env-file /etc/genarrative/pingora-gateway.env \
+  --direct-preflight-systemd \
+  --direct-preflight-check-cert-readable \
+  --direct-preflight-check-service-env-file \
+  --direct-preflight-check-service-user-cert-readable \
+  --direct-preflight-check-service-binary-executable \
+  --direct-preflight-check-ports-free \
+  --cutover-evidence-output-root /var/log/genarrative/pingora-cutover-evidence \
+  --rollback-nginx-smoke-url https://<域名>/ \
+  --rollback-nginx-smoke-expect-body '<!doctype html>' \
+  --rollback-health-patrol-public-base-url <切换前Nginx巡检入口>
+```
+
+runbook 会列出 Host 与回退巡检入口确认、切换前 current release 自包含自审、切换前状态快照证据包、切换前证据 manifest 只读验真、current release 随包 preflight、启用前基础门禁、direct enable dry-run、direct enable apply、启用命令证据 manifest 只读验真、用 current release 随包 `scripts/deploy/pingora-health-patrol-env-switch.mjs --apply` 把 health patrol 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后状态快照证据包、启用后证据 manifest 只读验真、启用后 `--require-direct` 复核、rollback dry-run、用 current release 随包 `scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply` 在 rollback apply 前把 Pingora env 预置回 shadow、用 health patrol env 切换脚本在 rollback apply 前把 health patrol 预置回 `nginx`、rollback apply、回退命令证据 manifest 只读验真、回退后 health patrol env Nginx 模式复核、回退后状态快照证据包、回退后证据 manifest 只读验真和切换证据根目录三阶段总审计。rollback dry-run / apply 必须显式传 `--nginx-smoke-expect-body`，该片段必须来自切换前真实 Nginx 入口响应；dev 实测证明默认 `/healthz` 并不总是公网 Nginx 可用端点，因此不要把 `http://127.0.0.1/healthz` 或固定 `"ok":true` 当作通用回退 smoke。启用前 current release 自审使用 `--require-pingora-gateway --systemd-show`，先确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、`release-manifest.api-server.json` 已登记 `pingora-gateway`、`pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release；启用前基础门禁不带 `--require-direct`，因为此时 systemd direct-entry drop-in 尚未生效；启用后复核必须带 `--require-direct`，但不再检查 `--direct-preflight-check-ports-free`，因为此时 `80/443` 应由 Pingora 直连入口占用。若切换参数提供 `--direct-probe-token`，启用后复核也会继续透传该 token 检查内部探针，JSON runbook 只显示 `<redacted>`。三个状态快照证据包都使用 current release 随包脚本，显式传 `--output-root <证据根目录>` 和同一个 `--cutover-run-id`，并带 `--require-pingora-gateway --run-health-patrol --fail-on-critical`，用于把切换前基线、启用后 direct 状态、回退后 Nginx 状态和当前发布物自审结果留成可归档证据；其中启用后证据包还会额外传 `--run-direct-live`，把 direct live smoke 的 `direct-live.json`、stdout / stderr、命令记录和 Pingora access log `request_id` 反查结果一起写入同一证据目录，且 `direct-access-log` JSON 要保留匹配数量、缺失明细和 method/path/status 漂移明细，避免只在终端输出里保留直连证据；`post-enable` 证据包会传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包会传 `--expected-pingora-env-mode shadow`。证据包 manifest 会给已生成的 snapshot、direct live、stdout / stderr、命令记录和 parse-error 文件记录 `path`、`sizeBytes` 与 `sha256`，并把 Pingora env 的 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode` 和 `shadowReady` 提升到 `manifest.summary.pingoraEnvShadow`，用于证明回退后 active env 已恢复到 `127.0.0.1:18081` shadow，且低端口 TLS / HTTP redirect / 证书路径均已清空；direct enable apply / rollback apply 通过命令证据脚本归档时，命令证据 manifest 也会给 `command.stdout.txt`、`command.stderr.txt` 和 `command-record.json` 同步记录 `sizeBytes` 与 `sha256`。每次复制或归档证据目录后，都要把对应阶段 stdout 中的 `bundleDir` 填入 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <bundleDir>` 做只读验真，确认文件未在归档过程中损坏或被替换；enable / rollback apply 命令证据生成后也要分别把 stdout 中的 `bundleDir` 填入 verifier 的 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>` 占位符，先验真命令证据，再继续 health patrol 切换或回退后复核；三阶段证据、enable / rollback apply 命令证据和三条 env 变更命令证据都完成并即时验真后，再运行 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-phase-pingora-env-shadow post-rollback --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000` 生成总审计 JSON，并在 JSON 中记录 `requiredCutoverRunId`、`requiredCommandExecutables`、`requiredCommandArgs`、`timeline.maxSpanMs` 与 `timeline.spanMs`。若 snapshot 或 direct live stdout 解析失败，证据包会保留对应 `*-parse-error.txt` 并写入 manifest 索引。`--cutover-release-root` 与 `--cutover-evidence-output-root` 必须是绝对路径，且不能是文件系统根目录，证据根目录默认 `/var/log/genarrative/pingora-cutover-evidence`；`--cutover-evidence-timeline-max-span-ms` 默认 `86400000`，仅用于明确批准超过 24 小时的维护窗口。
+
+runbook 中“启用前基础门禁”和“启用后 `--require-direct` 复核”都调用 current release 随包 `scripts/check-pingora-release-readiness.mjs --release-runtime-only`。前者不带 `--require-direct`，因为 direct-entry drop-in 尚未生效，并会额外跑直连彩排状态复核，确认 Nginx 仍接公网、Pingora shadow / realpath canary 高端口和 current release 自审均可用；后者必须带 `--require-direct`，不再要求 Nginx 接公网彩排状态，并复核 direct preflight、health patrol env 直连模式和 direct live smoke。
+
+证据 verifier / 总审计的入口路径、verifier 脚本路径和 manifest 登记文件名都不能包含换行或 NUL 字符，避免污染 JSON 证据、终端输出或归档复盘；遇到此类失败应重新生成证据或修正 runbook 参数，不要手工改 manifest 兜底。
+
+命令证据生成端的 `--output-root` 同样必须是安全绝对路径，不能是文件系统根目录、符号链接或包含换行 / NUL 字符；失败时应先修正证据根目录参数，不能让被污染的路径进入 bundleDir / manifestPath 输出。
+
+最终证据根目录总审计命令必须同时带两条真实脚本身份要求：`--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 和 `--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`。这两个参数的 executable 段必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符；否则总审计会在读取证据前失败，避免把被控制字符污染的审计要求带入正式证据链。总审计 JSON 会记录 `requiredCommandExecutables`，用于复盘本次 enable / rollback apply 证据到底绑定了哪两个 current release 随包脚本。
+
+`--live-host`、`--direct-host`、`--direct-redirect-host` 和 `--rollback-nginx-smoke-host` 都只接受域名或 `host:port`，不要填 `https://` URL、路径或查询。`--direct-redirect-host` 用于校验 HTTP redirect `Location` 的目标 host，本机单独 smoke 使用非标准端口验证 redirect 时可填 `127.0.0.1:18443`；但 `--dry-run-cutover` 代表正式切换 runbook，会要求 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 使用同一 hostname，只允许端口不同，避免 redirect 和回退 smoke 打到不同入口。Host 与回退巡检入口确认步骤会同时展示 `rollback-health-patrol-public-base-url` 和 `rollback-health-patrol-public-host`，当班人员必须确认回退巡检入口就是切换前记录值。`--rollback-health-patrol-public-base-url` 必须填写切换前 `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL` 的原值；如果切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，否则 runbook 会要求回退后清空 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST`。若希望回退步骤同时证明 Pingora shadow 高端口仍存活，可给 runbook 追加 `--rollback-pingora-shadow-probe-url` 和 `--rollback-pingora-shadow-probe-token`；两者必须成对出现，URL 必须是 `http(s)`，JSON runbook 会隐藏 token 原文。生产不应使用 `--direct-insecure-tls`，`--require-direct` 会直接拒绝 insecure TLS。
+`--require-direct` 会强制要求同时提供 `--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、`--direct-preflight-systemd`、`--direct-preflight-check-cert-readable`、`--direct-preflight-check-service-env-file`、`--direct-preflight-check-service-user-cert-readable`、`--direct-preflight-check-service-binary-executable` 和 `--direct-spacetime-database`，避免只验证 HTTPS / WSS 而漏掉 HTTP 301、ACME challenge、正式域名 Host/SNI、redirect Location host、Pingora access log 的 request_id 落盘证据、health patrol 仍按 Nginx 模式巡检、systemd drop-in 生效、service 实际读取 env 与 preflight env 一致性、当前用户证书可读性、服务用户证书私钥可读性、current release 二进制可执行性或误用默认 SpacetimeDB 库。`--direct-preflight-check-ports-free` 只属于切换前端口释放门禁，`--dry-run-cutover`、启用前 preflight 和 enable apply 必须带它，启用后 `--require-direct` 复核不能再带它。`--direct-pingora-access-log`、`--direct-health-patrol-env-file` 和 `--direct-preflight-env-file` 必须是绝对路径且不能是文件系统根目录；单独运行 `scripts/check-pingora-direct-live.mjs --pingora-access-log` 或 `scripts/check-pingora-direct-preflight.mjs --env-file` 时同样不能把路径指向 `/`。
+`check-pingora-release-readiness.mjs --help` 的正式直连和只生成 runbook 示例也必须显式带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，确保值班人员复制示例命令时不会因为缺少 direct access log 参数而被 `--require-direct` 拦住。
+
+前缀 canary 已在目标 Nginx 中人工 include 且 reload 后，执行 live smoke：
+
+```bash
+GENARRATIVE_PINGORA_CANARY_BASE_URL=http://127.0.0.1 \
+GENARRATIVE_PINGORA_CANARY_HOST=<域名> \
+npm run check:pingora-canary-live
+```
+
+该脚本只读访问 `GET /__genarrative_pingora_canary/*`，检查 healthz、代表性 API、SpacetimeDB identity、静态资源和 generated 禁止入口，并强制校验 `X-Genarrative-Nginx-Handoff: pingora-canary`。本机用 `http://127.0.0.1` 验证时仍必须设置 `GENARRATIVE_PINGORA_CANARY_HOST=<域名>` 命中正式 vhost；base URL、canary prefix、Host、额外 path 和 timeout 不能包含换行或 NUL，脚本会在发起 canary 请求前失败，避免污染参数进入 URL、Host header 或 JSON 输出。环境变量示例见 `deploy/env/pingora-canary-live.env.example`。live smoke 后用 current release 随包 `scripts/check-pingora-canary-access-log-parity.mjs` 对照 Nginx 与 Pingora access log，确认同一 `request_id` 已在两侧落盘且 method/status/path 没有漂移。
+
+如果已经显式配置 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`，并准备验证 Pingora 不经 Nginx 的直连入口，执行 direct live smoke：
+
+```bash
+GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL=https://127.0.0.1 \
+GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL=http://127.0.0.1 \
+GENARRATIVE_PINGORA_DIRECT_HOST=<域名> \
+GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST=<域名或host:port> \
+npm run check:pingora-direct-live
+```
+
+该脚本只读检查 HTTPS 根路径、HTTP/2 ALPN、代表性 API、SpacetimeDB identity、WSS `/v1/database/<database>/subscribe` 握手、generated 禁止入口、公开 `/healthz` 拒绝、可选 shadow probe，以及 HTTP 入口到 HTTPS 的 301 和 ACME challenge 静态读取；真实 SpacetimeDB 对 `GET /v1/identity` 返回 `405 Method Not Allowed` 属于可接受语义，direct live 只把它作为路径转发代表，不要求该 GET 创建 identity；配置 `--pingora-access-log` 后还会为每个请求生成 `X-Request-Id` 并反查 Pingora access log，逐条比对同一 `request_id` 的 method、path 与 status，证明直连流量真实进入 Pingora，且未发生日志侧方法 / 路径 / 状态漂移。HTTP 响应必须带 `X-Genarrative-Gateway: pingora-shadow`，TLS ALPN 必须协商到 `h2`，WSS 成功握手时必须保留 `v2.bsatn.spacetimedb` 子协议。release readiness `--require-direct` 会自动要求 WSS 返回 101，并要求提供 direct HTTP base URL、正式域名 Host/SNI、redirect Location host、显式 SpacetimeDB 数据库名和 Pingora access log 路径，让 HTTP/2、HTTP redirect / ACME 入口、正式证书域名、跳转目标域名、目标库 subscribe 和 request_id + method/path/status 对账证据都纳入硬门禁；单独运行 direct live smoke 时也可加 `--require-wss-upgrade` 强制同一口径。direct live 在首页发现 `/assets/` 或 `/admin/assets/` 引用时会额外执行静态资源 GET、HEAD、`If-None-Match` / `If-Modified-Since` 条件请求和 `Range: bytes=0-0` 探针，确认静态头、HEAD 头响应、`304` 协商缓存、`206 + Content-Range` 以及不压缩 Range / 304 响应均进入同一 access log 证据链；这些静态 GET / HEAD / 304 / Range 的 JSON 结果会写入白名单 `headers`，只保留 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`，方便切换后复盘缓存和 Range 响应头。若发现 Vite 指纹资源，还会额外确认 `Cache-Control: public, max-age=31536000, immutable` 及其 GET / HEAD / 304 / Range method/path/status 证据，避免旧 tab chunk 缓存口径在直连后退化。direct live 的 HTTPS / HTTP base URL、Host、redirect Host、probe token、额外 path、SpacetimeDB 数据库名、access log 路径、timeout 和布尔 env 都不能包含换行或 NUL；脚本会在发起 HTTPS / HTTP / WSS 请求前失败，避免污染参数进入请求头、URL、日志对账或 JSON 证据。环境变量示例见 `deploy/env/pingora-direct-live.env.example`。生产证书必须可被系统信任；`--insecure-tls` 只允许本机自签证书 smoke 使用。`--skip-wss` 只允许单独 direct live 临时排障，release readiness `--require-direct` 会直接拒绝。
+
+生产发布包默认不携带 Pingora，避免现有 API 流水线被影子网关构建依赖影响。需要部署影子服务时，构建机先确保有 `cmake`、C/C++ 编译器和 Rust target，再显式执行；`build-production-release.sh` 会在真实构建 Pingora 前 fail-fast 检查 `cmake`、C 编译器和 C++ 编译器，Jenkins `INCLUDE_PINGORA_GATEWAY=true` 时也会先检查这些工具：
+
+```bash
+npm run build:production-release -- --component api-server --name <version> --include-pingora-gateway
+```
+
+Jenkins `Genarrative-Api-Build` 对应参数是 `INCLUDE_PINGORA_GATEWAY`，默认关闭；勾选后才会归档 `pingora-gateway` 与 `pingora-gateway.sha256`，触发后续 `Genarrative-Api-Deploy` 时也会传递该布尔参数并复制这两个可选产物。无论是否打包 Pingora 二进制，API release 都必须携带 `build/<version>/scripts/deploy/production-api-deploy.sh`、同目录的 `maintenance-on.sh` / `maintenance-off.sh`、`/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`pingora-direct-rollback.sh`、`pingora-tls-cert-sync.mjs`、`scripts/ops/pingora-current-release-audit.mjs`、`scripts/ops/pingora-cutover-status-snapshot.mjs`、`scripts/ops/pingora-cutover-evidence-bundle.mjs`、`scripts/ops/pingora-cutover-command-evidence.mjs`、`scripts/ops/pingora-cutover-evidence-verify.mjs`、`scripts/ops/pingora-cutover-evidence-audit.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/check-pingora-canary-access-log-parity.mjs`、`scripts/check-production-health-patrol-env.mjs`、`deploy/systemd/`、`deploy/env/` 和 `deploy/pingora/`。`Genarrative-Api-Deploy` 只能从上游构建归档复制并执行 `build/<version>/scripts/deploy/production-api-deploy.sh`，不能继续执行部署工作区根部脚本；维护脚本必须与 deploy 脚本来自同一发布包同一目录，避免 Jenkins 工作区里的旧脚本掩盖 release 包布局缺陷。直连启用脚本从 current release 执行时默认读取 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，必须能自包含完成 preflight、systemd 模板读取和 direct live smoke，不依赖 Jenkins 工作区、目标机源码 checkout 或 `/etc` 参考模板；current release 自审、TLS 证书同步、health patrol env 复核、canary access log 对账、canary live、direct live、状态快照、证据包、命令证据、证据验真和证据根目录审计也必须来自 current release 随包脚本与 `deploy/env/`。`/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 只作为 Server-Provision 安装的人工审阅 / 手动覆盖模板；确需使用时显式传 `--template-path` 或 `GENARRATIVE_PINGORA_DIRECT_TEMPLATE_PATH`。`npm run check:production-api-release` 会用临时 `CARGO_TARGET_DIR` 和假 `api-server` / `pingora-gateway` release binary 跑 `build-production-release.sh --component api-server --skip-api-build`，动态验证默认 API release 不登记 Pingora，显式 `--include-pingora-gateway --skip-pingora-gateway-build` 时则必须包含 `pingora-gateway`、`pingora-gateway.sha256` 并写入 manifest，同时验证 Pingora 直连依赖、TLS 证书同步脚本、current release 自审脚本、状态快照脚本、证据包脚本、命令证据脚本、证据验真脚本、证据根目录审计脚本、canary access log 对账脚本、健康巡检 env 复核脚本、env 示例目录、API deploy 执行入口自包含和 `deploy/pingora/pingora-gateway.env.example` 的生产安全默认值：gzip-only、`TRUST_X_FORWARDED_FOR=false`、`TRUSTED_FRONT_PROXY_CONFIRMED=false`、接流保护默认开启、probe token 为空；该检查还会读取发布包 README，并直接运行发布包内 `scripts/check-pingora-release-readiness.mjs --dry-run-cutover`，确认最终证据根目录总审计步骤仍带两条 `--require-command-executable ... /opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` / `pingora-direct-rollback.sh` current release 脚本身份要求。`npm run check:pingora-production-release-build` 会用假 `api-server`、临时 `CARGO_TARGET_DIR` 和真实 `cargo build -p pingora-gateway --release --target x86_64-unknown-linux-gnu` 验证显式 include 路径能构出可执行 `pingora-gateway`、checksum 和 manifest 登记，避免只靠假二进制布局 smoke。`production-api-deploy.sh` 对这些 Pingora 直连依赖采取 fail-fast：上游发布产物缺失时保持维护模式并停止部署，不再从部署工作区兜底复制；`release-manifest.json` 必须存在且登记 `api-server` artifact，若发布包包含 `pingora-gateway`，manifest 也必须登记 `pingora-gateway` artifact，否则部署会在切换 current 前失败。API deploy 要求 `--release-root`、`--current-link`、`--api-env-file` 使用绝对路径，`--version` 必须以数字或字母开头并拒绝点目录，会先写 `${RELEASE_ROOT}/.${VERSION}.staging.$`，全部校验和复制完成后用非合并语义提升为 `${RELEASE_ROOT}/${VERSION}`，再用固定替换语义切换 current 符号链接；同版本正式 release 已存在、提升前竞态出现或 current 路径不是符号链接时都会拒绝合并 / 覆盖，失败时清理 staging 并保持维护模式。本机用 `npm run check:production-api-deploy` 通过临时 release、fake `systemctl` / `curl` 动态验证从发布产物内执行 deploy 脚本后 current release 自洽，并覆盖缺少 TLS 证书同步脚本、current release 自审脚本、状态快照脚本、证据包脚本、证据验真脚本、证据根目录审计脚本、canary access log 对账脚本、健康巡检 env 复核脚本、`deploy/env/`、release manifest、api-server manifest artifact、Pingora manifest artifact、相对 release root / current link / api env file、点目录或点开头 version、同版本 release 目录已存在、current 路径不是符号链接或提升前 release 目录竞态出现时必须失败，同时复核 current release 内 Pingora env 示例仍保持同一组生产安全默认值。
+
+API release 还必须携带 `scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs` 与 `scripts/ops/pingora-direct-rehearsal-status.mjs`。前者支撑 current release 的 `--release-runtime-only` 聚合复核，canary live 脚本支撑目标 Nginx canary live smoke，直连彩排状态脚本支撑目标机切换前只读确认 Nginx 仍接公网、Pingora shadow / realpath canary 高端口和 current release 自审均可用；缺少任一脚本时 `check:production-api-release`、`check:production-api-deploy` 和生产运维护栏都必须失败。
+
+发布包会额外包含 `pingora-gateway` 与 `pingora-gateway.sha256`。`production-api-deploy.sh` 看到这两个文件时会校验并把 `pingora-gateway` / `pingora-gateway.sha256` 一起复制到 `/opt/genarrative/current`，供 shadow systemd 模板和 current release 自审使用；`api-server.sha256` 也必须随 `api-server` 一起进入 current release。没有这两个 Pingora 文件时现有 API 发布行为不变。API 发布仍只重启 `genarrative-api.service`；包含 Pingora 时，部署脚本会在提升 release 和切换 `current` 前读取 `systemctl cat genarrative-pingora-gateway.service` 与其 `EnvironmentFile`，拒绝已出现 `CAP_NET_BIND_SERVICE` direct-entry capability、拒绝 `GENARRATIVE_PINGORA_GATEWAY_LISTEN` 不是 `127.0.0.1:18081`、拒绝已配置 `TLS_LISTEN` 或 `HTTP_REDIRECT_LISTEN`，确认仍是本机 shadow 高端口后才切换 current，并执行 `systemctl restart genarrative-pingora-gateway.service` 后复核 active。该自动拉起只覆盖 shadow 服务，不会启用公网 `80/443` 直连入口；若现场已经处于 direct-entry 状态，应走正式直连 runbook 或先回退到 shadow 后再执行 API deploy。
+
+也可以复制 `deploy/pingora/pingora-gateway.env.example` 到部署环境的非 Git 配置文件，由 systemd 或容器注入。仓库提供 `deploy/systemd/genarrative-pingora-gateway.service` 作为影子服务模板，默认读取 `/etc/genarrative/pingora-gateway.env`，仍只应监听本机高端口，再由 Nginx 或本机 smoke 主动访问。Server-Provision 会把主 service 安装到 `/etc/systemd/system/genarrative-pingora-gateway.service`，并把直连低端口 drop-in 模板安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 作为参考和手动覆盖来源；该模板不会默认生效，`/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 默认使用随 current release 发布的 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`。`deploy/nginx/snippets/genarrative-pingora-canary.conf` 是可选的 Nginx -> Pingora 前缀 canary 模板，Server-Provision 会安装到 `/etc/nginx/snippets/`，但主站配置默认不 include；启用前必须把 `__GENARRATIVE_PINGORA_PROBE_TOKEN__` 替换为真实 token，并确认 `allow/deny` 来源边界符合当次验证窗口。
+
+直连公网入口切换窗口如果需要让非 root 的 `genarrative` 用户绑定 `80/443`，先确认 `/etc/genarrative/pingora-gateway.env` 已显式设置 TLS / redirect 入口和证书路径，并确认 `genarrative` 用户可读取证书链和私钥；生产 `80/443` 还必须先从 Nginx 或其它进程释放，非切换窗口建议先用 `18443/18080` 这类高端口验证。若证书来自 Certbot / Let’s Encrypt，不要放宽 `/etc/letsencrypt/live` 或 `archive` 的目录 / 私钥权限；先用随包 `pingora-tls-cert-sync.mjs` 把 live symlink 解析后的真实证书复制到 `/etc/genarrative/pingora-tls/<域名>/`，再把 env 中 `TLS_CERT_FILE` / `TLS_KEY_FILE` 指向该私有副本：
+
+```bash
+sudo -n node -- /opt/genarrative/current/scripts/deploy/pingora-tls-cert-sync.mjs \
+  --apply \
+  --source-cert-file /etc/letsencrypt/live/<域名>/fullchain.pem \
+  --source-key-file /etc/letsencrypt/live/<域名>/privkey.pem \
+  --target-dir /etc/genarrative/pingora-tls/<域名>
+```
+
+该脚本默认 dry-run，`--apply` 才原子写入 `fullchain.pem` / `privkey.pem`，目标目录默认 `root:genarrative 0750`，文件默认 `root:genarrative 0640`，并复核 `genarrative` 服务用户可读；目标目录和目标文件不能是符号链接。随后先 dry-run 直连启用脚本：
+
+```bash
+npm run plan:pingora-direct-cutover -- --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --rollback-nginx-smoke-url https://<域名>/ --rollback-nginx-smoke-expect-body '<!doctype html>' --rollback-health-patrol-public-base-url <切换前Nginx巡检入口>
+/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status
+```
+
+`plan:pingora-direct-cutover` 只打印切换 runbook，不执行命令。默认 enable dry-run 会展示 apply 前执行 current release 自审，以及安装 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf` 到 `/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf` 的命令。只有需要临时使用 Server-Provision 安装到 `/etc/genarrative/pingora/` 的参考模板时，才显式传 `--template-path /etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf`。切换窗口覆盖 `--preflight-script`、`--direct-live-script`、`--current-release-audit-script`、`--template-path`、`--service-unit-path`、`--dropin-path` 或 env 文件路径时必须使用绝对路径且不能是文件系统根目录；`--apply` 会在安装 drop-in 前确认 current release 自审、direct preflight 和 direct live smoke 脚本都真实存在，脚本缺失时直接失败。直连启用脚本的 service、路径、URL、Host、probe token、access log、数据库名、tail 行数和 timeout 参数都不能包含换行或 NUL；脚本会在 current release 自审、preflight、drop-in 写入和 systemctl 前失败。`--apply` 还会拒绝符号链接形式的 drop-in 目录或 drop-in 目标文件，并拒绝已存在但不是普通文件的目标，避免把直连 capability 写入非预期 systemd 位置。
+
+确认 `direct preflight` 已通过且命令符合预期后，再显式执行：
+
+```bash
+/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh \
+  --apply \
+  --preflight-env-file /etc/genarrative/pingora-gateway.env \
+  --preflight-check-cert-readable \
+  --preflight-check-service-env-file \
+  --preflight-check-service-user-cert-readable \
+  --preflight-check-service-binary-executable \
+  --preflight-check-ports-free \
+  --direct-https-base-url https://127.0.0.1 \
+  --direct-http-base-url http://127.0.0.1 \
+  --direct-host <域名> \
+  --direct-redirect-host <域名或host:port> \
+  --direct-spacetime-database <库名> \
+  --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log
+systemctl cat genarrative-pingora-gateway.service | grep -E 'AmbientCapabilities|CapabilityBoundingSet'
+grep -E 'GENARRATIVE_PINGORA_GATEWAY_(TLS_LISTEN|HTTP_REDIRECT_LISTEN|TLS_CERT_FILE|TLS_KEY_FILE)=' \
+  /etc/genarrative/pingora-gateway.env
+```
+
+仓库工作区也可以执行 `npm run deploy:pingora-direct-enable -- --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。`--apply` 会先执行随包 `scripts/ops/pingora-current-release-audit.mjs --require-pingora-gateway --systemd-show`；自审失败、direct preflight 脚本缺失、direct live smoke 脚本缺失、drop-in 目录是符号链接、drop-in 目标是符号链接或已存在目标不是普通文件时不会安装 direct-entry drop-in。`--apply` 缺少 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 或 `--direct-spacetime-database` 会直接失败，避免跳过 env / 当前用户证书可读 / service EnvironmentFile 一致性 / 服务用户证书可读 / service 二进制可执行 / 端口释放预检、正式域名 Host/SNI、HTTP redirect Location host、Pingora access log request_id 落盘或 WSS 目标库验证；`--apply` 安装并重启后还会用 `systemctl cat` 核验 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已进入 systemd 最终配置，用 `systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager` 确认最终 ExecStart 指向随包主 service 模板中的 current release `pingora-gateway`，用 `systemctl is-active` 确认 Pingora service 为 `active`，再执行 direct live smoke，覆盖 HTTPS 根路径、首页引用静态资产自动发现探测、静态资产 `HEAD` 与 `Range: bytes=0-0`、HTTP/2 ALPN、API、SpacetimeDB identity、HTTP redirect / ACME、generated / healthz 拒绝、WSS 101 和 Pingora access log request_id 落盘。首页返回 `200` 且 HTML 中包含 `/assets/` 或 `/admin/assets/` 引用时，direct live 会额外请求该静态资源，确认 `Cache-Control`、`ETag`、`Last-Modified`、`Accept-Ranges: bytes` 和 `HEAD` 头响应，再用 `Range: bytes=0-0` 验证 `206 + Content-Range` 且不压缩，并纳入 `direct-access-log` method/path/status 对账；维护模式、非 HTML 或发布包首页没有资产引用时该项标记为 skipped，不阻断维护窗口。启用脚本会解析 direct live JSON 中的 `direct-access-log` 结果，要求 `matchedCount == checked` 且 `missingCount=0`、`mismatchCount=0`，因此 direct live 退出 0 但缺少结构化 access log 证据也会被视为启用失败。直连启用前必须已把 active `/etc/genarrative/pingora-gateway.env` 提升为直连 env；回退前则必须用 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 把同一文件恢复为 shadow 高端口 env（`GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081` 且清空 TLS / HTTP redirect 低端口监听），否则移除 capability 后重启 Pingora 可能仍按 `80/443` 配置失败。启用后单独复核可执行 `npm run check:pingora-direct-live`；启用后 `--require-direct` 聚合复核不再带 `--direct-preflight-check-ports-free`。验证失败时优先执行随 release 携带的直连回退脚本，移除 drop-in、`systemctl daemon-reload` 并重启 Pingora，让公网入口回到 Nginx：
+
+正式 runbook 的状态快照证据包必须显式传 `--expected-pingora-env-mode`：`post-enable` 使用 `direct`，证明 active `/etc/genarrative/pingora-gateway.env` 已是直连姿态；`post-rollback` 使用 `shadow`，证明回退后的 active env 已恢复 shadow 姿态。`pingora-gateway-env-shadow-switch.mjs --apply` 不只清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，还必须同时清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE`；否则 Pingora 会看到“有证书路径但无 TLS listen”的半直连 env，回退证据也会被判为 `CRITICAL`。
+
+```bash
+/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh \
+  --apply \
+  --reload-nginx \
+  --nginx-smoke-url https://<域名>/ \
+  --nginx-smoke-host <域名> \
+  --nginx-smoke-expect-body '<!doctype html>'
+```
+
+在仓库工作区也可以执行 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-host <域名> --nginx-smoke-expect-body '<!doctype html>'`；不带 `--apply` 时只打印将执行的命令，适合切换前复核。回退脚本 `--apply` 必须同时带 `--reload-nginx` 和 `--nginx-smoke-url`，且 smoke URL 必须是 `http(s)` URL；执行时会先拒绝带换行或 NUL 的 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override，并拒绝路径参数指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件，并拒绝已存在但不是普通文件的 drop-in 目标，通过后才运行 `nginx -t`、移除 direct-entry drop-in、`systemctl daemon-reload`、重启 Pingora；随后用 `systemctl cat` 确认 `AmbientCapabilities=CAP_NET_BIND_SERVICE` 与 `CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 已从最终 unit 配置中消失，避免只删除文件但 systemd 仍保留旧能力，并用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，避免回退后 shadow 服务继续跑旧发布包；最后 reload Nginx、确认 Nginx service 仍为 `active`，并用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时会额外要求响应体包含预期片段，避免 HTTP 200 命中错误入口。回退 smoke URL 和响应片段必须来自切换前真实 Nginx 响应；dev 当前首页可用 `https://dev.genarrative.world/` 与 `<!doctype html>`，不要沿用固定 `/healthz + "ok":true`。`--nginx-smoke-url` 指向本机 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 必须同时传 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免回退 smoke 命中默认 vhost。覆盖 `--nginx-binary` 或 `--curl-binary` 时可以传裸命令名；如果值包含路径分隔符，则必须使用绝对路径，避免回退窗口受 cwd 影响。若 health patrol env 已先切回 Nginx，可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host`，脚本会在 Nginx smoke 之后调用 current release 的 `scripts/check-production-health-patrol-env.mjs`，确认 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 public base URL / Host 已恢复为切换前记录值；若切换前 Nginx 巡检需要 Host 覆盖，则把 `--health-patrol-require-empty-public-host` 换成 `--health-patrol-expected-public-host <切换前Host>`。若需要同时证明回退后 Pingora 仍作为 shadow 高端口服务存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`；脚本会隐藏 token，并要求探针响应包含 `gateway=pingora-shadow`。同一能力也可由 `plan:pingora-direct-cutover` 的 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token` 写进 rollback dry-run 和 apply 步骤。
+
+生产健康巡检脚本支持可选 shadow probe。将 `deploy/env/health-patrol.env.example` 复制到 `/etc/genarrative/health-patrol.env` 后，同时配置：
+
+```bash
+GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL=http://127.0.0.1:18081
+GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN=<与 pingora-gateway.env 一致的 token>
+```
+
+此时 `genarrative-health-patrol.service` 会额外请求 `GET /__genarrative_pingora/healthz` 并校验返回 `{"ok":true,"gateway":"pingora-shadow"}`；未配置时现有生产巡检行为不变。
+
+Pingora 直连接管公网入口后，巡检口径也必须从 Nginx 切到直连网关，避免因为 `nginx.service` 已停止而误报，同时继续证明正式 Host 语义可用。切换窗口不要手工编辑这三项，使用 current release 随包脚本写入并立即复核：
+
+```bash
+node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs \
+  --apply \
+  --env-file /etc/genarrative/health-patrol.env \
+  --gateway-mode pingora-direct \
+  --public-base-url https://127.0.0.1 \
+  --public-host <域名>
+```
+
+该模式检查 `genarrative-api.service`、`spacetimedb.service`、`genarrative-pingora-gateway.service` 和 Pingora 直连 public probe；脚本只管理 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST`，保留其它巡检配置，并会先对权限固定为 `0600` 的临时目标 env 调用 `/opt/genarrative/current/scripts/check-production-health-patrol-env.mjs` 复核，复核通过后才按真实 env 原权限、owner/group 原子替换，复核失败不会落盘。env 切换脚本的 `--env-file`、`--check-script` 以及 health patrol env 复核脚本的 `--env-file` 都必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本的 `--public-base-url` 与 `--public-host` 同样不能包含换行或 NUL。`--apply` 的 `--env-file` 还必须直接指向真实普通文件，不能是符号链接；如果现场 `/etc/genarrative/health-patrol.env` 是链接，应先确认真实目标路径后把真实路径传给脚本，避免切换窗口替换链接本身或写入非预期目标。生产巡检脚本自身的显式 `--timeout-ms`、`--slow-ms`、`GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS` 和 `GENARRATIVE_HEALTH_PATROL_SLOW_MS` 必须是正整数，非法值直接失败，不静默回退默认 `5000ms` / `3000ms`，避免切换窗口因写错阈值而误判巡检质量。回退到 Nginx 前用同一脚本把 mode 和 public base URL / Host 恢复为切换前记录值；若切换前 Nginx 巡检不需要 Host 覆盖，用 `--clear-public-host`：
+
+```bash
+node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs \
+  --apply \
+  --env-file /etc/genarrative/health-patrol.env \
+  --gateway-mode nginx \
+  --public-base-url <切换前Nginx巡检入口> \
+  --clear-public-host
+```
+
+若切换前 Nginx 巡检需要 Host 覆盖，则把最后一项换成 `--public-host <切换前Host>`。脚本默认 dry-run，只有 `--apply` 才写入 env；Pingora direct 模式使用 `https://127.0.0.1` 这类本机 public base URL 时必须带 `--public-host <域名>`。
+
+生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败，不再按 false 继续。
+
+## Nginx canary handoff
+
+当前 canary 只提供人工验证入口，不做随机流量抽样。启用步骤：
+
+1. 在本地或 CI 先执行 `npm run check:pingora-canary-docker`；需要强制真实 Docker Nginx 链路时执行 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull`。该脚本会同时验证 Docker Nginx access log 与 Pingora access log 的 `request_id` 对账，不只看 handoff 响应头。
+2. 确认 `genarrative-pingora-gateway.service` 已作为持久 shadow service 运行在 `127.0.0.1:18081`，`GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN` 非空，并已用真实 `api-server`、SpacetimeDB、静态 Web 目录和 access log 做过本机回环验收；不要直接从一次性 `/tmp` 进程进入 Nginx canary。
+3. 在目标机复制 `/etc/nginx/snippets/genarrative-pingora-canary.conf` 为临时启用版本，替换 `__GENARRATIVE_PINGORA_PROBE_TOKEN__`。
+4. 在 `server {}` 内人工 include 该 snippet，并保持 `allow 127.0.0.1; allow ::1; deny all;` 或改成当次可信来源。
+5. 执行 `npm run check:nginx-pingora-canary`；目标机或 CI 有 Nginx 时执行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`，再执行 `nginx -t && nginx -s reload`。
+6. 执行 `GENARRATIVE_PINGORA_CANARY_BASE_URL=http://127.0.0.1 GENARRATIVE_PINGORA_CANARY_HOST=<域名> npm run check:pingora-canary-live`，确认 healthz、API、SpacetimeDB identity、静态资源和拒绝入口都带 `X-Genarrative-Nginx-Handoff: pingora-canary`。
+7. 必要时再用同一前缀访问其它代表性路由，例如 `/__genarrative_pingora_canary/api/creation-entry/config`、`/__genarrative_pingora_canary/v1/identity` 和 `/__genarrative_pingora_canary/assets/app.js`，并对照直连 Nginx 正常入口和 Pingora shadow 日志。
+8. 执行 current release 随包 `scripts/check-pingora-canary-access-log-parity.mjs --nginx-log-file /var/log/nginx/genarrative.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_canary/healthz --path /__genarrative_pingora_canary/api/creation-entry/config`，确认同一 `request_id`、`path`、`status` 和 `proxy_target` 与 Nginx access log 可对齐。对账脚本的日志路径、canary prefix、必需路径和 `--since-lines` / `GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES` 都不能包含换行或 NUL；若 access log 行里解析出的 URI / path 含控制字符，脚本也会把对应行记为失败，避免污染值进入 JSON 对账输出。
+9. 验证结束后移除 include 并 reload Nginx；不要把该前缀入口当作正式公网 URL。
+
+## dev shadow service 验收记录
+
+2026-06-17 已在 dev 机安装 `genarrative-pingora-gateway.service` 作为持久 shadow service。服务使用 `/opt/genarrative/current/pingora-gateway`，读取 `/etc/genarrative/pingora-gateway.env`，只监听 `127.0.0.1:18081`，上游保持 `api-server=127.0.0.1:8082`、`SpacetimeDB=127.0.0.1:3101`、静态目录 `/srv/genarrative/web`，access log 写入 `/var/log/genarrative/pingora-gateway.access.log`。probe token 只保存在目标机 env 文件，不进入仓库、终端日志或证据包。
+
+本阶段验收只证明 shadow service 和真实上游链路可用，不启用 Nginx include，不 reload Nginx，不绑定公网 `80/443`。验收结果：
+
+- `systemctl is-active genarrative-pingora-gateway.service` 返回 `active`，`NRestarts=0`。
+- `GET /__genarrative_pingora/healthz` 带 `X-Genarrative-Pingora-Probe` 返回 `200` 和 `gateway=pingora-shadow`，不带 token 返回 `404`。
+- `GET /api/creation-entry/config` 经 Pingora 转发到真实 `api-server`，返回 `200 application/json`。
+- `GET /` 从真实 Web 目录返回 `200 text/html`。
+- `GET /v1/identity` 经 Pingora 转发到真实 SpacetimeDB，返回 `405 Method Not Allowed`；这是当前 SpacetimeDB 对 GET identity 的真实语义，只作为路径转发代表。
+- `GET /v1/database/genarrative-prod/subscribe?compression=Brotli` WebSocket Upgrade 经 Pingora 转发到真实 SpacetimeDB，返回 `101 Switching Protocols`，并带 `X-Genarrative-Gateway: pingora-shadow`。
+- `/var/log/genarrative/pingora-gateway.access.log` 已记录 healthz、API、静态、SpacetimeDB identity 和 WSS subscribe 的 `request_id`、`path`、`status`、`proxy_target` 与 `upstream`。
+
+dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清理旧 `/tmp/genarrative-*` 临时部署目录、apt cache，并将 journald 收敛到约 `512M`，`df -h /` 从 `100%` 降到约 `92%`。后续 canary / 证据归档前仍应复核 `df -h /`，避免 access log、Nginx reload 或证据归档阶段被磁盘空间干扰。
+
+## dev Nginx prefix canary 验收记录
+
+2026-06-17 已在 dev 机做过一次临时 Nginx prefix canary。步骤是将 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 渲染到 `/etc/nginx/snippets/genarrative-pingora-canary.conf`，只在 `dev.genarrative.world` 的本机 HTTP `server {}` 内临时 include，执行 `nginx -t && nginx -s reload` 后用 `http://127.0.0.1` 与 `Host: dev.genarrative.world` 做 loopback 验收。验证结束后已恢复 `/etc/nginx/conf.d/genarrative.conf` 备份并 reload Nginx；当前正常公网入口仍由 Nginx 原配置承接，Pingora 继续只作为 `127.0.0.1:18081` shadow service 运行。
+
+本阶段验收只证明 Nginx -> Pingora 的前缀 handoff 可用，不做真实路径 canary，不切 `80/443` 到 Pingora。验收结果：
+
+- `node /tmp/check-pingora-canary-live.mjs --base-url http://127.0.0.1 --host dev.genarrative.world --json` 通过：healthz `200`、API config `200`、SpacetimeDB identity `405`、静态代表路径 `404`、generated 拒绝路径 `404`，全部带 `X-Genarrative-Nginx-Handoff: pingora-canary`。
+- 通过 Nginx 前缀 canary 访问 `/__genarrative_pingora_canary/v1/database/genarrative-prod/subscribe?compression=Brotli`，WebSocket Upgrade 返回 `101 Switching Protocols`，并带 `sec-websocket-protocol: v2.bsatn.spacetimedb`、`X-Genarrative-Nginx-Handoff: pingora-canary` 和 `X-Genarrative-Gateway: pingora-shadow`。
+- `node /tmp/check-pingora-canary-access-log-parity.mjs --nginx-log-file /var/log/nginx/genarrative.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log ... --json` 对账 `6/6 matched`，`missingCount=0`，`mismatchCount=0`；覆盖 healthz、API config、SpacetimeDB identity、WSS subscribe、静态代表路径和 generated 拒绝路径。
+- 恢复后 `grep genarrative-pingora-canary /etc/nginx/conf.d/genarrative.conf` 无匹配，`GET http://127.0.0.1/__genarrative_pingora_canary/healthz` 在正常 Nginx HTTP 入口回到 `301`，证明临时 canary include 已移除；`genarrative-pingora-gateway.service` 仍为 `active` 且 `NRestarts=0`。
+
+## dev Nginx realpath canary 验收记录
+
+2026-06-17 已在 dev 机做过一次临时 Nginx realpath canary。步骤是将 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 渲染到 `/etc/nginx/snippets/genarrative-pingora-realpath-canary.conf`，并在 Nginx `http` 上下文临时 include 一个只监听 `127.0.0.1:18083` 的独立 `server {}`；执行 `nginx -t && nginx -s reload` 后，用 `http://127.0.0.1:18083` 与 `Host: genarrative-pingora-realpath-canary.local` 做 loopback 验收。验证结束后已恢复 `/etc/nginx/conf.d/genarrative.conf` 备份并 reload Nginx；`127.0.0.1:18083` 已释放，正常公网入口仍由 Nginx 原配置承接，Pingora 继续只作为 `127.0.0.1:18081` shadow service 运行。
+
+本阶段验收只证明真实路径 Nginx -> Pingora handoff 可用，不切 `80/443` 到 Pingora。验收结果：
+
+- `node /tmp/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host genarrative-pingora-realpath-canary.local --json` 通过：healthz `200`、API config `200`、SpacetimeDB identity `405`、静态代表路径 `404`、generated 拒绝路径 `404`，全部带 `X-Genarrative-Nginx-Handoff: pingora-realpath-canary`。
+- 通过真实路径 canary 访问 `/v1/database/genarrative-prod/subscribe?compression=Brotli`，WebSocket Upgrade 返回 `101 Switching Protocols`，并带 `sec-websocket-protocol: v2.bsatn.spacetimedb`、`X-Genarrative-Nginx-Handoff: pingora-realpath-canary` 和 `X-Genarrative-Gateway: pingora-shadow`。
+- `node /tmp/check-pingora-canary-access-log-parity.mjs --realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log ... --json` 对账 `6/6 matched`，`missingCount=0`，`mismatchCount=0`；除 healthz 探针映射到 `__genarrative_pingora/healthz` 外，API config、SpacetimeDB identity、WSS subscribe、静态代表路径和 generated 拒绝路径的 Nginx path 与 Pingora path 完全一致。
+- 恢复后 `grep genarrative-pingora-realpath-canary /etc/nginx/conf.d/genarrative.conf` 无匹配，`ss -ltnp | grep :18083` 无监听，证明临时 realpath canary server 已移除；`genarrative-pingora-gateway.service` 仍为 `active` 且 `NRestarts=0`。
+
+同日下一阶段在 current release `/opt/genarrative/releases/dev-pingora-api-20260617230221` 上重新启用 loopback realpath canary，并用正式 Host `dev.genarrative.world` 验收。第一次把独立 server 写成 `/etc/nginx/conf.d/genarrative-pingora-realpath-canary.conf` 时，因它早于 `genarrative.conf` 加载，`nginx -t` 报 `unknown log format "genarrative_upstream"`；改为 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf` 后 `nginx -t` 和 reload 均通过。随后：
+
+- `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host dev.genarrative.world --json` 通过：healthz `200`、API config `200`、SpacetimeDB identity `405`、静态代表路径 `404`、generated 拒绝路径 `404`，全部带 `X-Genarrative-Nginx-Handoff: pingora-realpath-canary`。
+- `node -- /opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --realpath ... --json` 对账 `12/12 matched`，`missingCount=0`，`mismatchCount=0`。
+- `node -- /opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-realpath-live ...` 通过 current release 自包含自审、realpath live smoke 和 realpath access log 对账，最终对账 `18/18 matched`。
+- 本阶段没有启用前缀 canary，因此不能同时传 `--require-live`；否则正式 HTTP 入口会按 Nginx 策略返回 `301`，并缺少 `X-Genarrative-Nginx-Handoff: pingora-canary`。当前 public `80/443` 仍由 Nginx 承接，realpath canary 只保留在 `127.0.0.1:18083` 用于后续 loopback 复核。
+- 后续 realpath canary 启停统一走 current release 随包脚本：`/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083` 和 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply`。启用脚本固定写入 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`，并在 `nginx -t`、reload 或 live smoke 失败时回滚；关闭脚本在 `nginx -t` 或 reload 失败时恢复删除前配置。
+
+## dev API release 正式路径验收记录
+
+2026-06-17 已在 dev 机用正式 API release 路径部署包含 Pingora 的发布包 `dev-pingora-api-20260617140915`。发布包由分支 `codex/pingoranginx` 的 `68bf3b698a885ee2cd248dcba81e4b57460000f8` 构建，包含 `api-server`、`api-server.sha256`、`pingora-gateway`、`pingora-gateway.sha256`、`release-manifest.json` 和随包部署 / 自审脚本。部署命令从上传到 `/tmp/dev-pingora-api-20260617140915` 的发布包内执行 `scripts/deploy/production-api-deploy.sh`，目标 release root 为 `/opt/genarrative/releases`，current link 为 `/opt/genarrative/current`。
+
+本阶段验收只证明 API release 的正式打包、复制、current 切换、服务重启和 shadow Pingora 随 current 重启可用，不切 `80/443` 到 Pingora。验收结果：
+
+- `production-api-deploy.sh` 进入维护模式后完成 `api-server.sha256` 和 `pingora-gateway.sha256` 校验，复制二进制、checksum、manifest 和 Pingora 直连依赖到新 release，再把 `/opt/genarrative/current` 切到 `/opt/genarrative/releases/dev-pingora-api-20260617140915`，最后退出维护模式。
+- 部署时 `genarrative-pingora-gateway.service` 仍是 shadow 配置，脚本在 current 切换前拒绝 direct-entry capability 和公网监听 env，切换后执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active；`genarrative-api.service`、外部生成 worker 和 worker controller 也完成重启和 active 等待。
+- `/opt/genarrative/current/release-manifest.api-server.json` 记录 `api-server` 和 `pingora-gateway` 两个 artifact，`cd /opt/genarrative/current && sha256sum -c api-server.sha256 && sha256sum -c pingora-gateway.sha256` 均为 `OK`。
+- `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show` 返回 `summary.status=OK`，确认 current release 自包含、checksum 匹配、`pingora-gateway` 可执行，且 systemd `ExecStart` 指向 `/opt/genarrative/current/pingora-gateway`。
+- `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only` 通过，证明目标机可以只依赖 current release 运行 runtime-only 发布自审，不需要源码 checkout 或 Jenkins 工作区。
+- 部署后 `nginx`、`genarrative-api`、`genarrative-pingora-gateway`、`spacetimedb`、`genarrative-external-generation-controller.service` 和 `genarrative-external-generation-worker@1.service` 均为 `active`，API / Pingora / worker 相关服务 `NRestarts=0`。
+- `GET http://127.0.0.1:8082/readyz` 返回 `{"ok":true,"ready":true}`；`GET http://127.0.0.1:8082/api/creation-entry/config` 返回 `200`。
+- `GET http://127.0.0.1:18081/api/creation-entry/config` 经 Pingora shadow 返回 `200`；`GET http://127.0.0.1:18081/v1/identity` 返回真实 SpacetimeDB 语义 `405`。
+- 使用完整 WebSocket 握手头 `Sec-WebSocket-Protocol: v2.bsatn.spacetimedb` 访问 `http://127.0.0.1:18081/v1/database/genarrative-prod/subscribe?compression=Brotli`，HTTP code 为 `101`；curl 的超时退出只发生在 WebSocket 升级后连接保持阶段。少传该子协议时 SpacetimeDB 会返回 `400 no valid protocol selected`，不能作为网关失败证据。
+- Nginx 仍监听公网 `80/443`，Pingora 仍只监听 `127.0.0.1:18081`；`127.0.0.1:18083` 无监听。`https://dev.genarrative.world/` 与 `https://dev.genarrative.world/api/creation-entry/config` 通过本机 `--resolve` 验收均为 `200`，证明正常公网入口仍由 Nginx 承接。
+- 上传到 `/tmp/dev-pingora-api-20260617140915` 的临时发布包已删除；新 release 目录约 `57M`，清理后 dev 根盘约 `92%` 使用率。后续正式证据归档前仍需复核磁盘余量。
+
+2026-06-18 已在 dev 机把 current release 提升到 `dev-pingora-realpath-readiness-20260618151219`，发布包由分支 `codex/pingoranginx` 的 `e79cc5bd0909291431892f5dc7e3e68f839ae52a` 构建，包含最新 `check:pingora-realpath-canary-toggle` 默认门禁。部署后：
+
+- `/opt/genarrative/current/release-manifest.api-server.json` 记录 `source_commit=e79cc5bd0909291431892f5dc7e3e68f839ae52a`，并登记 `api-server` 与 `pingora-gateway` 两个 artifact。
+- `grep 'Pingora realpath canary 启停烟测' /opt/genarrative/current/scripts/check-pingora-release-readiness.mjs` 可确认 realpath canary 启停烟测已进入随包聚合门禁。
+- `nginx`、`genarrative-api`、`genarrative-pingora-gateway`、`spacetimedb`、`genarrative-external-generation-worker@1.service` 和 `genarrative-external-generation-controller.service` 均为 `active`；`/healthz` 与 `/readyz` 返回正常。
+- 公网 `80/443` 仍由 Nginx 监听，Pingora shadow 仍只监听 `127.0.0.1:18081`，真实路径 canary 仍由 Nginx 监听 `127.0.0.1:18083`，本阶段没有执行 `pingora-direct-enable.sh --apply`。
+- `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-realpath-live ...` 通过 current release 自审、直连彩排状态、realpath live smoke 和 realpath access log 对账，最终对账 `47/47 matched`。
+- 部署前 dev 根盘约 `99%`，先清理旧 `/tmp` 发布包，再删除不再作为当前回滚点的旧数字 release `52`、`53`、`54`、`55`、`57`，清理后 `df -h /` 约剩 `3.2G`，避免证据包阶段被磁盘空间干扰。
+
+同日进入正式直连前证据链彩排，但仍未执行公网直连切换：
+
+- 使用 cutover run id `pingora-direct-dev-20260618T1520-realpath-readiness` 生成 `pre-cutover` 证据包：`/var/log/genarrative/pingora-cutover-evidence/20260618T071853Z-pre-cutover`。
+- `node -- /opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir /var/log/genarrative/pingora-cutover-evidence/20260618T071853Z-pre-cutover --require-summary-ok` 返回 `ok=true`，`checkedCount=4`，`failedCount=0`；manifest summary 为 `OK`，`criticalCount=0`，`warningCount=0`。
+- `node -- /opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --dry-run-cutover --require-direct ... --cutover-run-id pingora-direct-dev-20260618T1520-realpath-readiness ...` 生成 22 步 JSON runbook，覆盖 Host 一致性确认、current release 自审、pre-cutover / post-enable / post-rollback 三阶段证据包、enable / rollback 命令证据、health patrol env 切换、启用后 direct live 证据和最终证据根目录总审计；最终总审计包含两条 current release 脚本身份护栏：`--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 与 `--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`。
+- 当前 dev 的正式 `/etc/genarrative/pingora-gateway.env` 还没有进入 direct 模式：缺少 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE`、`GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`，`GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO` 仍为 `http`，且 systemd 最终配置未包含 `AmbientCapabilities=CAP_NET_BIND_SERVICE` / `CapabilityBoundingSet=CAP_NET_BIND_SERVICE`。`check-pingora-direct-preflight.mjs --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free` 因上述缺口失败，符合正式直连前应阻断的预期。
+- dev 已有证书副本 `/etc/genarrative/pingora-tls/dev.genarrative.world/fullchain.pem` 与 `privkey.pem`，权限为 `root:genarrative 0640`，可用于后续 loopback 高端口 direct rehearsal 或正式切换前 env 准备；不要直接放宽 `/etc/letsencrypt/live` / `archive` 权限。
+
+同日已完成不触碰公网 `80/443` 的高端口直连真实演练：
+
+- 基于 `/etc/genarrative/pingora-gateway.env` 生成临时 env `/tmp/pingora-direct-highport-20260618T1535.env`，把 shadow 监听改到 `127.0.0.1:18084`，直连 HTTPS / HTTP redirect 分别设为 `127.0.0.1:18443` / `127.0.0.1:18080`，证书指向 `/etc/genarrative/pingora-tls/dev.genarrative.world/`，`FORWARDED_PROTO=https`，access log 独立写入 `/var/log/genarrative/pingora-direct-highport-20260618T1535.access.log`。
+- `node -- /opt/genarrative/current/scripts/check-pingora-direct-preflight.mjs --env-file /tmp/pingora-direct-highport-20260618T1535.env --require-live-env --check-cert-readable --check-service-user-cert-readable --check-ports-free --allow-loopback-only --json` 通过，确认两个高端口可绑定，当前用户和 `genarrative` 用户都可读 TLS cert/key。
+- 独立演练进程通过临时 systemd unit `genarrative-pingora-direct-highport-pingora-direct-highport-20260618T1535.service` 启动 `/opt/genarrative/current/pingora-gateway`，只读取临时 env，不改正式 `genarrative-pingora-gateway.service`、不安装 direct-entry drop-in、不重启 Nginx。
+- `node -- /opt/genarrative/current/scripts/check-pingora-direct-live.mjs --https-base-url https://127.0.0.1:18443 --http-base-url http://127.0.0.1:18080 --host dev.genarrative.world --redirect-host dev.genarrative.world --redirect-base-url https://dev.genarrative.world --spacetime-database genarrative-prod --pingora-access-log /var/log/genarrative/pingora-direct-highport-20260618T1535.access.log --access-log-since-lines 4000 --require-wss-upgrade --insecure-tls --json` 返回 `OK`：HTTPS 根路径 `200`、API config `200`、SpacetimeDB identity `405`、HTTP redirect `301` 到正式域名、ACME 静态 `404`、HTTP/2 ALPN `h2`、WSS subscribe `101`，静态资源 `Cache-Control/ETag/Last-Modified/Accept-Ranges`、`HEAD`、`Range 206`、ETag / Last-Modified `304` 全部通过，access log 对账 `19/19 matched`。
+- 演练结束后停止并清理临时 unit；因 Pingora 默认优雅退出窗口较长，临时 unit 曾短暂停在 `stop-sigterm`，确认高端口无监听后对该临时 unit 执行 `systemctl kill -s SIGKILL` 收尾。收尾后 `127.0.0.1:18080`、`127.0.0.1:18084`、`127.0.0.1:18443` 均无监听，正式公网 `80/443` 仍由 Nginx 监听，正式 Pingora shadow 仍为 `127.0.0.1:18081`，realpath canary 仍为 Nginx `127.0.0.1:18083`。
+- 复核 `http://127.0.0.1:8082/healthz` 与 `/readyz` 正常，`curl --resolve dev.genarrative.world:443:127.0.0.1 https://dev.genarrative.world/` 返回 Nginx `HTTP/2 200`，`http://127.0.0.1:18081/__genarrative_pingora/healthz` 带 probe token 返回 `{"ok":true,"gateway":"pingora-shadow","maintenance":false}`。
+- 经验：临时 env 含 `GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL=public, max-age=31536000, immutable` 这类带空格值，不能用 shell `source` 直接加载；演练进程应交给 systemd `EnvironmentFile=` 或使用安全 env 解析器，否则 shell 会把 `max-age=31536000,` 当命令执行。
+
+同日继续进入正式窗口前 final-prep，不执行公网切换：
+
+- `node -- /opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs --release-root /opt/genarrative/current --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical` 返回 `summary.status=OK`：公网 `80/443` 为 Nginx，Pingora shadow 为 `127.0.0.1:18081`，realpath canary 为 Nginx `127.0.0.1:18083`，health patrol env 为 `nginx` 模式且 public base URL 为 `https://dev.genarrative.world`。
+- `node -- /opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show` 返回 `summary.status=OK`，确认 current release 自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、manifest 登记 `pingora-gateway`，且 `genarrative-pingora-gateway.service` 的 `ExecStart` 指向 `/opt/genarrative/current/pingora-gateway`。
+- 生成正式 direct env 候选 `/tmp/pingora-direct-dev-20260618T1548-final-prep.pingora-gateway.env`，与正式 `/etc/genarrative/pingora-gateway.env` 的差异仅为 `FORWARDED_PROTO=https`，追加 `TLS_LISTEN=0.0.0.0:443`、`HTTP_REDIRECT_LISTEN=0.0.0.0:80`、`TLS_CERT_FILE=/etc/genarrative/pingora-tls/dev.genarrative.world/fullchain.pem`、`TLS_KEY_FILE=/etc/genarrative/pingora-tls/dev.genarrative.world/privkey.pem`、`HTTP_REDIRECT_TARGET_SCHEME=https`。该候选 env 的 `check-pingora-direct-preflight.mjs --require-live-env --check-cert-readable --check-service-user-cert-readable` 通过，证明 direct env 内容和证书权限就绪。
+- 生成正式 dry-run cutover runbook `/tmp/pingora-direct-dev-20260618T1548-final-prep.runbook.json`，共 22 步，cutover run id 为 `pingora-direct-dev-20260618T1548-final-prep`，覆盖 pre-cutover 证据、enable/rollback 命令证据、post-enable/post-rollback 证据和最终根目录总审计。后续 runbook 已追加回退前 Pingora env shadow 预置确认，因此步数会大于该早期 final-prep 版本。
+- 注意：该 runbook 仍按正式切换窗口读取 active `/etc/genarrative/pingora-gateway.env`。因此正式执行前必须在维护窗口内先把已审阅的 direct env 提升为 `/etc/genarrative/pingora-gateway.env`，确认 Nginx 释放 `80/443`，再进入 runbook 第 5 步 preflight；否则第 5 步会继续按当前 shadow env 失败。当前阶段未替换 active env、未安装 direct-entry drop-in、未释放 Nginx 端口、未执行 `pingora-direct-enable.sh --apply`。
+
+同日真实 dev 直连 `80/443` 切换已完成一次启用和回退验证：
+
+- 切换前必须释放所有占用公网低端口的进程，不只是主站 Nginx；dev 上还需要临时释放 Gitea vhost，回退时再恢复。
+- Pingora direct 接管 `0.0.0.0:80/443` 后，HTTPS 根路径、API、静态资源 `HEAD` / `Range` / `304`、HTTP/2 ALPN、WSS subscribe 和 Pingora access log 对账均通过，direct access log `19/19 matched`。
+- 启用后 release readiness 不能再要求 `80/443` 空闲；此时端口应由 Pingora 占用。
+- 回退 smoke 不能使用固定 `http://127.0.0.1/healthz` 和 `"ok":true`。dev 实测应使用切换前真实 Nginx 首页，例如 `https://dev.genarrative.world/` 与 `<!doctype html>`。
+- 回退前必须把 `/etc/genarrative/pingora-gateway.env` 从 direct 低端口配置恢复为 shadow 配置；回退后 dev 恢复为 Nginx 监听 `0.0.0.0:80/443`、Pingora shadow `127.0.0.1:18081`、realpath canary `127.0.0.1:18083`，`genarrative-api.service`、`spacetimedb.service`、`nginx.service` 和 `genarrative-pingora-gateway.service` 均 active。
+
+同日继续推进正式 dev 切换时发现 `dev.genarrative.world` 和 `git.genarrative.world` 解析到同一公网 IP；旧 Pingora 只按 path 分流，若直接绑定 `0.0.0.0:80/443` 会把 `git.genarrative.world` 也落到主站静态 / API 路由。新版补齐 Host 分流后，dev 直连切换不应再“临时释放 Gitea vhost 后让 Gitea 不可用”，而应在 direct env 中配置：
+
+- `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world`
+- `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`
+- `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE` 指向同时覆盖 `dev.genarrative.world` 和 `git.genarrative.world` 的证书副本。
+
+当前 dev 的单域名证书 `/etc/letsencrypt/live/dev.genarrative.world/fullchain.pem` 只覆盖 `dev.genarrative.world`，`/etc/letsencrypt/live/git.genarrative.world/fullchain.pem` 只覆盖 `git.genarrative.world`。由于当前 Pingora TLS listener 只加载一组 cert/key，正式直连接管两个 Host 前必须先准备一张覆盖两个域名的证书并同步到 `/etc/genarrative/pingora-tls/<combined-name>/`，或另行实现 SNI 多证书支持。
+
+## 环境变量
+
+| 变量                                                                | 默认值                                     | 说明                                                                                               |
+| ------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `GENARRATIVE_PINGORA_GATEWAY_LISTEN`                                | `127.0.0.1:18081`                          | Pingora 监听地址。                                                                                 |
+| `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`                            | 空                                         | 可选 HTTPS 监听地址；启用时必须同时设置 `TLS_CERT_FILE` 和 `TLS_KEY_FILE`。                        |
+| `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE`                         | 空                                         | 可选 HTTPS 证书链文件；必须是网关运行用户可读取的文件。Certbot 证书建议先同步到 `/etc/genarrative/pingora-tls/<域名>/fullchain.pem`。 |
+| `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`                          | 空                                         | 可选 HTTPS 私钥文件；必须是网关运行用户可读取的文件。Certbot 私钥建议先同步到 `/etc/genarrative/pingora-tls/<域名>/privkey.pem`。 |
+| `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`                  | 空                                         | 可选 HTTP 重定向监听地址；启用时必须已配置 TLS 入口，ACME challenge 仍静态读取。                   |
+| `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_TARGET_SCHEME`           | `https`                                    | HTTP 重定向目标 scheme，当前只允许 `https`。                                                       |
+| `GENARRATIVE_PINGORA_GATEWAY_API_UPSTREAM`                          | `127.0.0.1:8082`                           | `api-server` 上游地址。                                                                            |
+| `GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM`                    | `127.0.0.1:3101`                           | SpacetimeDB 上游地址。                                                                             |
+| `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS`                           | 空                                         | 可选 Gitea Host 白名单，逗号分隔；匹配时整站代理到 Gitea。                                        |
+| `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM`                        | 空                                         | 可选 Gitea 上游；配置 Gitea Host 时必须同时设置。                                                  |
+| `GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT`                              | `/srv/genarrative/web`                     | 前端静态文件根目录。                                                                               |
+| `GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT`                             | `/var/www/html`                            | ACME challenge 静态目录。                                                                          |
+| `GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE`                      | `/var/lib/genarrative/maintenance/enabled` | 存在即进入维护模式。                                                                               |
+| `GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO`                       | `http`                                     | 写入 `X-Forwarded-Proto` 的值。                                                                    |
+| `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES`                    | `67108864`                                 | `/api` 通用路由的 `Content-Length` 上限。                                                          |
+| `GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS`                | `gzip`                                     | 当前唯一允许的压缩算法白名单；Pingora 正式化口径固定为 gzip-only，Brotli 继续由 Nginx / 前置代理承担。 |
+| `GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED`                          | `true`                                     | 是否启用 gzip 响应压缩。                                                                           |
+| `GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL`                            | `5`                                        | gzip 压缩等级，必须在 `0..=9`。                                                                    |
+| `GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES`                 | `1024`                                     | gzip 最小响应长度，默认对齐 Nginx `gzip_min_length 1024`，必须大于 `0`。                           |
+| `GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL`                    | `no-cache`                                 | HTML、目录 index 和 SPA fallback 的缓存头，避免入口 HTML 被长期缓存。                              |
+| `GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL`                   | `public, max-age=31536000, immutable`      | `/assets/*` 与 `/admin/assets/*` 中带 Vite 指纹文件名的静态资源缓存头。                             |
+| `GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL`                  | `no-cache`                                 | 非指纹静态资源和 ACME challenge 的默认缓存头。                                                     |
+| `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_CONNECT_TIMEOUT_MS`           | `3000`                                     | 连接上游的超时，必须大于 `0`。                                                                     |
+| `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS` | `60`                                       | 没有 Nginx 显式长超时的代理路由读取超时，必须大于 `0`。                                            |
+| `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS`     | `3600`                                     | 通用 `/api` 路由读取超时，对齐当前 Nginx `proxy_read_timeout 3600s`。                              |
+| `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_LONG_READ_TIMEOUT_SECONDS`    | `3600`                                     | 公开列表 / 详情和 SpacetimeDB subscribe 长连接读取超时。                                           |
+| `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_WRITE_TIMEOUT_SECONDS`        | `3600`                                     | 写上游请求头 / 请求体超时，对齐当前 Nginx `proxy_send_timeout 3600s` 口径。                        |
+| `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR`                 | `false`                                    | 是否用 `X-Forwarded-For` 首个 IP 作为接流保护 client key；公网直连 Pingora 时必须保持 `false`，direct preflight 会阻断公网监听误开启。 |
+| `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED`         | `false`                                    | 开启 `TRUST_X_FORWARDED_FOR` 时必须显式设为 `true`，表示前置代理会清洗 `X-Forwarded-For`。         |
+| `GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED`                    | `true`                                     | 是否启用单进程接流保护。                                                                           |
+| `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT`                        | `1`                                        | 当前接流保护覆盖的 Pingora 实例数；必须是正整数。开启网关保护且大于 `1` 时必须确认共享保护层。     |
+| `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED`           | `false`                                    | 多实例仍启用网关保护时必须显式设为 `true`，表示已落地共享限流 / 共享并发保护层。                  |
+| `GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_MAX_CONCURRENT`              | `64`                                       | `/admin/api/*` 每 client 并发上限；`0` 表示不限制并发。                                            |
+| `GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_RATE_PER_SECOND`             | `30`                                       | `/admin/api/*` 每 client token bucket 回填速率；`0` 表示不限制 RPS。                               |
+| `GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_BURST`                       | `16`                                       | `/admin/api/*` 每 client 额外 burst。                                                              |
+| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_MAX_CONCURRENT`           | `320`                                      | 公开列表路由每 client 并发上限。                                                                   |
+| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_RATE_PER_SECOND`          | `5000`                                     | 公开列表路由每 client RPS。                                                                        |
+| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_BURST`                    | `4096`                                     | 公开列表路由每 client burst。                                                                      |
+| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_MAX_CONCURRENT`         | `32`                                       | 公开详情兼容路由每 client 并发上限。                                                               |
+| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_RATE_PER_SECOND`        | `300`                                      | 公开详情兼容路由每 client RPS。                                                                    |
+| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_BURST`                  | `32`                                       | 公开详情兼容路由每 client burst。                                                                  |
+| `GENARRATIVE_PINGORA_GATEWAY_API_MAX_CONCURRENT`                    | `64`                                       | 通用 `/api` 路由每 client 并发上限。                                                               |
+| `GENARRATIVE_PINGORA_GATEWAY_API_RATE_PER_SECOND`                   | `300`                                      | 通用 `/api` 路由每 client RPS。                                                                    |
+| `GENARRATIVE_PINGORA_GATEWAY_API_BURST`                             | `64`                                       | 通用 `/api` 路由每 client burst。                                                                  |
+| `GENARRATIVE_PINGORA_GATEWAY_SPACETIME_MAX_CONCURRENT`              | `256`                                      | SpacetimeDB 公开最小路由每 client 并发上限。                                                       |
+| `GENARRATIVE_PINGORA_GATEWAY_SPACETIME_RATE_PER_SECOND`             | `1000`                                     | SpacetimeDB 公开最小路由每 client RPS。                                                            |
+| `GENARRATIVE_PINGORA_GATEWAY_SPACETIME_BURST`                       | `256`                                      | SpacetimeDB 公开最小路由每 client burst。                                                          |
+| `GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN`                           | 空                                         | 内部 shadow 探针 token；为空时探针端点关闭。                                                       |
+| `GENARRATIVE_PINGORA_GATEWAY_LOG`                                   | `info,pingora=info,pingora_gateway=info`   | tracing 过滤器。                                                                                   |
+| `GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE`                       | 空                                         | 可选 access log 文件路径；生产 shadow 示例使用 `/var/log/genarrative/pingora-gateway.access.log`。 |
+| `GENARRATIVE_PINGORA_GATEWAY_OTEL_ENABLED`                          | `false`                                    | 是否启用共享 OpenTelemetry 初始化。                                                                |
+
+## 当前路由口径
+
+| 路由                                                                                      | 行为                                                                                   |
+| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `/.well-known/acme-challenge/*`                                                           | 从 `GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT` 精确读取静态文件，默认 `Cache-Control: no-cache`，并带 `ETag` / `Last-Modified` / `Accept-Ranges: bytes`。 |
+| `/admin`                                                                                  | 301 到 `/admin/`。                                                                     |
+| `/admin/api/*`                                                                            | 转发到 `api-server`。                                                                  |
+| `/admin/assets/*`                                                                         | 从 Web 根目录精确读取静态文件；带 Vite 指纹的文件默认长期缓存，其它文件默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
+| `/admin/*`                                                                                | 先读取静态文件或目录 index，失败回退 `/admin/index.html`，HTML 默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
+| `/assets/*`                                                                               | 从 Web 根目录精确读取静态文件；带 Vite 指纹的文件默认长期缓存，其它文件默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
+| `/api/runtime/puzzle/gallery`、`/api/runtime/custom-world-gallery`                        | 转发到 `api-server`。                                                                  |
+| `/api/runtime/puzzle/gallery/{id}`、`/api/runtime/custom-world-gallery/{profile}/{owner}` | 转发到 `api-server`。                                                                  |
+| `/api`、`/api/*`                                                                          | 转发到 `api-server`，按配置执行 `Content-Length` 与流式 body 累计上限检查。            |
+| `/v1/database/{db}/subscribe`、`/v1/identity*`                                            | 转发到 SpacetimeDB，保留 WebSocket Upgrade 头。                                        |
+| `/__genarrative_pingora/healthz`                                                          | 仅在携带 `X-Genarrative-Pingora-Probe` 且匹配配置 token 时返回 shadow JSON，否则 404。 |
+| `/v1/*`、`/generated-*`、`/healthz*`、`/readyz*`                                          | 返回 404，保持生产公网不暴露口径。                                                     |
+| 其它路径                                                                                  | 先读取静态文件或目录 index，失败回退 `/index.html`，HTML 默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
+
+维护模式下，API-like 路由返回 JSON `503`，Web 静态路由优先返回 `maintenance.html`，不存在时返回纯文本 `503`。
+代理失败时，API / SpacetimeDB 等代理路由返回统一 JSON 网关错误；本地静态路由仍保持对应 HTTP 错误状态。
+静态 `Range` 只支持单段 bytes range；多段 range 暂按完整文件返回，避免在正式替换前引入 multipart 响应面。`If-None-Match` / `If-Modified-Since` 优先于 `Range` 判定，命中时仍返回 `304`；`If-Range` 日期匹配时继续返回 `206`，日期旧于文件或弱 ETag 校验器时回完整 `200`；`206` / `304` / `416` 不做 gzip 压缩，避免 `Content-Range` 语义被响应体改写破坏。Gateway smoke 会用固定 `X-Request-Id` 对账静态 `304`、`405`、`206`、`416` 的 Pingora access log 行，确认本地响应状态也进入正式切换证据链。
+静态路由只允许 `GET` / `HEAD` 读取；其它方法在确认命中静态候选后返回 `405` 并写入 `Allow: GET, HEAD`，缺失文件仍返回 `404`，避免直连后错误客户端把静态入口当作可写接口。
+
+## 后续替换前验收
+
+1. 每次网关行为变更后运行 `npm run check:pingora-gateway-smoke`，确认 mock 上游下的静态、gzip、API 代理头、维护模式、429 保护、上游断连错误和 WebSocket 行为仍通过。
+2. 涉及 Nginx 模板、Pingora 路由、限流分组或路由文档时，同步更新 `deploy/pingora/nginx-route-parity.matrix.json`，并运行 `npm run check:pingora-route-parity` 与 `cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix`。
+3. 容器内使用同一份 Web 产物、同一组真实上游地址跑 Pingora smoke，并继续对照 `deploy/nginx/genarrative.conf` 扩展真实上游路由 parity 自动测试。
+4. 使用 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 做 Nginx 前缀 canary；启用前先跑 `npm run check:nginx-pingora-canary` 和 `npm run check:pingora-canary-docker`，有 Nginx 或 Docker 的目标环境分别强制跑 `node scripts/check-nginx-pingora-canary.mjs --require-nginx` 与 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull`，其中 Docker handoff 会自动对账临时 Nginx 与 Pingora access log。启用后跑 `npm run check:pingora-canary-live`，再用 current release 随包 access log parity 脚本对账目标机 Nginx 与 Pingora access log。canary live 的 base URL、prefix、Host、额外 path 和 timeout 不能包含换行或 NUL；canary live timeout 和 access log `since-lines` 必须是正整数，非法值直接失败。
+5. 前缀 canary 通过后，再使用 current release 随包 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083` 启用真实路径 canary；它会把 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 渲染成独立本机 `server`，写入 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`，不能 include 到生产 `443` server 内。该片段使用 `access_log ... genarrative_upstream`，文件名必须保证晚于定义 `log_format genarrative_upstream` 的主站配置加载；否则 `nginx -t` 会报 `unknown log format "genarrative_upstream"`。启用脚本会先执行 `nginx -t`、reload Nginx，再默认运行 realpath live smoke，任一阶段失败都会恢复写入前配置。关闭时执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply`，脚本会在 `nginx -t` 或 reload 失败时恢复删除前配置。启用后跑 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`，再用 current release 随包 access log parity 脚本传 `--realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log` 对账 `/api/creation-entry/config`、`/v1/identity` 和 `/assets/app.js` 等真实路径。
+6. 目标机 canary include 后必须跑正式切换聚合门禁，并按现场已启用的 canary 入口选择参数：前缀 canary 已启用时，源码 checkout / CI / 构建环境执行 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，目标机 current release 执行 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；真实路径 canary 已启用时，追加或单独使用 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。如果现场只启用了真实路径 canary，不要同时传 `--require-live`；缺少 Host 会直接失败，避免 live canary 误测默认 vhost。live smoke 后还会按 `request_id` 对账 Nginx 与 Pingora access log，缺少同一请求的 Pingora 日志、状态码、方法或 path 漂移都会失败。
+7. 如需评估 Pingora 直连公网入口，必须显式配置 `TLS_LISTEN`、证书、私钥和 `HTTP_REDIRECT_LISTEN`；Certbot 证书先用随包 `scripts/deploy/pingora-tls-cert-sync.mjs` 同步到 `/etc/genarrative/pingora-tls/<域名>/`，不要直接 chmod Let’s Encrypt live/archive 原路径；同一 IP 上还有 Gitea 域名时，还必须配置 `GITEA_HOSTS` / `GITEA_UPSTREAM` 并确认 TLS 证书覆盖所有由 Pingora 直连接管的 Host。绑定 `80/443` 时还必须人工启用 `genarrative-pingora-gateway-direct-entry.conf` drop-in 授予 `CAP_NET_BIND_SERVICE`。随后用 `npm run check:pingora-gateway-smoke` 覆盖 TLS / HTTP/2 ALPN / redirect / WSS subscribe / Gitea Host 分流；目标机必须先跑 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再跑 `npm run check:pingora-direct-live` 或 release readiness 的 `--require-direct`，且 `--require-direct` 必须带 direct HTTPS base URL、direct HTTP base URL、正式域名 Host/SNI、redirect Location host、Pingora access log 文件、health patrol env 文件、direct preflight env 文件、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户和 systemd 服务用户证书可读检查、service 二进制可执行检查、显式 SpacetimeDB 数据库名，并会拒绝 `--skip-wss`。高端口 rehearsal 使用 `https://127.0.0.1:<高端口>` 打入但期望 HTTP redirect Location 指向正式域名默认 HTTPS 入口时，额外传 `--direct-redirect-base-url https://<域名>`；`--direct-redirect-host` 仍必须保留，用于 runbook Host 一致性约束。direct live 会用生成的 `request_id` 反查 Pingora access log；缺少对应日志、method 漂移、path 漂移或 status 漂移都算直连门禁失败。direct preflight 会拒绝开启网关保护但未确认共享保护层的 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 配置；`--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值都不能包含换行或 NUL，执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前还会复核子命令参数，避免污染参数进入目标机预检命令；direct live 的 URL、Host、redirect base URL、probe token、额外 path、数据库名、access log 路径、timeout 和布尔 env 也不能包含换行或 NUL，且会在发起请求前失败；direct live timeout 必须是正整数，直连相关布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败。证书申请与续期仍由 Certbot / 外部自动化承担，网关只读取现有文件。
+8. 正式直连 runbook 的启用前基础门禁和启用后 `--require-direct` 复核必须调用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only`。该脚本、`scripts/check-pingora-canary-live.mjs`、`scripts/ops/pingora-direct-rehearsal-status.mjs`、realpath canary 启停脚本和 `deploy/nginx/` 必须进入生产 API release、Jenkins API Build 归档、Jenkins API Deploy 复制清单和目标机 current release；缺失时部署应 fail-fast，切换窗口不能依赖源码 checkout 或 Jenkins workspace。
+9. direct preflight / direct live timeout 必须是正整数；直连相关布尔 env 和 Pingora gateway env 里的 `TRUST_X_FORWARDED_FOR` / `TRUSTED_FRONT_PROXY_CONFIRMED` 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败。
+10. 最终证据根目录总审计必须带 `--require-phase-pingora-env-shadow post-rollback`；`post-enable` 证据包必须通过 `--expected-pingora-env-mode direct` 证明 active Pingora env 是直连姿态，`post-rollback` 证据包必须通过 `--expected-pingora-env-mode shadow` 证明 active Pingora env 已恢复 shadow 姿态。`manifest.summary.pingoraEnvShadow` 必须证明 `listen=127.0.0.1:18081`，`mode=shadow`，`shadowReady=true`，且 `tlsListen` / `httpRedirectListen` / `tlsCertFile` / `tlsKeyFile` 均为空，避免回退后仍残留 direct 低端口或证书路径 env。
+11. Pingora 正式化口径固定为 gzip-only；Brotli 继续由 Nginx / 前置代理承担，直连 Pingora 不以 Brotli parity 作为切换门禁。如需多实例，开启网关接流保护时必须先引入共享限流 / 共享并发保护层并设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则保持 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT=1`；关闭网关保护的多实例方案必须明确由前置 Nginx / LB 承担全局限流。
+12. 前缀 canary 稳定后，再评估是否做真实路径 canary；真实路径 canary 稳定后，再评估是否让 Pingora 直接承接公网入口。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 3033da8fd..9df1db3aa 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -228,7 +228,7 @@ UI 相关修改要重点验证：
 npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service --restart-service-after genarrative-api.service
 ```
 
-脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service` 依赖 `spacetimedb.service`，生产定时冷备份还必须传入 `--restart-service-after genarrative-api.service`，确保备份后 API 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉该参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service` 依赖 `spacetimedb.service`，生产定时冷备份还必须传入 `--restart-service-after genarrative-api.service`，确保备份后 API 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉该参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node -- ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
 
 生产环境变量模板在 `deploy/env/api-server.env.example`：
 
@@ -270,12 +270,79 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 
 `Genarrative-Server-Provision` 会安装并启用 `genarrative-health-patrol.timer`，默认每 5 分钟运行一次 `genarrative-health-patrol.service`。巡检脚本随 API release 归档到 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs`，只读检查：
 
-- `genarrative-api.service`、`genarrative-external-generation-controller.service`、`spacetimedb.service`、`nginx.service` 是否 active。
+- 默认 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx`，检查 `genarrative-api.service`、`genarrative-external-generation-controller.service`、`spacetimedb.service`、`nginx.service` 是否 active；Pingora 直连切换后改为 `pingora-direct`，检查 `genarrative-api.service`、`genarrative-external-generation-controller.service`、`spacetimedb.service`、`genarrative-pingora-gateway.service`，不再要求 `nginx.service` active。
 - 至少一个 `genarrative-external-generation-worker@*.service` 实例是否 active；如果 controller 存活但 worker 全部退出，巡检直接返回 `CRITICAL`，避免外部生成队列长期无人消费。
 - API 直连 `/healthz`、`/readyz`。
 - SpacetimeDB 直连 `/v1/ping`。
-- 默认直连 API 端口检查 `/api/creation-entry/config`、`/api/runtime/puzzle/gallery`、`/api/runtime/custom-world-gallery`；如需走 Nginx / 公网域名，在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://<域名>`。
-- 最近 15 分钟 `genarrative-api.service`、`genarrative-external-generation-controller.service`、`genarrative-external-generation-worker@*.service`、`spacetimedb.service`、`nginx.service` 的 `err..alert` 日志。
+- 默认通过本机公网网关入口检查 `/api/creation-entry/config`、`/api/runtime/puzzle/gallery`、`/api/runtime/custom-world-gallery`；如需走正式域名，在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://<域名>`。若在目标机本机打 `https://127.0.0.1` 或 `http://127.0.0.1`，同时配置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`，确保 public probe 命中正确 vhost / Host 语义。
+- Pingora 影子网关只在同时配置 `GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL` 与 `GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN` 时纳入巡检；脚本会访问 `GET /__genarrative_pingora/healthz` 并校验返回 `gateway=pingora-shadow`，未配置时不影响现有生产巡检。
+- 最近 15 分钟对应 gateway mode 下 `genarrative-api.service`、`genarrative-external-generation-controller.service`、`genarrative-external-generation-worker@*.service`、`spacetimedb.service` 和 `nginx.service` 或 `genarrative-pingora-gateway.service` 的 `err..alert` 日志。
+
+巡检脚本的显式 `--timeout-ms`、`--slow-ms`、`GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS` 和 `GENARRATIVE_HEALTH_PATROL_SLOW_MS` 必须是正整数，非法值会直接失败，不静默回退默认 `5000ms` / `3000ms`；生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 也必须是明确布尔值，非法值会直接失败。health patrol env 复核脚本的 `--env-file`，以及 env 切换脚本的 `--env-file` / `--check-script` 都必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。env 切换 `--apply` 还必须直接指向真实普通 env 文件，不能传符号链接。切换窗口调整超时、慢请求阈值、巡检模式开关或 env 路径时，先确认 env 与命令行参数格式正确，再把失败当作配置错误处理。
+
+Pingora 网关行为变更后应先在本机运行 `npm run check:pingora-gateway-smoke`。该脚本不依赖完整 dev stack，会用临时 mock 上游覆盖静态路由、HTML / 普通静态资源 `no-cache`、Vite 指纹静态资源 immutable 缓存、gzip 最小长度、小响应不压缩、图片资源不压缩、大响应压缩、TLS 直连、HTTP 到 HTTPS 重定向、API 代理头、body limit、429 接流保护、上游断连 / 超时 JSON 错误、维护模式和 SpacetimeDB WebSocket Upgrade，并复用 `check-pingora-direct-live.mjs` 对临时 HTTPS / HTTP redirect / WSS subscribe 入口做 live smoke。API 代理头必须保持 Nginx 口径：透传 `Host`，写入 `X-Forwarded-Host`、配置化的 `X-Forwarded-Proto`、TCP 对端 IP 作为 `X-Real-IP`，并把 TCP 对端 IP 追加到 `X-Forwarded-For`；`TRUST_X_FORWARDED_FOR` 只用于接流保护 client key。gzip 默认由 `GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED=true` 开启，`GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5` 与 `GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024` 对齐当前 Nginx `gzip_comp_level 5` / `gzip_min_length 1024`；`GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip` 是当前唯一允许的压缩算法白名单。Pingora 静态缓存头默认由 `GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL=no-cache`、`GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL=public, max-age=31536000, immutable` 和 `GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL=no-cache` 分别控制入口 HTML、指纹资源和其它静态资源。Pingora 正式化口径固定为 gzip-only，Brotli 仍由 Nginx / 前置代理能力探测承担，直连 Pingora 不以 Brotli parity 作为切换门禁。Pingora 上游超时显式配置在 peer 上：连接默认 `3000ms`，无显式长超时代理路由默认读 `60s`，通用 `/api`、公开列表 / 详情和 SpacetimeDB subscribe 默认读 `3600s`，写上游默认 `3600s`；读 / 写 / 连接超时统一返回 JSON `504 GATEWAY_UPSTREAM_TIMEOUT`。当前 Pingora 接流保护默认只覆盖单进程单实例；`GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 时，必须先落地共享限流 / 共享并发保护层并设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则网关启动和目标机 direct preflight 都会失败。若关闭网关保护后横向多实例运行，全局接流保护必须由前置 Nginx / LB 承担。
+
+直连 HTTPS 入口只在显式设置 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、证书链和私钥文件后启用，证书链和私钥必须允许 `genarrative` 用户读取；HTTP 重定向入口只在已配置 TLS 入口后启用，且 ACME challenge 仍从 `ACME_ROOT` 静态读取。默认 systemd service 仍以非 root `genarrative` 用户运行且不具备低端口绑定能力；Server-Provision 只把直连 drop-in 模板安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 作为参考和手动覆盖来源，正式切换默认使用 current release 内的 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`。需要绑定 `80/443` 时必须先释放 Nginx 或其它进程占用，再通过 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log` 安装到 `/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf`、`systemctl daemon-reload` 并重启 Pingora；脚本会先拒绝带换行或 NUL 的 service、路径、URL、Host、probe token、access log、数据库名、tail 行数和 timeout 参数，并拒绝脚本、env、drop-in、release root、access log 等路径参数指向文件系统根目录，再执行 current release 自审，确认发布包自包含、`pingora-gateway` 可执行且 systemd `ExecStart` 指向随包网关，失败时不会安装 drop-in；随后确认当前执行用户可读 TLS 文件，确认 service 模板和 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含本次 preflight env，再按 `genarrative-pingora-gateway.service` 的 `User=` 验证真实服务用户可读证书链和私钥，并从 service `ExecStart=` 确认 current release 的 `pingora-gateway` 存在且可执行，重启后用 `systemctl cat` 核验低端口 capability drop-in 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已进入 systemd 最终配置，用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，用 `systemctl is-active` 确认 Pingora active，并以 JSON 模式执行 direct live smoke，强制覆盖 HTTPS / HTTP redirect / ACME / WSS 101 和 Pingora access log request_id 落盘；启用脚本会解析 `direct-access-log` 结构化结果，要求 `matchedCount == checked` 且 `missingCount=0`、`mismatchCount=0`，缺少该结构化结果时即使 direct live 子进程退出 0 也会让启用失败。只有需要临时改用 `/etc/genarrative/pingora/` 参考模板时，才显式传 `--template-path` 或设置 `GENARRATIVE_PINGORA_DIRECT_TEMPLATE_PATH`；切换窗口覆盖 `--preflight-script`、`--direct-live-script`、`--current-release-audit-script`、`--template-path`、`--service-unit-path`、`--dropin-path` 或 env 文件路径时必须使用绝对路径，且不能用 `/` 占位，`--apply` 会在安装 drop-in 前确认 current release 自审、direct preflight 和 direct live smoke 脚本都存在。
+
+目标机验证直连入口时先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再运行 `npm run check:pingora-direct-live`；正式切换聚合门禁追加 `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable`；`--require-direct` 会强制要求 direct HTTPS base URL、direct HTTP base URL、正式域名 Host/SNI、redirect Location host、Pingora access log 文件、health patrol env 文件、direct preflight env 文件、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户证书可读检查、服务用户证书可读检查、service 二进制可执行检查和显式 SpacetimeDB 数据库名同时存在，并默认要求 WSS subscribe 返回 101，避免漏掉 HTTP 301 / ACME challenge、正式证书域名、HTTP redirect Location host、Pingora access log request_id 落盘、SpacetimeDB 长连接、低端口 capability、TLS 文件权限验证、systemd 实际 env 漂移、systemd 服务用户权限、current release 二进制可执行性或误用默认数据库名。`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、direct live 单脚本的 `--pingora-access-log` 和 direct preflight 单脚本的 `--env-file` 都必须是绝对路径，且不能是文件系统根目录；direct preflight 的 `--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值还不能包含换行或 NUL，执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前会复核子命令参数，避免污染参数进入目标机预检命令；direct live 的 URL、Host、probe token、额外 path、数据库名、access log 路径、timeout 和布尔 env 同样不能包含换行或 NUL，脚本会在发起 HTTPS / HTTP / WSS 请求前失败，避免污染请求头、URL、日志对账或 JSON 证据。若 env 中 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true`，preflight 会要求同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true`；当 TLS / HTTP redirect 监听公网地址时还会直接失败，因为公网直连 Pingora 不能信任客户端可伪造的 `X-Forwarded-For`。若 env 中 `GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1`，preflight 会要求同时设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，避免把进程内保护误当成跨实例全局保护。生产证书必须可被系统信任，`--direct-insecure-tls` 只允许本机自签证书 smoke 使用；`--direct-skip-wss` 只允许单独 direct live 临时排障，release readiness `--require-direct` 会直接拒绝。生成 `--dry-run-cutover` 正式切换 runbook 时，`--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同；同时必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，避免回退计划把现场巡检入口覆盖成仓库默认值。runbook 的 Host 与回退巡检入口确认步骤会直接展示回退后要恢复的 public base URL / Host，并默认展示来自切换前真实 Nginx 入口的 `rollback-nginx-smoke-expect-body`，当班人员需要在启用前确认它们就是切换前记录值。多域名或 canonical redirect 切换需要单独设计，不混入第一版 runbook。runbook 可选追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，把回退后 Pingora shadow 高端口探针复核写入 rollback dry-run / apply，JSON 输出会隐藏 token 原文。
+
+正式 runbook 的状态快照证据包必须显式传 `--expected-pingora-env-mode`：`post-enable` 使用 `direct`，证明 active `/etc/genarrative/pingora-gateway.env` 已是直连姿态；`post-rollback` 使用 `shadow`，证明回退后的 active env 已恢复 shadow 姿态。回退前的 `pingora-gateway-env-shadow-switch.mjs --apply` 必须同时清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` 和 `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`，避免留下“有证书路径但无 TLS listen”的半直连 env。
+
+直连验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`，或在仓库工作区执行 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`；回退脚本会先拒绝带换行或 NUL 的 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override，并拒绝 service unit、drop-in、health patrol env、复核脚本、路径形式二进制 override 指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件，以及已存在但不是普通文件的 drop-in 目标，通过后才运行 `nginx -t`、移除 drop-in、重启 Pingora，并用 `systemctl cat` 核验低端口 capability 已从 systemd 最终配置中移除，用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，最后 reload Nginx、确认 Nginx service 仍为 `active`，并用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时还会要求响应体包含该片段，避免 HTTP 200 命中错误入口；该 URL 与 body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`。`--nginx-smoke-url` 必须是 `http(s)` URL；本机打 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 还必须显式传 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免命中默认 vhost。覆盖 `--nginx-binary` 或 `--curl-binary` 时可以传裸命令名；如果值包含路径分隔符，则必须使用绝对路径，避免回退窗口受 cwd 影响。若 health patrol env 已在回退命令前切回 Nginx，可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env`，让回退脚本在 Nginx smoke 后复核 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST` 为空；若要证明回退后 Pingora 仍作为 shadow 高端口服务存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`。否则回退后必须单独运行 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs --env-file /etc/genarrative/health-patrol.env --expected-gateway-mode nginx --require-empty-public-host`。启用 / 回退脚本默认 dry-run，必须显式传 `--apply` 才修改 systemd；启用脚本 `--apply` 必须先通过 current release 自审，并同时传 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 和 `--direct-spacetime-database`，回退脚本 `--apply` 必须同时传 `--reload-nginx` 和 `--nginx-smoke-url`；当 smoke URL 是本机地址时还必须传 `--nginx-smoke-host`。本机 `npm run check:pingora-direct-enable` 和 `npm run check:pingora-direct-rollback` 会用临时文件验证 dry-run 不修改 drop-in、current release 自审失败时启用脚本不会安装 drop-in、direct preflight / direct live smoke 脚本缺失时安装前失败、direct live 退出 0 但缺少 `direct-access-log` JSON 证据时启用失败、回退脚本在 drop-in 路径安全异常时不会继续执行 `nginx -t` 或删除真实目标、会打印对应命令、展示 release layout 默认读取随包 `deploy/systemd` direct-entry 模板、systemd 最终配置核验、ExecStart 指向核验、Pingora active 核验、direct live smoke、Nginx 配置语法检查、Nginx reload 后状态核验、Nginx smoke 及响应体片段核验、可选 health patrol env 复核、可选 Pingora shadow probe 复核，并拒绝相对路径、文件系统根目录路径、非法 smoke URL、路径形式的二进制 override 和控制字符参数。
+
+`npm run check:pingora-current-release-audit` 会烟测 current release 自审脚本，`npm run check:pingora-cutover-status-snapshot` 会烟测随包状态快照脚本，`npm run check:pingora-cutover-evidence-bundle` 会烟测证据包归档脚本，`npm run check:pingora-cutover-command-evidence` 会烟测 apply 命令 stdout / stderr / 退出码归档脚本，`npm run check:pingora-cutover-evidence-verify` 会烟测证据 manifest 只读验真脚本，`npm run check:pingora-cutover-evidence-audit` 会烟测证据根目录三阶段总审计脚本；正式切换窗口先用 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show` 只读确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 与当前文件匹配、`release-manifest.api-server.json` 已登记 `pingora-gateway`、`pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release，再使用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 在 `pre-cutover`、`post-enable`、`post-rollback` 三个阶段生成时间戳证据目录，保存 `manifest.json`、`snapshot.json`、`snapshot.stdout.txt`、`snapshot.stderr.txt` 和 `snapshot-command.json`；证据包 `manifest.files` 会给已生成的 snapshot / stdout / stderr / command / parse-error / direct-live 文件统一记录 `path`、`sizeBytes` 和 `sha256`，便于窗口后复核归档文件未漂移。每个阶段证据目录生成、复制或归档后，都要用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <本阶段bundleDir>` 做只读验真；该 verifier 把 `manifest.files` 视为闭集，除已登记文件和 `manifest.json` 外，目录中混入任何未登记普通文件、目录或符号链接都会默认失败，`--allow-extra-files` 只允许人工排障时显式放行，正式切换归档不使用。enable / rollback apply 命令证据生成后也要立即用同一个 verifier 做只读验真，把上一步 stdout 中的 `bundleDir` 分别填入 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>`，确认 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 与 manifest 元数据一致后，再继续 health patrol 切换或回退后复核。三阶段证据、enable / rollback apply 命令证据和三条 env 变更命令证据都完成并即时验真后，再用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000` 自动定位每个阶段最新证据目录和五条真实切换命令证据目录，并复用 verifier 的 `--require-summary-ok` 严格模式输出总审计 JSON。证据根目录总审计默认只接受带 `manifest.json` 的证据目录，根目录夹带普通文件、无 manifest 子目录或符号链接都会失败；`--allow-extra-root-entries` 只允许人工排障显式放行，正式切换归档不使用。阶段证据必须是不带 `manifest.commandName` 的状态快照证据包，命令证据不能冒充同名 phase 的阶段证据。验真与总审计脚本只读取 manifest 和证据文件，拒绝路径逃逸、未登记额外条目、根目录额外条目、缺文件、大小漂移、sha256 漂移、符号链接证据目录、非目录证据路径、缺阶段证据、缺命令证据、阶段 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`，以及标准八段证据的 `manifest.generatedAt` 顺序不满足 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback` 或八段跨度超过默认 24 小时、要求 `--require-cutover-run-id` 时任一证据缺少同一 `manifest.cutoverRunId`，不修改 `/etc`、systemd、Nginx、Pingora 或证据文件；runbook 会生成或接受 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、五条真实切换命令证据和最终总审计；确需跨更长维护窗口时，生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让总审计 JSON 记录本次 `timeline.maxSpanMs` 和 `timeline.spanMs`。runbook 的 direct enable apply / rollback apply 还会通过 `/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs` 包装真实脚本执行，额外保存 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 和 `manifest.json`，失败时同样保留证据并返回真实退出码，命令证据 `manifest.files` 也会记录这三份命令证据文件的 `path`、`sizeBytes` 和 `sha256` 供归档后复核。若状态快照 stdout 无法解析为 JSON，证据包会改写 `snapshot-parse-error.txt` 并在 `manifest.files.snapshotParseError` 与最终 stdout 中给出路径；启用后 direct live stdout 无法解析时，同理写入 `direct-live-parse-error.txt` 并在 `manifest.files.directLiveParseError` 与最终 stdout 中给出路径，避免解析失败原因只散落在终端输出里。底层状态快照收录 `summary`、`healthPatrolEnv`、`pingoraEnv`、`releaseArtifacts`、`systemd` 和 `checks`；其中 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile` 必须为 `true`，证明 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 精确包含本次 `--pingora-env-file`，避免证据包读取一份 env 而真实服务读取另一份 env。直连 runbook 的三个证据包阶段都会向状态快照透传 `--require-pingora-gateway`，因此 `checks.current-release-audit.details` 会同步保存 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果。自审脚本和快照脚本只读采集状态，证据包脚本只写 `--output-root` 下的新目录；命令证据脚本只负责执行 `--` 后面的真实命令并归档输出，不自行修改 `/etc`、systemd、Nginx 或 Pingora；自审、快照和证据包传入的 `--release-root` 都必须是绝对路径且不能是文件系统根目录，状态快照的 `--health-patrol-env-file` / `--pingora-env-file` 以及证据包所有显式路径参数也不能是文件系统根目录，`--output-root` 及其已存在上级路径不能是符号链接，且已存在的 `--output-root` 必须是目录；路径异常时会在执行状态快照前失败，不写入软链真实目标、不覆盖已有文件、不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora；正式 runbook 传 `--run-health-patrol --fail-on-critical`，任何 `CRITICAL` 都应阻断继续切换或回退确认。
+
+证据包还会把 Pingora env 的 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode` 和 `shadowReady` 提升到 `manifest.summary.pingoraEnvShadow`；正式总审计必须追加 `--require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-phase-pingora-env-shadow post-rollback`，其中 `post-rollback` 必须证明 `listen=127.0.0.1:18081`、`mode=shadow`、`shadowReady=true`，且低端口 TLS / HTTP redirect 监听和证书路径均为空。
+
+证据 verifier / 总审计的 `--manifest`、`--bundle-dir`、`--evidence-root`、`--verify-script` 和 manifest 登记文件名都不能包含换行或 NUL 字符；遇到此类失败应修正 runbook 参数或重新生成证据，不要把被污染的路径留给下游 JSON 归档兜底。
+
+current release 自审的 `--release-root` 和 `--systemd-service` 不能包含换行或 NUL 字符；启用 `--systemd-show` 时，脚本还会在执行 `systemctl show` 前复核子命令可执行文件和所有参数不含换行或 NUL，避免只读自审命令被污染参数带偏。
+
+证据根目录总审计的“最新证据”只以 `manifest.generatedAt` 为准；任何阶段或命令候选缺少合法 `manifest.generatedAt` 都会作为根目录 `CRITICAL` 失败，不能用目录 mtime 兜底。同一阶段或同一命令如果出现多个候选共享最新 `manifest.generatedAt`，总审计会以 `AMBIGUOUS_LATEST` 失败并列出重复目录，不能按目录名排序打平；应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。所有证据 manifest 必须是 `schemaVersion=1`，命令证据中的 `manifest.command` 与独立 `command-record.json` 也必须是 `schemaVersion=1` 且字段一致；`manifest.generatedAt`、命令 `startedAt` 和 `finishedAt` 必须使用 `new Date().toISOString()` 产出的 UTC 毫秒格式 `YYYY-MM-DDTHH:mm:ss.sssZ`，不接受省略毫秒、本地时区或其它可被 `Date.parse` 宽松解析的字符串；命令证据的顶层 `manifest.commandName` 和内嵌 `manifest.command.name` 只要存在就必须各自是安全非空命令名，且两者同时存在时必须一致，否则按坏 manifest 处理；旧格式或手工 JSON 即使 hash 正确，也不能进入正式证据链。标准八段时间线在阶段和命令都被要求时，还会显式检查八段条目的审计状态都是 `OK`，任一阶段或命令为 `MANIFEST_FAILED` / `VERIFY_FAILED` 等非 OK 状态都会写入 timeline 诊断。这样证据目录被复制、归档或恢复后，选择最新证据和标准八段时间线证明仍只依赖 manifest 中可验真的事实。
+
+标准八段时间线只要任一阶段或命令证据声明了 `manifest.cutoverRunId`，八段就必须全部声明同一个值；缺字段或混入其它批次都会让总审计失败。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。正式 runbook 仍必须显式传 `--require-cutover-run-id <本次cutoverRunId>`，避免人工临时审计遗漏参数。
+
+总审计 JSON 的 `timeline.failedCount` 会按标准八段时间线的具体失败项累计，`timeline.failureBreakdown` 会区分 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded`。切换窗口排障时不要只看顶层 `ok=false`，应先按 breakdown 定位是证据状态未达标、时间字段缺失、批次混入、顺序倒挂还是维护窗口跨度超限。
+
+正式 runbook 的每个即时 verifier 步骤，以及三条 env 变更命令证据即时验真步骤，都必须追加 `--require-summary-ok`：三阶段状态证据、enable / rollback apply 命令证据和三条 env 变更命令证据在刚生成后就要同时通过 `manifest.files` 完整性校验和 `manifest.summary.status=OK` 校验；缺少 `summary`、状态为 `CRITICAL` 或文件 hash 漂移都必须立即停住。最终证据根目录总审计仍负责跨目录聚合、命令身份、`--apply` 参数、时间线和 `cutoverRunId` 的二次确认，不能用来替代即时验真；总审计内部再次复用 verifier 时也必须启用 `--require-summary-ok`。
+
+正式 cutover runbook 不允许携带 `--warn-only`、`--allow-extra-files` 或 `--allow-extra-root-entries`。这些参数只用于 runbook 之外的人工排障命令；一旦需要它们，说明正式证据链还不干净，应先修现场状态、归档方式或重新生成证据，再回到无放行参数的 runbook。
+
+最终证据根目录总审计必须在 `--require-command` 之外追加五条 `--require-command-executable` 和七条 `--require-command-arg` 要求，覆盖 enable apply、health patrol direct env switch、Pingora gateway shadow env switch、health patrol nginx env switch 和 rollback apply；其中 include `enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并要求 `--apply`、`pingora-direct` 与 `nginx` 等关键参数，复核命令证据里的 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable 都是 current release 随包脚本，并要求 `manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的 executable 段必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符；总审计 JSON 会记录 `requiredCommandExecutables`，便于复盘本次绑定的真实 current release 随包脚本。总审计还会要求 `manifest.commandName` 与 `manifest.command.name` 一致，并要求 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / commandName / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段一致；stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作。命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`。这些参数会隐式要求对应命令证据存在；旧证据缺少 `schemaVersion` 或 `expectedExecutable`、缺少必需 `--apply` 参数、人工同名证据的 executable 漂移、manifest 与 command-record 语义漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染、命令时间线漂移或同一命令绑定多个不同脚本路径都会失败。
+
+命令证据的 `manifest.expectedExecutable` 和 `manifest.command.expectedExecutable` 只要出现，就必须是安全绝对路径；空字符串、相对路径、文件系统根目录或包含换行 / NUL 的值都会让总审计失败，避免坏字段被当作缺省值跳过。生成命令证据时，`pingora-cutover-command-evidence.mjs --expected-executable` 也会在执行真实命令前拒绝相对路径、文件系统根目录和带换行 / NUL 的路径。
+
+只要命令证据声明了 `expectedExecutable`，`manifest.command.executable` 和独立 `command-record.json.executable` 就必须同时是同一个绝对路径；即使未显式传 `--require-command-executable`，真实 `executable` 与 `expectedExecutable` 漂移也必须失败。
+
+正式命令证据不能只依赖 `command` 字符串复盘真实命令；`manifest.command.executable` 和 `command-record.json.executable` 都是必填安全绝对路径，缺失任一字段都会让总审计失败。
+
+生成命令证据时，`pingora-cutover-command-evidence.mjs` 的 `--output-root` 必须是安全绝对路径，不能是文件系统根目录、符号链接或包含换行 / NUL 字符；`-- <command>` 也必须使用绝对路径，不能依赖 PATH 裸命令名；真实命令不能是文件系统根目录，真实命令和每个真实命令参数都不能包含换行或 NUL 字符。这保证生成端写出的结构化 `executable` / `args[]` 天然符合最终总审计的必填安全证据要求。
+
+current release 自审、状态快照、证据包、direct preflight、生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，拼写错误会直接失败，避免 `REQUIRE_GATEWAY`、`RUN_HEALTH_PATROL`、`REQUIRE_PINGORA_GATEWAY`、`FAIL_ON_CRITICAL`、`TRUST_X_FORWARDED_FOR` 或巡检切换开关被悄悄当成 false。
+
+正式直连 runbook 的启用前 release readiness 基础门禁和启用后 `--require-direct` 复核，都必须调用 current release 随包的 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs`。生产 API release、Jenkins API Build 归档、Jenkins API Deploy 复制清单和 `production-api-deploy.sh` 都必须携带该聚合门禁脚本；缺失时部署应 fail-fast 并保持维护模式，切换窗口不能回退到源码 checkout 或 Jenkins workspace 的相对路径脚本。
+
+current release 随包执行的 release readiness 必须追加 `--release-runtime-only`，只运行包内可自包含的 current release 自审、live canary、真实 access log 对账、direct preflight、health patrol env 复核和 direct live smoke；不要在 `/opt/genarrative/current` 上运行默认源码全量门禁。默认不带 `--release-runtime-only` 的聚合门禁仍属于本机 / CI / 构建环境使用，负责覆盖 Cargo、npm、Docker、Nginx 静态 / 真机校验和发布包构建烟测。
+
+Pingora direct 切换门禁按阶段拆分：启用前 preflight、`--dry-run-cutover` 和 `pingora-direct-enable.sh --apply` 必须带 `--direct-preflight-check-ports-free` / `--preflight-check-ports-free`，证明 Nginx、Gitea 等所有占用 `80/443` 的进程已释放；启用后 `--require-direct --release-runtime-only` 复核不再要求端口空闲，因为此时 `80/443` 应由 Pingora 占用。回退 runbook 必须显式提供来自切换前真实 Nginx 响应的 `--rollback-nginx-smoke-url` 与 `--rollback-nginx-smoke-expect-body`，例如 dev 首页 `https://dev.genarrative.world/` 和 `<!doctype html>`；不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`。如果切换窗口把 `/etc/genarrative/pingora-gateway.env` 提升为 direct 低端口配置，rollback apply 前必须用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 预置 Pingora shadow env，确认 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081`，并清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`，再重启 Pingora。
+
+涉及 Nginx 模板、Pingora 路由、限流分组或路由文档时，必须同步更新 `deploy/pingora/nginx-route-parity.matrix.json`，并运行 `npm run check:pingora-route-parity`；Rust 侧 `cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix` 会读取同一份矩阵验证 `classify_path` 的路由结果、body limit 和接流保护分组。
+
+Pingora canary 入口默认由 Server-Provision 安装但不接入主站配置。`deploy/nginx/snippets/genarrative-pingora-canary.conf` 是前缀 canary，人工 include 后用 `/__genarrative_pingora_canary/` rewrite 到 Pingora shadow；`deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 是前缀 canary 之后、direct 直连之前的真实路径 canary，只能在 Nginx `http` 上下文 include，默认监听 `127.0.0.1:18083` 并写独立 `/var/log/nginx/genarrative-pingora-realpath-canary.access.log`，不要 include 到生产 `443` server 内覆盖正式 location。启用前必须运行 `npm run check:nginx-pingora-canary`；目标 agent 有 Nginx 时运行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`，强制把前缀 location 片段和真实路径 server 片段一起执行 `nginx -t`。本机或 CI 可用 `npm run check:pingora-canary-docker` 启动 Docker Nginx、真实 Pingora 和 mock 上游复现两条 Nginx -> Pingora handoff，并复用 `scripts/check-pingora-canary-access-log-parity.mjs` 按 `request_id` 对账。需要证明 Docker Nginx -> Pingora -> 真实本地服务时，先启动真实 api-server 与 SpacetimeDB，再运行 `node scripts/check-pingora-canary-docker.mjs --require-docker --real-upstreams --api-upstream 127.0.0.1:<api-port> --spacetime-upstream 127.0.0.1:<spacetime-port> --web-root dist`；该模式不会启动内置 mock 上游，会先检查真实 `/healthz` 和 `/v1/ping`，随后复用同一组 live smoke 与 access log 对账。真实 SpacetimeDB 对 `GET /v1/identity` 返回 `405 Method Not Allowed` 属于可接受语义，canary live 只把它作为路径路由代表，不要求该 GET 创建 identity。前缀 canary reload 后运行 `GENARRATIVE_PINGORA_CANARY_BASE_URL=http://127.0.0.1 GENARRATIVE_PINGORA_CANARY_HOST=<域名> npm run check:pingora-canary-live`；真实路径 canary 启停统一使用 current release 随包脚本：`/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083` 写入 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf` 并执行 `nginx -t`、reload 和 realpath live smoke，`/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply` 删除该配置并复核 Nginx；两者失败都会恢复操作前状态。真实路径 canary reload 后运行 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`，随后用 `node -- /opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_realpath_canary/healthz --path /api/creation-entry/config --path /v1/identity --path /assets/app.js` 对账；真实路径模式除 healthz 探针外要求 Nginx path 与 Pingora path 完全一致。canary live 的 base URL、prefix、Host、额外 path、`--timeout-ms` / `GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS` 不能包含换行或 NUL，脚本会在发起请求前失败；canary access log 对账脚本的日志路径、prefix、必需路径和 `--since-lines` / `GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES` 也不能包含换行或 NUL，日志行里解析出的 URI / path 含控制字符时必须失败；timeout 和 access log 对账的 `--since-lines` / 对应 env 必须是正整数，非法值直接失败，不静默回默认值。
+
+下方聚合门禁示例以前缀 canary 已启用为前提；如果现场只启用了真实路径 canary，源码 checkout / CI 与目标机 `--release-runtime-only` 都不要传 `--require-live`，改用 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。只有前缀 canary 和真实路径 canary 都启用时，才同时传两组 live 参数。
+
+Pingora 正式切换前必须额外运行聚合门禁：`node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。该门禁串起 Rust 单测、mock smoke、路由 parity、Nginx snippet 校验、Docker Nginx handoff、canary access log 对账烟测、直连入口静态预检、直连启用 / 回退 dry-run 行为检查、health patrol env 切换脚本烟测、current release 自审烟测、release readiness 计划自检、生产运维护栏、API release build 烟测、Pingora production release 真实构建烟测、API deploy release 烟测、目标机 live canary 和目标机真实 access log 对账；其中 `--require-live` 只能在目标 Nginx 已人工 include canary snippet 并 reload 后执行，并会强制要求 `--live-host`，避免只访问 `127.0.0.1` 命中 Nginx 默认 vhost。live smoke 成功后会立即读取 Nginx 与 Pingora access log 尾部记录，按 `request_id` 验证 `/__genarrative_pingora_canary/healthz` 和 `/__genarrative_pingora_canary/api/creation-entry/config` 已在两边落盘且 method/status/path 没有漂移。启用真实路径 canary 时追加 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，它会用独立 Nginx access log 对账真实 `/api`、`/v1` 与 `/assets` 路径。live canary、direct live 和 access log 对账的显式毫秒超时或尾部行数参数都必须是正整数，非法值应先修参数再重跑，不能把默认值兜底后的结果当成切换证据；direct live 与 release readiness 读取的直连布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，拼写错误会直接失败，避免 `REQUIRE_WSS_UPGRADE`、preflight 开关或 `SKIP_WSS` 被悄悄当成 false。若验证 Pingora 直连公网入口，还必须追加 direct preflight 参数检查目标机 env、systemd drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限和 service 二进制可执行性：`--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable`；该模式缺少 `--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log`、`--direct-preflight-systemd`、`--direct-preflight-check-cert-readable`、`--direct-preflight-check-service-env-file`、`--direct-preflight-check-service-user-cert-readable`、`--direct-preflight-check-service-binary-executable`、缺少 `--direct-health-patrol-env-file` 或缺少 `--direct-spacetime-database` 会直接失败，且会拒绝 `--direct-skip-wss`，并默认要求 WSS subscribe 返回 101，证明 HTTP redirect / ACME、正式域名 Host/SNI、redirect Location host、Pingora access log request_id + path/status 对账、health patrol direct 模式、systemd drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性与目标 SpacetimeDB 长连接都能从直连入口透传。`check-pingora-release-readiness.mjs --help` 中的正式直连和只生成 runbook 示例也必须显式带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，避免值班人员复制示例后被 `--require-direct` 自身拦住。普通本机提交前可先跑 `npm run check:pingora-release-readiness`，但该默认模式不能替代目标机切换窗口的强制门禁。直连切换前还应先运行 `npm run plan:pingora-direct-cutover -- --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --rollback-nginx-smoke-url https://<域名>/ --rollback-nginx-smoke-expect-body '<!doctype html>' --rollback-health-patrol-public-base-url <切换前Nginx巡检入口>` 生成只读 JSON runbook；若切换参数提供 `--direct-probe-token`，启用后复核会继续透传 direct probe token 检查内部探针，runbook JSON 只显示 `<redacted>`。runbook 会列出 Host 与回退巡检入口确认、current release 自包含自审、current release preflight、启用前基础门禁、direct enable dry-run、direct enable apply、用 `/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply` 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后 `--require-direct` 复核、rollback dry-run、回退前用同一脚本预置回 `nginx` 并恢复切换前 public base URL / Host、rollback apply、回退后 health patrol env Nginx 模式复核，供当班人员逐条审阅。direct enable / rollback `--apply` 都会拒绝符号链接形式的 systemd drop-in 目录或目标文件，并拒绝已存在但不是普通文件的目标，避免把低端口 capability 写入非预期位置，或在回退窗口误删 / 误判非预期 systemd 位置；health patrol env 切换脚本 `--apply` 会保留原文件权限和 owner/group，此时 `--env-file` 必须直接指向真实普通文件，不能是符号链接。如果现场 env 是链接，先确认真实目标路径后再传给脚本，避免替换链接本身或写入非预期目标。
+
+目标机在 `/opt/genarrative/current` 上执行上述启用前基础门禁或启用后 `--require-direct` 复核时，命令必须显式使用 `--release-runtime-only`。该模式会拒绝 `--require-docker`、`--pull-docker` 和 `--require-nginx`，这些源码 / 构建环境门禁应在 CI 或构建机的默认聚合门禁中完成。
+
+上述聚合门禁默认还会执行 `npm run check:pingora-cutover-status-snapshot`、`npm run check:pingora-cutover-evidence-bundle`、`npm run check:pingora-cutover-command-evidence`、`npm run check:pingora-cutover-evidence-verify` 和 `npm run check:pingora-cutover-evidence-audit`。正式直连 runbook 会额外列出 `切换前状态快照证据包`、`启用后状态快照证据包` 和 `回退后状态快照证据包`，每个证据包阶段后都会列出对应的 `证据 manifest 只读验真` 步骤；`Pingora direct enable apply` 与 `Pingora direct rollback apply` 后也会分别列出 `启用命令证据 manifest 只读验真` 和 `回退命令证据 manifest 只读验真`，先用随包 verifier 复核命令证据 manifest，再进入 health patrol 切换或回退后 env 复核；最后在三阶段与 enable / rollback apply 命令证据和三条 env 变更命令证据都完成并即时验真后列出 `切换证据根目录三阶段总审计`。这些步骤都从 `/opt/genarrative/current` 读取随包脚本和支撑文件，分别校验 Nginx 基线、Pingora direct 接流状态、回退后的 Nginx 状态、真实切换命令 stdout / stderr / 退出码证据和证据根目录阶段完整性，并通过 `--require-pingora-gateway --fail-on-critical` 防止把发布物 checksum / manifest 漂移、env 漂移、release 缺文件、systemd capability 残留、systemd 实际读取的 Pingora env 与快照 env 不一致或生产巡检失败当作可忽略信息。启用后证据包还会通过 `--run-direct-live` 归档 `direct-live.json`、stdout / stderr、命令记录和 Pingora access log `request_id` 反查结果，确保 direct live 不是只停留在终端输出；`direct-live.json` 中的 `direct-access-log` 检查必须保留扫描行数、匹配数量、缺失明细以及 path/status 漂移明细，便于事后不用翻 stderr 就能定位具体请求。证据包还会把 `directLiveAccessLog` 摘要写入 `manifest.summary`，缺少 `direct-access-log` 结构化结果会直接标记 `CRITICAL`。若 snapshot 或 direct live stdout 解析失败，证据包必须同时归档对应 `*-parse-error.txt` 并在 manifest 中索引。证据链脚本的 timeout 必须是正整数，布尔 env 必须是明确布尔值，非法值应先修配置再重跑，不能把静默 false 当成切换证据；状态快照脚本单独执行时会拒绝带换行或 NUL 字符的 release/env 路径，并在执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前复核子命令参数；证据包脚本在执行状态快照或 direct live 子命令前必须先拒绝任一带换行或 NUL 字符的子命令参数，且 `--run-direct-live` 的 direct URL、Host、probe token、数据库名、Pingora access log 路径和 tail 行数会在配置层先拒绝换行或 NUL，`--direct-pingora-access-log` 还必须是绝对路径且不能是文件系统根目录，避免污染后的结构化 `args[]` 进入证据链；命令证据脚本的 `--phase` / `--command-name` 只允许 ASCII 安全字符，`--output-root` 必须是绝对路径且不能是符号链接或文件系统根目录，`--` 后的真实命令也必须是绝对路径、不能是文件系统根目录、不能包含换行或 NUL 字符；证据根目录总审计的 `--require-command <phase>:<commandName>` 同样只接受 ASCII 安全阶段名和命令名，缺失 `enable-apply:pingora-direct-enable-apply` 或 `rollback-apply:pingora-direct-rollback-apply` 任一命令证据都必须失败。
+
+命令证据脚本还支持 `--expected-executable <绝对路径>` 和 `--require-arg <参数>`，正式 runbook 的 enable / rollback apply 会分别绑定到 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并在执行前要求真实命令参数包含 `--apply`。如果 `--` 后真实命令与预期脚本不一致、缺少必需 `--apply` 参数，或任一真实命令参数包含换行 / NUL 字符，脚本会在创建正式命令证据前失败，避免只靠 `commandName` 把错误命令伪装成正式切换证据。
+
+Pingora shadow 的 access log 由 `GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE=/var/log/genarrative/pingora-gateway.access.log` 控制，Server-Provision 会创建 `/var/log/genarrative`、安装 `/etc/logrotate.d/genarrative-pingora-gateway`，并让 `genarrative-pingora-gateway.service` 的 systemd 沙箱允许写该目录。做 canary 对照时同时看 Nginx access log、Pingora access log 和 Pingora tracing 日志；`scripts/check-pingora-canary-access-log-parity.mjs` 会按 `request_id` 对照两边 access log，Nginx canary exact `/healthz` 映射到 Pingora shadow `/__genarrative_pingora/healthz`，其余前缀路径按 rewrite 后路径比对。canary 对账的 `--nginx-log-file` / `--pingora-log-file` 以及 release readiness live 模式的 `--live-nginx-access-log` / `--live-pingora-access-log` 必须是绝对路径且不能是文件系统根目录，避免把日志扫描误指向 `/`。
+
+Pingora 启动会拒绝明显不安全或不完整的配置：probe token 不能使用占位值或短 token，TLS 入口必须同时给出可读取的证书链和私钥文件，HTTP redirect 入口必须依附已配置的 TLS 入口且不能复用同一监听地址，redirect scheme 当前只允许 `https`，`GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL` 必须在 `0..=9`，`GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES` 必须大于 `0`，`GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS` 当前只允许 `gzip`，所有 `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_*TIMEOUT*` 必须大于 `0`，`GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true` 时必须同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true`，并确认前置 Nginx / LB 已清洗 `X-Forwarded-For`；接流保护配置中 `BURST>0` 时对应 `RATE_PER_SECOND` 不能为 `0`；开启网关保护时 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 必须同时设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则多实例会把进程内限流额度按实例数放大。
 
 巡检输出总状态 `OK / WARNING / CRITICAL`；只有 `CRITICAL` 默认让 systemd service 失败，`WARNING` 只写日志和状态文件，避免历史日志噪声把 timer 长期打成失败。最近一次结果写入 `/var/lib/genarrative/health-patrol/status.json`。手动执行：
 
@@ -292,7 +359,11 @@ cat /var/lib/genarrative/health-patrol/status.json
 
 `Genarrative-Web-Build` 会把 `build/<version>/web.tar.gz`、`web.tar.gz.sha256`、`release-manifest.json` 和 `scripts/deploy/production-web-deploy.sh` 直接归档为 Jenkins 构建产物；`Genarrative-Web-Deploy` 只通过 `copyArtifacts` 从指定上游构建复制这些产物和部署脚本，不再在目标机器 checkout Git，再执行随构建归档的 `scripts/deploy/production-web-deploy.sh`。Web 发布不再读取构建机本地缓存目录，也不再通过 release agent `rsync` 回构建机拉取大包；如果 deploy 找不到 `web.tar.gz`，应先检查上游 Web Build 是否按同一 `BUILD_VERSION` 成功归档产物。
 
-`Genarrative-Api-Build` 的 Jenkins 归档产物必须包含 `build/<version>/api-server`、`api-server.sha256`、`release-manifest.json`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`scripts/deploy/production-api-deploy.sh`、`scripts/deploy/maintenance-on.sh` 和 `scripts/deploy/maintenance-off.sh`。`deploy/systemd/genarrative-database-backup.service` 从 `/opt/genarrative/current/scripts/database-backup-to-oss.mjs` 执行冷备份，`deploy/systemd/genarrative-health-patrol.service` 从 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs` 执行巡检；`Genarrative-Api-Deploy` 会从上游 API 构建产物复制部署脚本、备份脚本和巡检脚本，不再在目标机器 checkout Git。如果 API 发布后 current release 中缺少这些脚本，应先检查 `Genarrative-Api-Build` 的 `archiveArtifacts` 和 `Genarrative-Api-Deploy` 的 `copyArtifacts` 过滤器是否仍包含 `build/<version>/scripts/database-backup-to-oss.mjs` 与 `build/<version>/scripts/ops/production-health-patrol.mjs`，不要只在部署机工作区手工补文件。
+`Genarrative-Api-Build` 的 Jenkins 归档产物必须包含 `build/<version>/api-server`、`api-server.sha256`、`release-manifest.json`、`build/<version>/scripts/deploy/production-api-deploy.sh`、`build/<version>/scripts/deploy/maintenance-on.sh`、`build/<version>/scripts/deploy/maintenance-off.sh`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`scripts/ops/pingora-current-release-audit.mjs`、`scripts/ops/pingora-cutover-status-snapshot.mjs`、`scripts/ops/pingora-cutover-evidence-bundle.mjs`、`scripts/ops/pingora-cutover-command-evidence.mjs`、`scripts/ops/pingora-cutover-evidence-verify.mjs`、`scripts/ops/pingora-cutover-evidence-audit.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/check-pingora-canary-access-log-parity.mjs`、`scripts/check-production-health-patrol-env.mjs`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`deploy/systemd/**`、`deploy/env/**` 和 `deploy/pingora/**`。`deploy/systemd/genarrative-database-backup.service` 从 `/opt/genarrative/current/scripts/database-backup-to-oss.mjs` 执行冷备份，`deploy/systemd/genarrative-health-patrol.service` 从 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs` 执行巡检；`Genarrative-Api-Deploy` 会从上游 API 构建产物复制并执行 `build/<version>/scripts/deploy/production-api-deploy.sh`，同目录的 `maintenance-on.sh` / `maintenance-off.sh` 也必须来自同一 build 产物；部署脚本会先写入 `${RELEASE_ROOT}/.${VERSION}.staging.$$`，把 `release-manifest.json` 校验后复制为 current release 的 `release-manifest.api-server.json`，并把备份脚本、巡检脚本、Pingora 直连启用 / 回退 / 预检 / live smoke / canary access log 对账 / health patrol env 复核 / current release 自审 / 状态快照 / 证据包 / 命令证据 / 证据验真 / 证据根目录审计脚本，以及 `deploy/systemd`、`deploy/env`、`deploy/pingora` 支撑配置全部复制完成后，才用非合并语义提升为 `${RELEASE_ROOT}/${VERSION}` 并用固定替换语义切换 `current` 符号链接，不再在目标机器 checkout Git，也不再执行部署工作区根部脚本。Pingora 直连启用脚本必须能从 `/opt/genarrative/current` 独立执行 preflight 和 direct live smoke，并默认读取 current release 随包 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，不依赖 Jenkins 工作区、源码 checkout 或 `/etc` 参考模板；`plan:pingora-direct-cutover` 必须能用同一组参数生成 current release 切换 / 回退 runbook。`production-api-deploy.sh` 对 release manifest、备份脚本、巡检脚本、env 示例目录和 Pingora 直连依赖都执行 fail-fast，且 `--release-root`、`--current-link`、`--api-env-file` 必须是绝对路径，`--version` 必须以数字或字母开头并只能包含数字、字母、点、下划线和短横线，禁止 `.` / `..` 点目录；发布产物缺少 manifest、manifest 未登记 `api-server`、缺少脚本 / 配置目录、同版本 release 目录已存在、current 路径不是符号链接、提升前 release 目录竞态出现或 staging 构建中失败时会保留维护模式并停止部署；失败会清理 staging 目录且不会留下正式 release 目录，不再从部署机工作区兜底补文件，也不把旧同名 release 目录和新文件混合。如果 API 发布后 current release 中缺少这些脚本或目录，应先检查 `Genarrative-Api-Build` 的 `archiveArtifacts` 和 `Genarrative-Api-Deploy` 的 `copyArtifacts` 过滤器是否仍包含 `build/<version>/release-manifest.json`、`build/<version>/scripts/deploy/production-api-deploy.sh`、`build/<version>/scripts/deploy/maintenance-on.sh`、`build/<version>/scripts/deploy/maintenance-off.sh`、`build/<version>/scripts/database-backup-to-oss.mjs`、`build/<version>/scripts/ops/production-health-patrol.mjs`、`build/<version>/scripts/ops/pingora-current-release-audit.mjs`、`build/<version>/scripts/ops/pingora-cutover-status-snapshot.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-bundle.mjs`、`build/<version>/scripts/ops/pingora-cutover-command-evidence.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-verify.mjs`、`build/<version>/scripts/ops/pingora-cutover-evidence-audit.mjs`、`build/<version>/scripts/check-pingora-direct-preflight.mjs`、`build/<version>/scripts/check-pingora-direct-live.mjs`、`build/<version>/scripts/check-pingora-canary-access-log-parity.mjs`、`build/<version>/scripts/check-production-health-patrol-env.mjs`、`build/<version>/scripts/deploy/pingora-direct-enable.sh`、`build/<version>/scripts/deploy/pingora-direct-rollback.sh`、`build/<version>/deploy/systemd/**`、`build/<version>/deploy/env/**` 与 `build/<version>/deploy/pingora/**`，不要只在部署机工作区手工补文件。本机用 `npm run check:production-api-release` 通过临时 `CARGO_TARGET_DIR` 和假 `api-server` / `pingora-gateway` release binary 验证 `build-production-release.sh --component api-server --skip-api-build` 会把这些文件打进 API release，并验证显式 `--include-pingora-gateway --skip-pingora-gateway-build` 时发布包包含 `pingora-gateway`、`pingora-gateway.sha256` 和 manifest 登记；`npm run check:pingora-production-release-build` 则用假 `api-server` 和真实 `cargo build -p pingora-gateway --release --target x86_64-unknown-linux-gnu` 验证显式 include 路径能构出可执行网关二进制、checksum 和 manifest 登记；再用 `npm run check:production-api-deploy` 通过临时 release、fake `systemctl` / `curl` 验证从发布产物内执行 `production-api-deploy.sh` 会把这些文件复制到 current release，并验证缺少 release manifest、manifest 未登记 `api-server`、缺少数据库备份脚本、健康巡检脚本、健康巡检 env 复核脚本、current release 自审脚本、状态快照脚本、证据包脚本、证据验真脚本、证据根目录审计脚本、canary access log 对账脚本、env 示例目录或 direct live smoke 脚本时都会失败且保持维护模式，还会验证相对 release root / current link / api env file、点目录或点开头 version 被拒绝、失败时不留下 staging / 正式 release 目录、同版本 release 目录已存在、current 路径不是符号链接或提升前 release 目录竞态出现时拒绝覆盖 / 合并。Pingora 影子网关不是默认 API 归档物；只有显式用 `npm run build:production-release -- --component api-server --include-pingora-gateway` 或在 `Genarrative-Api-Build` 勾选 `INCLUDE_PINGORA_GATEWAY` 时，发布包才包含 `pingora-gateway` / `pingora-gateway.sha256`，API deploy 会在两者同时存在且 manifest 登记 `pingora-gateway` 时校验并复制到 current release；此时 build 脚本和 Jenkins 会先检查 `cmake`、C 编译器和 C++ 编译器，避免进入 Cargo 后才因 `libz-ng-sys` 构建依赖缺失失败。发布包包含 Pingora 时，deploy 会在提升 release 前读取 `systemctl cat genarrative-pingora-gateway.service` 和其 `EnvironmentFile`，拒绝 direct-entry `CAP_NET_BIND_SERVICE`、拒绝非 `127.0.0.1:18081` 的 shadow listen、拒绝 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，确认仍是本机 shadow 高端口后才切换 current；切换后执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，让 shadow / canary 机器加载新网关二进制。该自动拉起不会启用公网 `80/443` 直连入口；已经进入 direct-entry 状态的机器应走正式直连 runbook 或先回退到 shadow。
+
+Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.mjs`、直连切换状态快照脚本 `scripts/ops/pingora-cutover-status-snapshot.mjs`、证据包脚本 `scripts/ops/pingora-cutover-evidence-bundle.mjs`、命令证据脚本 `scripts/ops/pingora-cutover-command-evidence.mjs`、证据验真脚本 `scripts/ops/pingora-cutover-evidence-verify.mjs`、证据根目录审计脚本 `scripts/ops/pingora-cutover-evidence-audit.mjs` 和 canary access log 对账脚本 `scripts/check-pingora-canary-access-log-parity.mjs` 都属于 API release 的强制随包依赖；缺少任一脚本时 `check:production-api-release`、`check:production-api-deploy` 和生产运维护栏都必须失败，避免切换窗口只能靠 Jenkins 工作区或源码 checkout 临时补自审、证据或日志对账脚本。
+
+同一 API release 随包依赖还必须包含 `scripts/check-pingora-release-readiness.mjs` 与 `scripts/check-pingora-canary-live.mjs`。前者在 current release 上以 `--release-runtime-only` 汇总运行时复核，后者支撑目标 Nginx canary live smoke；缺少任一脚本时不能进入直连切换窗口。
 
 `Genarrative-Stdb-Module-Build` 的 Jenkins 归档产物必须包含 `build/<version>/spacetime_module.wasm`、`spacetime_module.wasm.sha256`、`release-manifest.json`、`scripts/deploy/production-stdb-publish.sh`、`scripts/deploy/maintenance-on.sh`、`scripts/deploy/maintenance-off.sh` 和 `scripts/database-backup-to-oss.mjs`。`Genarrative-Stdb-Module-Publish` 只通过 `copyArtifacts` 复制这些产物和发布脚本，不再在目标机器 checkout Git；如果 publish 前备份脚本缺失，应先检查 Stdb Build 的归档列表和 Stdb Publish 的复制过滤器。
 
@@ -304,7 +375,6 @@ dev 服务器上的 Gitea 内网入口固定为 `http://10.2.0.10/GenarrativeAI/
 
 `scripts/jenkins-checkout-source.sh` 是生产 Jenkinsfile 内部二次确认源码的统一入口。构建流水线和服务器初始化流水线传入 `COMMIT_HASH` 时，脚本必须先保持 `depth=1` 浅拉，若上游 commit 已在浅历史内则直接校验并 checkout；只有浅历史无法证明 commit 属于目标分支时，才按 `GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS`（默认 `50 200 1000 5000`）逐步加深，最后才尝试展开完整历史。`Genarrative-Api-Deploy`、`Genarrative-Web-Deploy` 和 `Genarrative-Stdb-Module-Publish` 仍保留上游构建传入的 `COMMIT_HASH` 作为通知和追溯字段，但不再用它在目标机器重新 checkout 部署脚本。
 
-
 `Genarrative-Stdb-Module-Publish` 在 `Pipeline script from SCM` 阶段如果一开始就报 `No such DSL method 'pipeline'`，优先检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 是否带 UTF-8 BOM。Jenkins Declarative Pipeline 的首个 token 必须是纯 `pipeline`；仓库中的 Jenkinsfile 应保存为 UTF-8 without BOM，只有临时写给 Windows PowerShell 5.1 `-File` 执行的 `.ps1` 才需要按对应 helper 转成带 BOM。验证时可检查文件前三字节不再是 `EF BB BF`，并运行 `validateDeclarativePipeline` 或重放该流水线。
 
 `Genarrative-Stdb-Module-Build` 或 SpacetimeDB module 构建失败若出现 Rust `E0425 cannot find function migrate_*`，优先排查 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 等同文件内默认种子迁移 helper 是否在分支合并时只保留了调用、漏掉了函数定义。`Genarrative-Stdb-Module-Build` 现在运行在 `linux && genarrative-build` 节点上，Checkout 与 Build 都走 bash + cargo + sccache，不再依赖 Windows PowerShell 或 Git Bash；Stdb module 的 `CARGO_HOME`、`CARGO_TARGET_DIR` 和 `SCCACHE_DIR` 默认落在稳定缓存根 `~/caches/genarrative-jenkins/stdb-module` 下，可用 `GENARRATIVE_STDB_CACHE_ROOT` 覆盖，避免 `WORKSPACE@tmp` 被清理后无改动也触发近似冷构建。修复时不要直接删除迁移调用；应恢复只纠偏历史默认种子且不覆盖后台手动配置的 helper，并用 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 复现 Jenkins module 编译路径。
diff --git a/jenkins/Jenkinsfile.production-api-build b/jenkins/Jenkinsfile.production-api-build
index 91aa966b6..d3daebccb 100644
--- a/jenkins/Jenkinsfile.production-api-build
+++ b/jenkins/Jenkinsfile.production-api-build
@@ -23,6 +23,7 @@ pipeline {
     string(name: 'COMMIT_HASH', defaultValue: '', description: '可选，指定属于 SOURCE_BRANCH 的 Git commit')
     string(name: 'BUILD_VERSION', defaultValue: '', description: '发布版本号，留空则使用 Jenkins BUILD_NUMBER')
     string(name: 'NOTIFICATION_EMAILS', defaultValue: '', description: '本次运行追加通知邮箱；会与 Jenkins Secret Text 凭据 genarrative-notification-emails 合并发送')
+    booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', defaultValue: false, description: '是否额外构建并归档 Pingora 影子网关二进制')
     booleanParam(name: 'PUBLISH_AFTER_BUILD', defaultValue: false, description: '构建成功后是否触发 API 发布')
     string(name: 'DEPLOY_JOB_NAME', defaultValue: 'Genarrative-Api-Deploy', description: 'API 发布流水线作业名')
     choice(name: 'DEPLOY_TARGET', choices: ['development', 'release'], description: 'PUBLISH_AFTER_BUILD=true 时的逻辑部署目标；development 使用当前 Linux 开发/构建/开发部署 agent')
@@ -91,12 +92,30 @@ pipeline {
               echo "[api-build] 缺少 clang/lld。请在 genarrative-build 节点预先安装 Linux 构建依赖。" >&2
               exit 1
             fi
+            if [[ "${INCLUDE_PINGORA_GATEWAY:-false}" == "true" ]]; then
+              if ! command -v cmake >/dev/null 2>&1; then
+                echo "[api-build] 构建 Pingora 影子网关缺少 cmake；请在 genarrative-build 节点预先安装 cmake。" >&2
+                exit 1
+              fi
+              if ! command -v cc >/dev/null 2>&1 && ! command -v clang >/dev/null 2>&1 && ! command -v gcc >/dev/null 2>&1; then
+                echo "[api-build] 构建 Pingora 影子网关缺少 C 编译器；请预先安装 clang 或 gcc。" >&2
+                exit 1
+              fi
+              if ! command -v c++ >/dev/null 2>&1 && ! command -v clang++ >/dev/null 2>&1 && ! command -v g++ >/dev/null 2>&1; then
+                echo "[api-build] 构建 Pingora 影子网关缺少 C++ 编译器；请预先安装 clang++ 或 g++。" >&2
+                exit 1
+              fi
+            fi
             if ! command -v sccache >/dev/null 2>&1; then
               echo "[api-build] 未找到 sccache，改用 rustc 直接构建。"
               unset RUSTC_WRAPPER
             fi
+            pingora_args=()
+            if [[ "${INCLUDE_PINGORA_GATEWAY:-false}" == "true" ]]; then
+              pingora_args+=(--include-pingora-gateway)
+            fi
             SOURCE_BRANCH="${SOURCE_BRANCH}" SOURCE_COMMIT="${SOURCE_COMMIT}" \
-            npm run build:production-release -- --component api-server --name "${EFFECTIVE_BUILD_VERSION}"
+            npm run build:production-release -- --component api-server --name "${EFFECTIVE_BUILD_VERSION}" "${pingora_args[@]}"
           '
         '''
       }
@@ -104,7 +123,12 @@ pipeline {
 
     stage('Archive') {
       steps {
-        archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,scripts/deploy/production-api-deploy.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh", fingerprint: true
+        archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-current-release-audit.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-direct-rehearsal-status.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-status-snapshot.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-bundle.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-command-evidence.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-verify.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-audit.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-production-health-patrol-env.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-release-readiness.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-direct-preflight.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-direct-live.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-canary-live.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-canary-access-log-parity.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/production-api-deploy.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/maintenance-on.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/maintenance-off.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/systemd/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/nginx/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/env/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/pingora/**", fingerprint: true
+        script {
+          if (params.INCLUDE_PINGORA_GATEWAY) {
+            archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/pingora-gateway,build/${env.EFFECTIVE_BUILD_VERSION}/pingora-gateway.sha256", fingerprint: true
+          }
+        }
       }
     }
 
@@ -122,6 +146,7 @@ pipeline {
             string(name: 'BUILD_VERSION', value: env.EFFECTIVE_BUILD_VERSION),
             string(name: 'NOTIFICATION_EMAILS', value: params.NOTIFICATION_EMAILS ?: ''),
             string(name: 'DEPLOY_TARGET', value: params.DEPLOY_TARGET),
+            booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', value: params.INCLUDE_PINGORA_GATEWAY),
             booleanParam(name: 'CONFIRM_RELEASE_DEPLOY_AGENT', value: params.CONFIRM_RELEASE_DEPLOY_AGENT),
             string(name: 'BUILD_JOB_NAME', value: env.JOB_NAME),
             string(name: 'BUILD_NUMBER_TO_DEPLOY', value: env.BUILD_NUMBER),
@@ -143,6 +168,7 @@ pipeline {
           string(name: 'BUILD_VERSION', value: env.EFFECTIVE_BUILD_VERSION ?: (params.BUILD_VERSION ?: '')),
           string(name: 'DEPLOY_TARGET', value: params.DEPLOY_TARGET ?: ''),
           string(name: 'DATABASE', value: params.DATABASE ?: ''),
+          string(name: 'INCLUDE_PINGORA_GATEWAY', value: String.valueOf(params.INCLUDE_PINGORA_GATEWAY)),
           string(name: 'SUMMARY', value: 'API 构建流水线结束'),
         ]
         def notificationRecipients = params.NOTIFICATION_EMAILS?.trim()
diff --git a/jenkins/Jenkinsfile.production-api-deploy b/jenkins/Jenkinsfile.production-api-deploy
index 152c181f0..39fc7e70b 100644
--- a/jenkins/Jenkinsfile.production-api-deploy
+++ b/jenkins/Jenkinsfile.production-api-deploy
@@ -16,6 +16,7 @@ pipeline {
     string(name: 'BUILD_VERSION', defaultValue: '', description: '待发布版本号')
     string(name: 'BUILD_JOB_NAME', defaultValue: 'Genarrative-Api-Build', description: 'API 构建流水线作业名')
     string(name: 'BUILD_NUMBER_TO_DEPLOY', defaultValue: '', description: '要复制归档产物的上游构建号')
+    booleanParam(name: 'INCLUDE_PINGORA_GATEWAY', defaultValue: false, description: '上游构建是否包含 Pingora 影子网关产物')
     string(name: 'RELEASE_ROOT', defaultValue: '/opt/genarrative/releases', description: '生产 release 根目录')
     string(name: 'CURRENT_LINK', defaultValue: '/opt/genarrative/current', description: '当前版本软链接')
     string(name: 'SERVICE_NAME', defaultValue: 'genarrative-api.service', description: 'systemd 服务名')
@@ -65,10 +66,21 @@ pipeline {
         copyArtifacts(
           projectName: params.BUILD_JOB_NAME,
           selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
-          filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json,build/${params.BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${params.BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,scripts/deploy/production-api-deploy.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh",
+          filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json,build/${params.BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${params.BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-current-release-audit.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-direct-rehearsal-status.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-status-snapshot.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-bundle.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-command-evidence.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-verify.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-audit.mjs,build/${params.BUILD_VERSION}/scripts/check-production-health-patrol-env.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-release-readiness.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-direct-preflight.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-direct-live.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-canary-live.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-canary-access-log-parity.mjs,build/${params.BUILD_VERSION}/scripts/deploy/production-api-deploy.sh,build/${params.BUILD_VERSION}/scripts/deploy/maintenance-on.sh,build/${params.BUILD_VERSION}/scripts/deploy/maintenance-off.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs,build/${params.BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs,build/${params.BUILD_VERSION}/deploy/systemd/**,build/${params.BUILD_VERSION}/deploy/nginx/**,build/${params.BUILD_VERSION}/deploy/env/**,build/${params.BUILD_VERSION}/deploy/pingora/**",
           target: '.',
           fingerprintArtifacts: true
         )
+        script {
+          if (params.INCLUDE_PINGORA_GATEWAY) {
+            copyArtifacts(
+              projectName: params.BUILD_JOB_NAME,
+              selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
+              filter: "build/${params.BUILD_VERSION}/pingora-gateway,build/${params.BUILD_VERSION}/pingora-gateway.sha256",
+              target: '.',
+              fingerprintArtifacts: true
+            )
+          }
+        }
       }
     }
 
@@ -80,8 +92,8 @@ pipeline {
         sh '''
           bash -lc '
             set -euo pipefail
-            chmod +x scripts/deploy/production-api-deploy.sh scripts/deploy/maintenance-on.sh scripts/deploy/maintenance-off.sh
-            scripts/deploy/production-api-deploy.sh \
+            chmod +x "build/${BUILD_VERSION}/scripts/deploy/production-api-deploy.sh" "build/${BUILD_VERSION}/scripts/deploy/maintenance-on.sh" "build/${BUILD_VERSION}/scripts/deploy/maintenance-off.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs" "build/${BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
+            "build/${BUILD_VERSION}/scripts/deploy/production-api-deploy.sh" \
               --source-dir "build/${BUILD_VERSION}" \
               --version "${BUILD_VERSION}" \
               --release-root "${RELEASE_ROOT}" \
@@ -110,6 +122,7 @@ pipeline {
           string(name: 'BUILD_VERSION', value: env.EFFECTIVE_BUILD_VERSION ?: (params.BUILD_VERSION ?: '')),
           string(name: 'DEPLOY_TARGET', value: params.DEPLOY_TARGET ?: ''),
           string(name: 'DATABASE', value: params.DATABASE ?: ''),
+          string(name: 'INCLUDE_PINGORA_GATEWAY', value: String.valueOf(params.INCLUDE_PINGORA_GATEWAY)),
           string(name: 'SUMMARY', value: 'API 发布流水线结束'),
         ]
         def notificationRecipients = params.NOTIFICATION_EMAILS?.trim()
diff --git a/package.json b/package.json
index a13d9d998..537fa0846 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,41 @@
     "check:encoding": "node scripts/check-encoding.mjs",
     "check:spacetime-schema": "node scripts/check-spacetime-schema-guard.mjs",
     "check:production-ops": "node scripts/check-production-ops-guardrails.mjs",
+    "check:production-health-patrol": "node scripts/check-production-health-patrol.mjs",
+    "check:production-health-patrol-env": "node scripts/check-production-health-patrol-env-check.mjs",
+    "check:production-api-release": "node scripts/check-production-api-release.mjs",
+    "check:production-api-deploy": "node scripts/check-production-api-deploy.mjs",
+    "check:pingora-gateway-smoke": "node scripts/check-pingora-gateway-smoke.mjs",
+    "check:nginx-pingora-canary": "node scripts/check-nginx-pingora-canary.mjs",
+    "check:pingora-route-parity": "node scripts/check-pingora-route-parity.mjs",
+    "check:pingora-canary-live": "node scripts/check-pingora-canary-live.mjs",
+    "check:pingora-canary-live-guard": "node scripts/check-pingora-canary-live-guard.mjs",
+    "check:pingora-realpath-canary-toggle": "node scripts/check-pingora-realpath-canary-toggle.mjs",
+    "check:pingora-direct-preflight": "node -- scripts/check-pingora-direct-preflight.mjs && node scripts/check-pingora-direct-preflight-guard.mjs",
+    "check:pingora-direct-live": "node scripts/check-pingora-direct-live.mjs",
+    "check:pingora-direct-live-guard": "node scripts/check-pingora-direct-live-guard.mjs",
+    "check:pingora-direct-enable": "node scripts/check-pingora-direct-enable.mjs",
+    "check:pingora-direct-rollback": "node scripts/check-pingora-direct-rollback.mjs",
+    "check:pingora-health-patrol-env-switch": "node scripts/check-pingora-health-patrol-env-switch.mjs",
+    "check:pingora-gateway-env-shadow-switch": "node scripts/check-pingora-gateway-env-shadow-switch.mjs",
+    "check:pingora-tls-cert-sync": "node scripts/check-pingora-tls-cert-sync.mjs",
+    "check:pingora-current-release-audit": "node scripts/check-pingora-current-release-audit.mjs",
+    "check:pingora-direct-rehearsal-status": "node scripts/check-pingora-direct-rehearsal-status.mjs",
+    "check:pingora-cutover-status-snapshot": "node scripts/check-pingora-cutover-status-snapshot.mjs",
+    "check:pingora-cutover-evidence-bundle": "node scripts/check-pingora-cutover-evidence-bundle.mjs",
+    "check:pingora-cutover-command-evidence": "node scripts/check-pingora-cutover-command-evidence.mjs",
+    "check:pingora-cutover-evidence-verify": "node scripts/check-pingora-cutover-evidence-verify.mjs",
+    "check:pingora-cutover-evidence-audit": "node scripts/check-pingora-cutover-evidence-audit.mjs",
+    "check:pingora-canary-access-log-parity": "node scripts/check-pingora-canary-access-log-parity-check.mjs",
+    "check:pingora-canary-docker": "node scripts/check-pingora-canary-docker.mjs",
+    "check:pingora-production-release-build": "node scripts/check-pingora-production-release-build.mjs",
+    "check:pingora-release-readiness-plan": "node scripts/check-pingora-release-readiness-plan.mjs",
+    "check:pingora-release-readiness": "node scripts/check-pingora-release-readiness.mjs",
+    "plan:pingora-direct-cutover": "node scripts/check-pingora-release-readiness.mjs --dry-run-cutover",
+    "deploy:pingora-realpath-canary-enable": "bash scripts/deploy/pingora-realpath-canary-enable.sh",
+    "deploy:pingora-realpath-canary-disable": "bash scripts/deploy/pingora-realpath-canary-disable.sh",
+    "deploy:pingora-direct-enable": "bash scripts/deploy/pingora-direct-enable.sh",
+    "deploy:pingora-direct-rollback": "bash scripts/deploy/pingora-direct-rollback.sh",
     "assets:child-motion-demo": "node scripts/generate-child-motion-demo-assets.mjs",
     "assets:match3d-style-references": "node scripts/generate-match3d-style-references.mjs",
     "check:visual-novel-vn11": "node scripts/check-visual-novel-vn11-negative-scan.mjs",
diff --git a/scripts/build-production-release.sh b/scripts/build-production-release.sh
index 19924c547..5b08f1f71 100644
--- a/scripts/build-production-release.sh
+++ b/scripts/build-production-release.sh
@@ -18,6 +18,10 @@ usage() {
   --skip-web-build        跳过主站与后台构建，仅复制已有 dist 产物
   --skip-api-build        跳过 api-server 构建，仅复制已有 release 二进制
   --skip-spacetime-build  跳过 spacetime-module 构建，仅复制已有 wasm
+  --include-pingora-gateway
+                         额外构建并打包 Pingora 影子网关二进制，默认不启用
+  --skip-pingora-gateway-build
+                         跳过 Pingora 构建，仅复制已有 release 二进制
   --no-migration-bootstrap-secret
                          构建不带迁移引导密钥的 spacetime-module wasm
 EOF
@@ -32,6 +36,28 @@ require_command() {
   fi
 }
 
+require_any_command() {
+  local label="$1"
+  shift
+
+  local command_name
+  for command_name in "$@"; do
+    if command -v "${command_name}" >/dev/null 2>&1; then
+      return
+    fi
+  done
+
+  echo "[production-release] 缺少 ${label}: $*" >&2
+  exit 1
+}
+
+require_pingora_build_toolchain() {
+  require_command cargo
+  require_command cmake
+  require_any_command "C 编译器" cc clang gcc
+  require_any_command "C++ 编译器" c++ clang++ g++
+}
+
 copy_required_file() {
   local source_path="$1"
   local target_path="$2"
@@ -140,6 +166,7 @@ write_release_manifest() {
   RELEASE_INCLUDE_WEB="${BUILD_WEB}" \
   RELEASE_INCLUDE_API="${BUILD_API}" \
   RELEASE_INCLUDE_SPACETIME="${BUILD_SPACETIME}" \
+  RELEASE_INCLUDE_PINGORA_GATEWAY="${INCLUDE_PINGORA_GATEWAY}" \
   RELEASE_INCLUDE_MIGRATION_BOOTSTRAP_SECRET="${MIGRATION_BOOTSTRAP_SECRET_ARTIFACT}" \
   node <<'NODE'
 const fs = require('fs');
@@ -166,6 +193,13 @@ if (process.env.RELEASE_INCLUDE_SPACETIME === '1') {
     checksum_path: 'spacetime_module.wasm.sha256',
   });
 }
+if (process.env.RELEASE_INCLUDE_PINGORA_GATEWAY === '1') {
+  artifacts.push({
+    component: 'pingora-gateway',
+    path: 'pingora-gateway',
+    checksum_path: 'pingora-gateway.sha256',
+  });
+}
 if (process.env.RELEASE_INCLUDE_MIGRATION_BOOTSTRAP_SECRET === '1') {
   artifacts.push({
     component: 'spacetime-module',
@@ -196,6 +230,8 @@ COMPONENT="all"
 SKIP_WEB_BUILD=0
 SKIP_API_BUILD=0
 SKIP_SPACETIME_BUILD=0
+SKIP_PINGORA_GATEWAY_BUILD=0
+INCLUDE_PINGORA_GATEWAY=0
 MIGRATION_BOOTSTRAP_SECRET=""
 MIGRATION_BOOTSTRAP_SECRET_ARTIFACT=0
 MIGRATION_BOOTSTRAP_SECRET_MODE="auto"
@@ -227,6 +263,14 @@ while [[ $# -gt 0 ]]; do
       SKIP_SPACETIME_BUILD=1
       shift
       ;;
+    --include-pingora-gateway)
+      INCLUDE_PINGORA_GATEWAY=1
+      shift
+      ;;
+    --skip-pingora-gateway-build)
+      SKIP_PINGORA_GATEWAY_BUILD=1
+      shift
+      ;;
     --no-migration-bootstrap-secret)
       MIGRATION_BOOTSTRAP_SECRET=""
       MIGRATION_BOOTSTRAP_SECRET_MODE="disabled"
@@ -276,6 +320,7 @@ WEB_DIR="${TARGET_DIR}/web"
 ADMIN_WEB_DIR="${WEB_DIR}/admin"
 CARGO_TARGET_DIR="${CARGO_TARGET_DIR:-${SERVER_RS_DIR}/target}"
 API_BINARY_SOURCE="${CARGO_TARGET_DIR}/x86_64-unknown-linux-gnu/release/api-server"
+PINGORA_GATEWAY_BINARY_SOURCE="${CARGO_TARGET_DIR}/x86_64-unknown-linux-gnu/release/pingora-gateway"
 WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module.wasm"
 RELEASE_SOURCE_BRANCH="${SOURCE_BRANCH:-${GIT_BRANCH:-}}"
 RELEASE_SOURCE_BRANCH="${RELEASE_SOURCE_BRANCH#origin/}"
@@ -310,7 +355,6 @@ if [[ -e "${TARGET_DIR}" ]]; then
   exit 1
 fi
 
-require_command node
 require_command node
 require_command sha256sum
 
@@ -322,6 +366,10 @@ if [[ "${BUILD_SPACETIME}" -eq 1 && "${SKIP_SPACETIME_BUILD}" -ne 1 ]]; then
   require_command cargo
 fi
 
+if [[ "${INCLUDE_PINGORA_GATEWAY}" -eq 1 && "${SKIP_PINGORA_GATEWAY_BUILD}" -ne 1 ]]; then
+  require_pingora_build_toolchain
+fi
+
 if [[ "${BUILD_WEB}" -eq 1 && "${SKIP_WEB_BUILD}" -ne 1 ]]; then
   require_command node
   require_command npm
@@ -427,6 +475,24 @@ if [[ "${BUILD_API}" -eq 1 ]]; then
   write_sha256_file "${TARGET_DIR}/api-server"
 fi
 
+if [[ "${INCLUDE_PINGORA_GATEWAY}" -eq 1 && "${SKIP_PINGORA_GATEWAY_BUILD}" -ne 1 ]]; then
+  echo "[production-release] 构建 pingora-gateway -> x86_64-unknown-linux-gnu"
+  (
+    cd "${SERVER_RS_DIR}"
+    cargo build \
+      -p pingora-gateway \
+      --release \
+      --target x86_64-unknown-linux-gnu \
+      --manifest-path "${SERVER_RS_DIR}/Cargo.toml"
+  )
+fi
+
+if [[ "${INCLUDE_PINGORA_GATEWAY}" -eq 1 ]]; then
+  copy_required_file "${PINGORA_GATEWAY_BINARY_SOURCE}" "${TARGET_DIR}/pingora-gateway" "pingora-gateway release binary"
+  chmod +x "${TARGET_DIR}/pingora-gateway"
+  write_sha256_file "${TARGET_DIR}/pingora-gateway"
+fi
+
 if [[ "${BUILD_SPACETIME}" -eq 1 && "${SKIP_SPACETIME_BUILD}" -ne 1 ]]; then
   echo "[production-release] 构建 spacetime-module -> wasm32-unknown-unknown"
   (
@@ -445,10 +511,20 @@ if [[ "${BUILD_SPACETIME}" -eq 1 ]]; then
   write_migration_bootstrap_secret_file
 fi
 
-mkdir -p "${TARGET_DIR}/scripts" "${TARGET_DIR}/scripts/ops" "${TARGET_DIR}/deploy"
+mkdir -p "${TARGET_DIR}/scripts" "${TARGET_DIR}/scripts/deploy" "${TARGET_DIR}/scripts/ops" "${TARGET_DIR}/deploy"
 cp "${SCRIPT_DIR}/deploy/maintenance-on.sh" "${TARGET_DIR}/scripts/maintenance-on.sh"
 cp "${SCRIPT_DIR}/deploy/maintenance-off.sh" "${TARGET_DIR}/scripts/maintenance-off.sh"
 cp "${SCRIPT_DIR}/deploy/maintenance-status.sh" "${TARGET_DIR}/scripts/maintenance-status.sh"
+cp "${SCRIPT_DIR}/deploy/production-api-deploy.sh" "${TARGET_DIR}/scripts/deploy/production-api-deploy.sh"
+cp "${SCRIPT_DIR}/deploy/maintenance-on.sh" "${TARGET_DIR}/scripts/deploy/maintenance-on.sh"
+cp "${SCRIPT_DIR}/deploy/maintenance-off.sh" "${TARGET_DIR}/scripts/deploy/maintenance-off.sh"
+cp "${SCRIPT_DIR}/deploy/pingora-direct-enable.sh" "${TARGET_DIR}/scripts/deploy/pingora-direct-enable.sh"
+cp "${SCRIPT_DIR}/deploy/pingora-direct-rollback.sh" "${TARGET_DIR}/scripts/deploy/pingora-direct-rollback.sh"
+cp "${SCRIPT_DIR}/deploy/pingora-realpath-canary-enable.sh" "${TARGET_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh"
+cp "${SCRIPT_DIR}/deploy/pingora-realpath-canary-disable.sh" "${TARGET_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh"
+cp "${SCRIPT_DIR}/deploy/pingora-health-patrol-env-switch.mjs" "${TARGET_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
+cp "${SCRIPT_DIR}/deploy/pingora-gateway-env-shadow-switch.mjs" "${TARGET_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
+cp "${SCRIPT_DIR}/deploy/pingora-tls-cert-sync.mjs" "${TARGET_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs"
 cp "${SCRIPT_DIR}/deploy/jenkins-inbound-agent-start.sh" "${TARGET_DIR}/scripts/jenkins-inbound-agent-start.sh"
 cp "${SCRIPT_DIR}/deploy/install-jenkins-inbound-agent.sh" "${TARGET_DIR}/scripts/install-jenkins-inbound-agent.sh"
 cp "${SCRIPT_DIR}/deploy/jenkins-agent-reverse-tunnel.ps1" "${TARGET_DIR}/scripts/jenkins-agent-reverse-tunnel.ps1"
@@ -457,6 +533,16 @@ chmod +x \
   "${TARGET_DIR}/scripts/maintenance-on.sh" \
   "${TARGET_DIR}/scripts/maintenance-off.sh" \
   "${TARGET_DIR}/scripts/maintenance-status.sh" \
+  "${TARGET_DIR}/scripts/deploy/production-api-deploy.sh" \
+  "${TARGET_DIR}/scripts/deploy/maintenance-on.sh" \
+  "${TARGET_DIR}/scripts/deploy/maintenance-off.sh" \
+  "${TARGET_DIR}/scripts/deploy/pingora-direct-enable.sh" \
+  "${TARGET_DIR}/scripts/deploy/pingora-direct-rollback.sh" \
+  "${TARGET_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh" \
+  "${TARGET_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh" \
+  "${TARGET_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs" \
+  "${TARGET_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs" \
+  "${TARGET_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs" \
   "${TARGET_DIR}/scripts/jenkins-inbound-agent-start.sh" \
   "${TARGET_DIR}/scripts/install-jenkins-inbound-agent.sh"
 
@@ -467,10 +553,24 @@ copy_required_file "${SCRIPT_DIR}/spacetime-authorize-migration-operator.mjs" "$
 copy_required_file "${SCRIPT_DIR}/spacetime-revoke-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-revoke-migration-operator.mjs" "数据库迁移撤权脚本"
 copy_required_file "${SCRIPT_DIR}/database-backup-to-oss.mjs" "${TARGET_DIR}/scripts/database-backup-to-oss.mjs" "数据库 OSS 备份脚本"
 copy_required_file "${SCRIPT_DIR}/ops/production-health-patrol.mjs" "${TARGET_DIR}/scripts/ops/production-health-patrol.mjs" "生产健康巡检脚本"
+copy_required_file "${SCRIPT_DIR}/ops/pingora-current-release-audit.mjs" "${TARGET_DIR}/scripts/ops/pingora-current-release-audit.mjs" "Pingora current release 自审脚本"
+copy_required_file "${SCRIPT_DIR}/ops/pingora-direct-rehearsal-status.mjs" "${TARGET_DIR}/scripts/ops/pingora-direct-rehearsal-status.mjs" "Pingora 直连切换彩排状态脚本"
+copy_required_file "${SCRIPT_DIR}/ops/pingora-cutover-status-snapshot.mjs" "${TARGET_DIR}/scripts/ops/pingora-cutover-status-snapshot.mjs" "Pingora 直连切换状态快照脚本"
+copy_required_file "${SCRIPT_DIR}/ops/pingora-cutover-evidence-bundle.mjs" "${TARGET_DIR}/scripts/ops/pingora-cutover-evidence-bundle.mjs" "Pingora 直连切换证据包脚本"
+copy_required_file "${SCRIPT_DIR}/ops/pingora-cutover-command-evidence.mjs" "${TARGET_DIR}/scripts/ops/pingora-cutover-command-evidence.mjs" "Pingora 直连切换命令证据脚本"
+copy_required_file "${SCRIPT_DIR}/ops/pingora-cutover-evidence-verify.mjs" "${TARGET_DIR}/scripts/ops/pingora-cutover-evidence-verify.mjs" "Pingora 直连切换证据验真脚本"
+copy_required_file "${SCRIPT_DIR}/ops/pingora-cutover-evidence-audit.mjs" "${TARGET_DIR}/scripts/ops/pingora-cutover-evidence-audit.mjs" "Pingora 直连切换证据根目录审计脚本"
+copy_required_file "${SCRIPT_DIR}/check-production-health-patrol-env.mjs" "${TARGET_DIR}/scripts/check-production-health-patrol-env.mjs" "生产健康巡检 env 复核脚本"
+copy_required_file "${SCRIPT_DIR}/check-pingora-release-readiness.mjs" "${TARGET_DIR}/scripts/check-pingora-release-readiness.mjs" "Pingora release readiness 聚合门禁脚本"
+copy_required_file "${SCRIPT_DIR}/check-pingora-direct-preflight.mjs" "${TARGET_DIR}/scripts/check-pingora-direct-preflight.mjs" "Pingora 直连预检脚本"
+copy_required_file "${SCRIPT_DIR}/check-pingora-direct-live.mjs" "${TARGET_DIR}/scripts/check-pingora-direct-live.mjs" "Pingora 直连 live smoke 脚本"
+copy_required_file "${SCRIPT_DIR}/check-pingora-canary-live.mjs" "${TARGET_DIR}/scripts/check-pingora-canary-live.mjs" "Pingora canary live smoke 脚本"
+copy_required_file "${SCRIPT_DIR}/check-pingora-canary-access-log-parity.mjs" "${TARGET_DIR}/scripts/check-pingora-canary-access-log-parity.mjs" "Pingora canary access log 对账脚本"
 
 copy_required_dir "${REPO_ROOT}/deploy/systemd" "${TARGET_DIR}/deploy/systemd" "systemd 配置"
 copy_required_dir "${REPO_ROOT}/deploy/nginx" "${TARGET_DIR}/deploy/nginx" "Nginx 配置"
 copy_required_dir "${REPO_ROOT}/deploy/env" "${TARGET_DIR}/deploy/env" "生产环境示例"
+copy_required_dir "${REPO_ROOT}/deploy/pingora" "${TARGET_DIR}/deploy/pingora" "Pingora 配置"
 
 cat >"${TARGET_DIR}/README.md" <<EOF
 # Genarrative Production Release
@@ -482,13 +582,24 @@ cat >"${TARGET_DIR}/README.md" <<EOF
 - \`web/\`：主站静态资源，\`web/admin/\` 为后台静态资源，\`web/maintenance.html\` 为维护页。
 - \`web.tar.gz\` / \`web.tar.gz.sha256\`：Web 发布流水线使用的静态资源压缩包与校验文件。
 - \`api-server\`：生产 Linux release 可执行文件。
+- \`pingora-gateway\`：可选 Pingora 影子网关可执行文件，仅在显式 \`--include-pingora-gateway\` 时包含。
 - \`spacetime_module.wasm\`：SpacetimeDB 模块 wasm。
 - \`migration-bootstrap-secret.txt\`：构建 \`spacetime_module.wasm\` 时注入的迁移引导密钥，仅用于创建首个迁移操作员；请作为敏感文件保存到 Jenkins Secret Text，授权完成后不要长期留在公开归档中。
 - \`*.sha256\`：发布产物 checksum，用于部署前校验。
 - \`release-manifest.json\`：发布版本、源码 commit 与产物清单。
-- \`scripts/\`：维护模式脚本、数据库导入导出脚本、数据库 OSS 备份脚本、生产健康巡检脚本、迁移授权脚本和 Jenkins inbound agent systemd 安装脚本。
+- \`scripts/\`：维护模式脚本、数据库导入导出脚本、数据库 OSS 备份脚本、生产健康巡检脚本、Pingora release readiness 聚合门禁、直连启用 / 回退、realpath canary 启用 / 关闭、health patrol env 切换 / TLS 证书同步 / 预检 / direct live smoke / canary live smoke / canary access log 对账 / current release 自审 / 直连彩排状态 / 状态快照 / 证据包 / 命令证据 / 证据验真 / 证据根目录审计脚本、迁移授权脚本和 Jenkins inbound agent systemd 安装脚本。
+- \`scripts/deploy/production-api-deploy.sh\`：API Deploy 执行入口；同目录的 \`maintenance-on.sh\` / \`maintenance-off.sh\` 必须来自同一发布包。
 - \`deploy/\`：systemd、Nginx 和生产环境变量示例；\`deploy/nginx/genarrative-dev-http.conf\` 仅供无域名开发服初始化使用。
 
+## Pingora 直连证据总审计
+
+正式切换 runbook 的最终证据根目录总审计必须使用 current release 随包脚本，并同时保留两条真实切换脚本身份要求：
+
+- \`--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh\`
+- \`--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh\`
+
+这两项用于证明 enable / rollback apply 命令证据里真实执行的是 \`/opt/genarrative/current\` 下的随包脚本，而不是 Jenkins 工作区、源码 checkout 或旧发布目录中的同名脚本。
+
 ## 生产部署口径
 
 本发布包不包含旧一体化 \`start.sh\`、\`stop.sh\` 或 \`web-server.mjs\`。
diff --git a/scripts/check-nginx-pingora-canary.mjs b/scripts/check-nginx-pingora-canary.mjs
new file mode 100644
index 000000000..a6e6d5f35
--- /dev/null
+++ b/scripts/check-nginx-pingora-canary.mjs
@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const PREFIX_SNIPPET_PATH =
+  'deploy/nginx/snippets/genarrative-pingora-canary.conf';
+const REALPATH_SNIPPET_PATH =
+  'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf';
+const PROBE_TOKEN_PLACEHOLDER = '__GENARRATIVE_PINGORA_PROBE_TOKEN__';
+const CANARY_PREFIX = '/__genarrative_pingora_canary';
+const REALPATH_HEALTHZ_PATH = '/__genarrative_pingora_realpath_canary/healthz';
+const PINGORA_UPSTREAM = 'http://127.0.0.1:18081';
+const REALPATH_HANDOFF =
+  'add_header X-Genarrative-Nginx-Handoff pingora-realpath-canary always;';
+
+const requireNginx = process.argv.includes('--require-nginx');
+const explicitNginxBinary =
+  process.env.GENARRATIVE_CHECK_NGINX_BINARY?.trim() ?? '';
+const nginxBinary = explicitNginxBinary || 'nginx';
+const failures = [];
+let activeSnippetPath = PREFIX_SNIPPET_PATH;
+
+function fail(message) {
+  failures.push(message);
+}
+
+function countOccurrences(content, needle) {
+  return content.split(needle).length - 1;
+}
+
+function requireIncludes(content, needle, reason) {
+  if (!content.includes(needle)) {
+    fail(`${activeSnippetPath}: 缺少 ${needle}。${reason}`);
+  }
+}
+
+function requireNotMatches(content, pattern, reason) {
+  if (pattern.test(content)) {
+    fail(`${activeSnippetPath}: ${reason}`);
+  }
+}
+
+function extractLocationBlocks(content) {
+  const blocks = new Map();
+  const locationPattern = /^\s*location\s+([^{]+)\{/gmu;
+
+  for (const match of content.matchAll(locationPattern)) {
+    const openBraceIndex = content.indexOf('{', match.index);
+    let depth = 0;
+
+    for (let index = openBraceIndex; index < content.length; index += 1) {
+      const char = content[index];
+      if (char === '{') {
+        depth += 1;
+      } else if (char === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          const header = `location ${match[1].trim()}`;
+          const block = content.slice(match.index, index + 1);
+          const body = content.slice(openBraceIndex + 1, index);
+          blocks.set(header, { body, block });
+          break;
+        }
+      }
+    }
+  }
+
+  return blocks;
+}
+
+function requireLocation(blocks, header) {
+  const block = blocks.get(header);
+  if (!block) {
+    fail(`${activeSnippetPath}: 缺少 ${header} location。`);
+  }
+  return block;
+}
+
+function requireLocationIncludes(header, block, needle, reason) {
+  if (!block?.body.includes(needle)) {
+    fail(`${activeSnippetPath}: ${header} 缺少 ${needle}。${reason}`);
+  }
+}
+
+function requireLocalOnlyAccess(header, block) {
+  for (const directive of ['allow 127.0.0.1;', 'allow ::1;', 'deny all;']) {
+    requireLocationIncludes(
+      header,
+      block,
+      directive,
+      'canary 入口默认必须只放行本机，避免误 include 后公开接流。',
+    );
+  }
+}
+
+function runStaticChecks(content) {
+  requireIncludes(
+    content,
+    PROBE_TOKEN_PLACEHOLDER,
+    '仓库模板必须保留 probe token 占位符，部署时再替换为非 Git 密钥。',
+  );
+  requireIncludes(
+    content,
+    `proxy_pass ${PINGORA_UPSTREAM}`,
+    'canary 必须固定转发到本机 Pingora shadow 端口。',
+  );
+  requireIncludes(
+    content,
+    'X-Genarrative-Nginx-Handoff',
+    'canary 响应必须带 handoff 标识，方便验证请求确实经 Nginx 交给 Pingora。',
+  );
+  requireNotMatches(
+    content,
+    /^\s*(http|server|listen)\b/mu,
+    'canary snippet 只能包含 location 片段，不能自行声明 http/server/listen。',
+  );
+
+  const locationBlocks = extractLocationBlocks(content);
+  if (locationBlocks.size !== 3) {
+    fail(
+      `${activeSnippetPath}: 预期只有 3 个 location，实际 ${locationBlocks.size} 个。`,
+    );
+  }
+
+  const healthzHeader = `location = ${CANARY_PREFIX}/healthz`;
+  const websocketHeader = `location ~ ^${CANARY_PREFIX}/v1/database/[^/]+/subscribe$`;
+  const genericHeader = `location ${CANARY_PREFIX}/`;
+  const healthz = requireLocation(locationBlocks, healthzHeader);
+  const websocket = requireLocation(locationBlocks, websocketHeader);
+  const generic = requireLocation(locationBlocks, genericHeader);
+
+  for (const [header, block] of [
+    [healthzHeader, healthz],
+    [websocketHeader, websocket],
+    [genericHeader, generic],
+  ]) {
+    requireLocalOnlyAccess(header, block);
+    requireLocationIncludes(
+      header,
+      block,
+      'add_header X-Genarrative-Nginx-Handoff pingora-canary always;',
+      '每条 canary 路由都必须可通过响应头审计 handoff。',
+    );
+    requireLocationIncludes(
+      header,
+      block,
+      'proxy_set_header X-Request-Id $request_id;',
+      'canary 访问需要沿用 Nginx request_id，便于和 Pingora access log 对照。',
+    );
+  }
+
+  requireLocationIncludes(
+    healthzHeader,
+    healthz,
+    `proxy_set_header X-Genarrative-Pingora-Probe "${PROBE_TOKEN_PLACEHOLDER}";`,
+    'healthz handoff 必须带 shadow probe token。',
+  );
+  requireLocationIncludes(
+    healthzHeader,
+    healthz,
+    `proxy_pass ${PINGORA_UPSTREAM}/__genarrative_pingora/healthz;`,
+    'healthz canary 必须转到 Pingora 内部探针路径。',
+  );
+
+  for (const [header, block] of [
+    [websocketHeader, websocket],
+    [genericHeader, generic],
+  ]) {
+    requireLocationIncludes(
+      header,
+      block,
+      `rewrite ^${CANARY_PREFIX}(/.*)$ $1 break;`,
+      'canary 前缀必须在转发给 Pingora 前剥离。',
+    );
+    requireLocationIncludes(
+      header,
+      block,
+      `proxy_pass ${PINGORA_UPSTREAM};`,
+      '剥离前缀后的请求必须交给 Pingora shadow。',
+    );
+  }
+
+  requireLocationIncludes(
+    websocketHeader,
+    websocket,
+    'proxy_set_header Upgrade $http_upgrade;',
+    'SpacetimeDB subscribe 必须保留 WebSocket Upgrade。',
+  );
+  requireLocationIncludes(
+    websocketHeader,
+    websocket,
+    'proxy_set_header Connection "Upgrade";',
+    'SpacetimeDB subscribe 必须保留 WebSocket Upgrade 连接语义。',
+  );
+  requireLocationIncludes(
+    websocketHeader,
+    websocket,
+    'proxy_read_timeout 3600s;',
+    'WebSocket canary 不能被短读超时提前断开。',
+  );
+
+  requireLocationIncludes(
+    genericHeader,
+    generic,
+    'proxy_buffering off;',
+    'API / SSE canary 必须保持低缓冲口径。',
+  );
+  requireLocationIncludes(
+    genericHeader,
+    generic,
+    'add_header X-Accel-Buffering no always;',
+    'API / SSE canary 必须显式关闭加速缓冲。',
+  );
+  requireLocationIncludes(
+    genericHeader,
+    generic,
+    'proxy_set_header X-Genarrative-Pingora-Canary "nginx-prefixed";',
+    'Pingora access log 需要能识别来自 Nginx 前缀 canary 的请求。',
+  );
+
+  if (
+    countOccurrences(
+      content,
+      'add_header X-Genarrative-Nginx-Handoff pingora-canary always;',
+    ) !== 3
+  ) {
+    fail(`${activeSnippetPath}: handoff 响应头必须在 3 个 location 中各出现一次。`);
+  }
+  if (countOccurrences(content, 'deny all;') !== 3) {
+    fail(`${activeSnippetPath}: deny all 必须在 3 个 location 中各出现一次。`);
+  }
+  if (countOccurrences(content, 'X-Genarrative-Pingora-Probe') !== 1) {
+    fail(`${activeSnippetPath}: probe token 只能出现在 healthz canary 路由。`);
+  }
+}
+
+function runRealpathStaticChecks(content) {
+  requireIncludes(
+    content,
+    PROBE_TOKEN_PLACEHOLDER,
+    '仓库模板必须保留 probe token 占位符，部署时再替换为非 Git 密钥。',
+  );
+  requireIncludes(
+    content,
+    'server {',
+    '真实路径 canary 必须是独立 server 片段，避免 include 到生产 443 server 后覆盖正式 location。',
+  );
+  requireIncludes(
+    content,
+    'listen 127.0.0.1:18083;',
+    '真实路径 canary 只能默认监听本机 loopback 端口。',
+  );
+  requireIncludes(
+    content,
+    'access_log /var/log/nginx/genarrative-pingora-realpath-canary.access.log genarrative_upstream;',
+    '真实路径 canary 必须写独立 access log，避免和生产真实用户请求混淆。',
+  );
+  requireIncludes(
+    content,
+    `proxy_pass ${PINGORA_UPSTREAM}`,
+    '真实路径 canary 必须固定转发到本机 Pingora shadow 端口。',
+  );
+  requireNotMatches(
+    content,
+    /^\s*http\b/mu,
+    '真实路径 canary snippet 只能包含 server 片段，不能自行声明 http。',
+  );
+  requireNotMatches(
+    content,
+    /^\s*rewrite\b/mu,
+    '真实路径 canary 不允许 rewrite；Nginx 和 Pingora access log path 必须一一对齐。',
+  );
+  requireNotMatches(
+    content,
+    /^\s*listen\s+(?:80|443|0\.0\.0\.0|\[::\])/mu,
+    '真实路径 canary 默认不能监听公网地址或 80/443。',
+  );
+
+  const serverCount = [...content.matchAll(/^\s*server\s*\{/gmu)].length;
+  if (serverCount !== 1) {
+    fail(`${activeSnippetPath}: 预期只有 1 个 server，实际 ${serverCount} 个。`);
+  }
+  for (const directive of ['allow 127.0.0.1;', 'allow ::1;', 'deny all;']) {
+    requireIncludes(
+      content,
+      directive,
+      '真实路径 canary 默认必须只放行本机，避免误 include 后公开接流。',
+    );
+  }
+
+  const locationBlocks = extractLocationBlocks(content);
+  if (locationBlocks.size !== 7) {
+    fail(
+      `${activeSnippetPath}: 真实路径 canary 预期只有 7 个 location，实际 ${locationBlocks.size} 个。`,
+    );
+  }
+
+  const healthzHeader = `location = ${REALPATH_HEALTHZ_PATH}`;
+  const apiHeader = 'location = /api/creation-entry/config';
+  const websocketHeader = 'location ~ ^/v1/database/[^/]+/subscribe$';
+  const identityHeader = 'location ^~ /v1/identity';
+  const assetHeader = 'location = /assets/app.js';
+  const generatedHeader = 'location = /generated-pingora-canary-smoke';
+  const fallbackHeader = 'location /';
+  const healthz = requireLocation(locationBlocks, healthzHeader);
+  const api = requireLocation(locationBlocks, apiHeader);
+  const websocket = requireLocation(locationBlocks, websocketHeader);
+  const identity = requireLocation(locationBlocks, identityHeader);
+  const asset = requireLocation(locationBlocks, assetHeader);
+  const generated = requireLocation(locationBlocks, generatedHeader);
+  const fallback = requireLocation(locationBlocks, fallbackHeader);
+
+  for (const [header, block] of [
+    [healthzHeader, healthz],
+    [apiHeader, api],
+    [websocketHeader, websocket],
+    [identityHeader, identity],
+    [assetHeader, asset],
+    [generatedHeader, generated],
+  ]) {
+    requireLocationIncludes(
+      header,
+      block,
+      REALPATH_HANDOFF,
+      '每条真实路径 canary 路由都必须可通过响应头审计 handoff。',
+    );
+    requireLocationIncludes(
+      header,
+      block,
+      'proxy_set_header X-Request-Id $request_id;',
+      '真实路径 canary 访问需要沿用 Nginx request_id，便于和 Pingora access log 对照。',
+    );
+  }
+
+  requireLocationIncludes(
+    healthzHeader,
+    healthz,
+    `proxy_set_header X-Genarrative-Pingora-Probe "${PROBE_TOKEN_PLACEHOLDER}";`,
+    'healthz handoff 必须带 shadow probe token。',
+  );
+  requireLocationIncludes(
+    healthzHeader,
+    healthz,
+    `proxy_pass ${PINGORA_UPSTREAM}/__genarrative_pingora/healthz;`,
+    '真实路径 canary healthz 必须转到 Pingora 内部探针路径。',
+  );
+  requireLocationIncludes(
+    apiHeader,
+    api,
+    'proxy_buffering off;',
+    '代表性 API 真实路径 canary 必须保持低缓冲口径。',
+  );
+  requireLocationIncludes(
+    apiHeader,
+    api,
+    'add_header X-Accel-Buffering no always;',
+    '代表性 API 真实路径 canary 必须显式关闭加速缓冲。',
+  );
+  requireLocationIncludes(
+    apiHeader,
+    api,
+    'proxy_set_header X-Genarrative-Pingora-Canary "nginx-realpath";',
+    'Pingora access log 需要能识别来自 Nginx 真实路径 canary 的请求。',
+  );
+  for (const [header, block] of [
+    [websocketHeader, websocket],
+    [identityHeader, identity],
+  ]) {
+    requireLocationIncludes(
+      header,
+      block,
+      'proxy_set_header Upgrade $http_upgrade;',
+      'SpacetimeDB 真实路径 canary 必须保留 Upgrade 设置。',
+    );
+    requireLocationIncludes(
+      header,
+      block,
+      'proxy_set_header Connection "Upgrade";',
+      'SpacetimeDB 真实路径 canary 必须保留 Upgrade 连接语义。',
+    );
+  }
+  requireLocationIncludes(
+    websocketHeader,
+    websocket,
+    'proxy_read_timeout 3600s;',
+    'WebSocket 真实路径 canary 不能被短读超时提前断开。',
+  );
+  requireLocationIncludes(
+    fallbackHeader,
+    fallback,
+    'return 404;',
+    '真实路径 canary 只能覆盖代表路径，其余路径必须拒绝。',
+  );
+
+  if (countOccurrences(content, REALPATH_HANDOFF) !== 6) {
+    fail(
+      `${activeSnippetPath}: pingora-realpath-canary handoff 响应头必须在 6 个代理 location 中各出现一次。`,
+    );
+  }
+  if (countOccurrences(content, 'X-Genarrative-Pingora-Probe') !== 1) {
+    fail(`${activeSnippetPath}: probe token 只能出现在真实路径 healthz canary 路由。`);
+  }
+}
+
+function hasNginxBinary() {
+  try {
+    execFileSync(nginxBinary, ['-v'], { encoding: 'utf8', stdio: 'pipe' });
+    return true;
+  } catch (error) {
+    if (explicitNginxBinary || requireNginx) {
+      fail(
+        `[check:nginx-pingora-canary] 无法执行 ${nginxBinary}: ${error.message}`,
+      );
+    }
+    return false;
+  }
+}
+
+function runNginxSyntaxCheck(prefixContent, realpathContent) {
+  if (!hasNginxBinary()) {
+    console.log(
+      '[check:nginx-pingora-canary] 未找到 nginx，已完成静态检查；需要强制 nginx -t 时使用 --require-nginx。',
+    );
+    return;
+  }
+
+  const tempRoot = mkdtempSync(
+    path.join(tmpdir(), 'genarrative-nginx-canary-'),
+  );
+  try {
+    const renderedPrefixSnippetPath = path.join(
+      tempRoot,
+      'genarrative-pingora-canary.conf',
+    );
+    const renderedRealpathSnippetPath = path.join(
+      tempRoot,
+      'genarrative-pingora-realpath-canary.conf',
+    );
+    const nginxConfigPath = path.join(tempRoot, 'nginx.conf');
+    const renderedPrefixSnippet = prefixContent.replaceAll(
+      PROBE_TOKEN_PLACEHOLDER,
+      'local-nginx-canary-check-token',
+    );
+    const renderedRealpathSnippet = realpathContent
+      .replaceAll(PROBE_TOKEN_PLACEHOLDER, 'local-nginx-canary-check-token')
+      .replace(
+        '/var/log/nginx/genarrative-pingora-realpath-canary.access.log',
+        path.join(tempRoot, 'genarrative-pingora-realpath-canary.access.log'),
+      )
+      .replace(
+        '/var/log/nginx/genarrative-pingora-realpath-canary.error.log',
+        path.join(tempRoot, 'genarrative-pingora-realpath-canary.error.log'),
+      );
+    const nginxConfig = `
+pid ${tempRoot}/nginx.pid;
+error_log stderr notice;
+
+events {
+    worker_connections 64;
+}
+
+http {
+    log_format genarrative_upstream
+        '$remote_addr - $remote_user [$time_local] "$request" '
+        '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
+        'request_time=$request_time upstream_connect_time=$upstream_connect_time '
+        'upstream_header_time=$upstream_header_time upstream_response_time=$upstream_response_time '
+        'upstream_status=$upstream_status request_id=$request_id';
+    access_log ${tempRoot}/access.log genarrative_upstream;
+
+    server {
+        listen 127.0.0.1:18082;
+        server_name genarrative-pingora-canary-check.local;
+
+        include ${renderedPrefixSnippetPath};
+    }
+
+    include ${renderedRealpathSnippetPath};
+}
+`;
+
+    writeFileSync(renderedPrefixSnippetPath, renderedPrefixSnippet, 'utf8');
+    writeFileSync(renderedRealpathSnippetPath, renderedRealpathSnippet, 'utf8');
+    writeFileSync(nginxConfigPath, nginxConfig, 'utf8');
+
+    execFileSync(
+      nginxBinary,
+      ['-t', '-q', '-p', `${tempRoot}/`, '-c', nginxConfigPath],
+      { encoding: 'utf8', stdio: 'pipe' },
+    );
+    console.log('[check:nginx-pingora-canary] nginx -t OK');
+  } catch (error) {
+    const stderr = error.stderr ? `\n${error.stderr}` : '';
+    const stdout = error.stdout ? `\n${error.stdout}` : '';
+    fail(`[check:nginx-pingora-canary] nginx -t 失败。${stderr}${stdout}`);
+  } finally {
+    rmSync(tempRoot, { force: true, recursive: true });
+  }
+}
+
+const prefixSnippet = readFileSync(PREFIX_SNIPPET_PATH, 'utf8');
+activeSnippetPath = PREFIX_SNIPPET_PATH;
+runStaticChecks(prefixSnippet);
+
+const realpathSnippet = readFileSync(REALPATH_SNIPPET_PATH, 'utf8');
+activeSnippetPath = REALPATH_SNIPPET_PATH;
+runRealpathStaticChecks(realpathSnippet);
+
+if (failures.length === 0) {
+  runNginxSyntaxCheck(prefixSnippet, realpathSnippet);
+}
+
+if (failures.length > 0) {
+  console.error('[check:nginx-pingora-canary] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:nginx-pingora-canary] OK');
diff --git a/scripts/check-pingora-canary-access-log-parity-check.mjs b/scripts/check-pingora-canary-access-log-parity-check.mjs
new file mode 100644
index 000000000..fcad2d5fa
--- /dev/null
+++ b/scripts/check-pingora-canary-access-log-parity-check.mjs
@@ -0,0 +1,493 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const PARITY_SCRIPT = 'scripts/check-pingora-canary-access-log-parity.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-canary-log-parity-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-canary-access-log-parity] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-canary-access-log-parity] OK');
+
+function main() {
+  assertScriptShape();
+  assertParitySucceeds();
+  assertRealpathParitySucceeds();
+  assertMissingPingoraRecordFails();
+  assertStatusMismatchFails();
+  assertRequiredPathFails();
+  assertRejectsRelativeLogPaths();
+  assertRejectsFilesystemRootLogPaths();
+  assertRejectsLogPathControlCharacters();
+  assertRejectsPrefixAndPathControlCharacters();
+  assertRejectsParsedLogPathControlCharacters();
+  assertRejectsInvalidSinceLines();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(PARITY_SCRIPT, 'utf8');
+  assertIncludes(
+    content,
+    '该脚本只读比较 Nginx canary handoff access log 和 Pingora access log',
+    'canary access log parity 脚本 usage 必须说明只读边界。',
+  );
+  assertIncludes(
+    content,
+    'request_id',
+    'canary access log parity 必须按 request_id 对照。',
+  );
+  assertIncludes(
+    content,
+    'realpath',
+    'canary access log parity 必须支持真实路径 canary 对账模式。',
+  );
+  if (
+    content.includes('writeFile') ||
+    content.includes('rmSync(') ||
+    content.includes('nginx -s reload')
+  ) {
+    failures.push('canary access log parity 脚本不应写文件、删除文件或 reload Nginx。');
+  }
+}
+
+function assertParitySucceeds() {
+  const fixture = prepareFixture('ok');
+  writeLogs(fixture, [
+    nginxLine('rid-health', 'GET', '/__genarrative_pingora_canary/healthz', 200),
+    nginxLine(
+      'rid-api',
+      'GET',
+      '/__genarrative_pingora_canary/api/creation-entry/config',
+      200,
+    ),
+  ], [
+    pingoraLine('rid-health', 'GET', '/__genarrative_pingora/healthz', 200, {
+      route: 'shadow_probe',
+    }),
+    pingoraLine('rid-api', 'GET', '/api/creation-entry/config', 200, {
+      route: 'api_proxy',
+      proxyTarget: 'api-server',
+    }),
+  ]);
+
+  const result = runParity(fixture, [
+    '--path',
+    '/__genarrative_pingora_canary/healthz',
+    '--path',
+    '/__genarrative_pingora_canary/api/creation-entry/config',
+    '--json',
+  ]);
+  assertStatus(result, 0, '日志对照完整时必须通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const payload = parseJson(result.stdout, '日志对照 JSON 输出');
+  assertEqual(payload.summary.matchedCount, 2, '应匹配两条 canary 请求。');
+  assertEqual(payload.summary.missingCount, 0, '不应缺少 Pingora 对应日志。');
+}
+
+function assertRealpathParitySucceeds() {
+  const fixture = prepareFixture('realpath-ok');
+  writeLogs(fixture, [
+    nginxLine(
+      'rid-real-health',
+      'GET',
+      '/__genarrative_pingora_realpath_canary/healthz',
+      200,
+    ),
+    nginxLine('rid-real-api', 'GET', '/api/creation-entry/config', 200),
+    nginxLine('rid-real-asset', 'GET', '/assets/app.js', 200),
+  ], [
+    pingoraLine('rid-real-health', 'GET', '/__genarrative_pingora/healthz', 200, {
+      route: 'shadow_probe',
+    }),
+    pingoraLine('rid-real-api', 'GET', '/api/creation-entry/config', 200, {
+      route: 'api_proxy',
+      proxyTarget: 'api-server',
+    }),
+    pingoraLine('rid-real-asset', 'GET', '/assets/app.js', 200, {
+      route: 'static',
+    }),
+  ]);
+
+  const result = runParity(fixture, [
+    '--realpath',
+    '--path',
+    '/__genarrative_pingora_realpath_canary/healthz',
+    '--path',
+    '/api/creation-entry/config',
+    '--path',
+    '/assets/app.js',
+    '--json',
+  ]);
+  assertStatus(result, 0, '真实路径日志对照完整时必须通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const payload = parseJson(result.stdout, '真实路径日志对照 JSON 输出');
+  assertEqual(payload.mode, 'realpath', '真实路径对账 JSON 必须标记 realpath 模式。');
+  assertEqual(payload.summary.matchedCount, 3, '应匹配三条真实路径 canary 请求。');
+  assertEqual(payload.summary.missingCount, 0, '真实路径对账不应缺少 Pingora 对应日志。');
+}
+
+function assertMissingPingoraRecordFails() {
+  const fixture = prepareFixture('missing-pingora');
+  writeLogs(fixture, [
+    nginxLine('rid-missing', 'GET', '/__genarrative_pingora_canary/v1/identity', 200),
+  ], []);
+  const result = runParity(fixture);
+  assertStatus(result, 1, '缺少同 request_id Pingora 日志时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '缺少对应 Pingora access log',
+    '缺少 Pingora 日志时必须给出明确错误。',
+  );
+}
+
+function assertStatusMismatchFails() {
+  const fixture = prepareFixture('status-mismatch');
+  writeLogs(fixture, [
+    nginxLine('rid-status', 'GET', '/__genarrative_pingora_canary/api/test', 200),
+  ], [
+    pingoraLine('rid-status', 'GET', '/api/test', 503),
+  ]);
+  const result = runParity(fixture);
+  assertStatus(result, 1, 'Nginx/Pingora 状态码不一致时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'status 200 != 503',
+    '状态码不一致必须给出明确错误。',
+  );
+}
+
+function assertRequiredPathFails() {
+  const fixture = prepareFixture('missing-required-path');
+  writeLogs(fixture, [
+    nginxLine('rid-health', 'GET', '/__genarrative_pingora_canary/healthz', 200),
+  ], [
+    pingoraLine('rid-health', 'GET', '/__genarrative_pingora/healthz', 200),
+  ]);
+  const result = runParity(fixture, [
+    '--path',
+    '/__genarrative_pingora_canary/api/creation-entry/config',
+  ]);
+  assertStatus(result, 1, '必需路径未出现在 Nginx canary 日志时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'Nginx canary 日志缺少必需路径',
+    '必需路径缺失必须给出明确错误。',
+  );
+}
+
+function assertRejectsRelativeLogPaths() {
+  const fixture = prepareFixture('relative-path');
+  const result = spawnSync(
+    'node',
+    [
+      PARITY_SCRIPT,
+      '--nginx-log-file',
+      'nginx.log',
+      '--pingora-log-file',
+      fixture.pingoraLogFile,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('日志路径为相对路径时必须失败。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--nginx-log-file 必须是绝对路径',
+    '相对 Nginx 日志路径必须给出明确错误。',
+  );
+}
+
+function assertRejectsFilesystemRootLogPaths() {
+  const fixture = prepareFixture('filesystem-root-path');
+  const result = spawnSync(
+    'node',
+    [
+      PARITY_SCRIPT,
+      '--nginx-log-file',
+      '/',
+      '--pingora-log-file',
+      fixture.pingoraLogFile,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('日志路径指向文件系统根目录时必须失败。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--nginx-log-file 不能是文件系统根目录',
+    '文件系统根目录 Nginx 日志路径必须给出明确错误。',
+  );
+}
+
+function assertRejectsLogPathControlCharacters() {
+  const fixture = prepareFixture('log-path-control-character');
+  const result = spawnSync(
+    'node',
+    [
+      PARITY_SCRIPT,
+      '--nginx-log-file',
+      `${fixture.nginxLogFile}\nspoofed`,
+      '--pingora-log-file',
+      fixture.pingoraLogFile,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('日志路径包含换行时必须失败。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--nginx-log-file 不能包含换行或 NUL 字符',
+    '带控制字符的 Nginx 日志路径必须给出明确错误。',
+  );
+}
+
+function assertRejectsPrefixAndPathControlCharacters() {
+  const fixture = prepareFixture('prefix-path-control-character');
+  writeLogs(fixture, [
+    nginxLine('rid-health', 'GET', '/__genarrative_pingora_canary/healthz', 200),
+  ], [
+    pingoraLine('rid-health', 'GET', '/__genarrative_pingora/healthz', 200),
+  ]);
+
+  const prefixResult = runParity(fixture, [
+    '--prefix',
+    '/__genarrative_pingora_canary\nspoofed',
+  ]);
+  if ((prefixResult.status ?? 0) === 0) {
+    failures.push('canary prefix 包含换行时必须失败。');
+  }
+  assertIncludes(
+    `${prefixResult.stdout}\n${prefixResult.stderr}`,
+    '--prefix 不能包含换行或 NUL 字符',
+    '带控制字符的 canary prefix 必须给出明确错误。',
+  );
+
+  const pathResult = runParity(fixture, [
+    '--path',
+    '/__genarrative_pingora_canary/healthz\nspoofed',
+  ]);
+  if ((pathResult.status ?? 0) === 0) {
+    failures.push('必需 canary path 包含换行时必须失败。');
+  }
+  assertIncludes(
+    `${pathResult.stdout}\n${pathResult.stderr}`,
+    '--path 不能包含换行或 NUL 字符',
+    '带控制字符的必需路径必须给出明确错误。',
+  );
+}
+
+function assertRejectsParsedLogPathControlCharacters() {
+  const fixture = prepareFixture('parsed-log-path-control-character');
+  writeLogs(fixture, [
+    nginxLine('rid-health', 'GET', '/__genarrative_pingora_canary/healthz', 200),
+  ], [
+    pingoraLine('rid-health', 'GET', '/__genarrative_pingora/healthz%0Aspoofed', 200),
+  ]);
+
+  const result = runParity(fixture);
+  if ((result.status ?? 0) === 0) {
+    failures.push('Pingora 日志 path 解析后包含换行时必须失败。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'Pingora access log 第 1 行 path 不能包含换行或 NUL 字符',
+    '带控制字符的 Pingora 日志 path 必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidSinceLines() {
+  const fixture = prepareFixture('invalid-since-lines');
+  writeLogs(fixture, [
+    nginxLine('rid-health', 'GET', '/__genarrative_pingora_canary/healthz', 200),
+  ], [
+    pingoraLine('rid-health', 'GET', '/__genarrative_pingora/healthz', 200),
+  ]);
+
+  const cliResult = runParity(fixture, ['--since-lines', '0']);
+  if ((cliResult.status ?? 0) === 0) {
+    failures.push('非正数 --since-lines 必须失败。');
+  }
+  assertIncludes(
+    `${cliResult.stdout}\n${cliResult.stderr}`,
+    '--since-lines 必须是正整数',
+    '非法 --since-lines 必须给出明确错误。',
+  );
+
+  const controlResult = runParity(fixture, ['--since-lines', '10\nspoofed']);
+  if ((controlResult.status ?? 0) === 0) {
+    failures.push('带控制字符的 --since-lines 必须失败。');
+  }
+  assertIncludes(
+    `${controlResult.stdout}\n${controlResult.stderr}`,
+    '--since-lines 不能包含换行或 NUL 字符',
+    '带控制字符的 --since-lines 必须给出明确错误。',
+  );
+
+  const envResult = spawnSync(
+    'node',
+    [
+      PARITY_SCRIPT,
+      '--nginx-log-file',
+      fixture.nginxLogFile,
+      '--pingora-log-file',
+      fixture.pingoraLogFile,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES: 'abc',
+      },
+    },
+  );
+  if ((envResult.status ?? 0) === 0) {
+    failures.push('非法 env since-lines 必须失败。');
+  }
+  assertIncludes(
+    `${envResult.stdout}\n${envResult.stderr}`,
+    'GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES 必须是正整数',
+    '非法 env since-lines 必须给出明确错误。',
+  );
+}
+
+function prepareFixture(name) {
+  const root = path.join(tmpRoot, name);
+  mkdirSync(root, { recursive: true });
+  return {
+    root,
+    nginxLogFile: path.join(root, 'nginx.access.log'),
+    pingoraLogFile: path.join(root, 'pingora.access.log'),
+  };
+}
+
+function writeLogs(fixture, nginxLines, pingoraLines) {
+  writeFileSync(fixture.nginxLogFile, `${nginxLines.join('\n')}\n`, 'utf8');
+  writeFileSync(fixture.pingoraLogFile, `${pingoraLines.join('\n')}\n`, 'utf8');
+}
+
+function nginxLine(requestId, method, uri, status) {
+  return [
+    '127.0.0.1 - - [16/Jun/2026:02:00:00 +0800]',
+    `"${method} ${uri} HTTP/1.1"`,
+    `${status} 12 "-" "agent"`,
+    'request_time=0.001 upstream_connect_time=0.000',
+    'upstream_header_time=0.001 upstream_response_time=0.001',
+    `upstream_status=${status} request_id=${requestId}`,
+  ].join(' ');
+}
+
+function pingoraLine(
+  requestId,
+  method,
+  requestPath,
+  status,
+  options = {},
+) {
+  return [
+    `request_id=${requestId}`,
+    `method=${method}`,
+    `path=${requestPath}`,
+    `uri=${requestPath}`,
+    'host=example.com',
+    'client_ip=127.0.0.1',
+    `status=${status}`,
+    `route=${options.route || 'api_proxy'}`,
+    `proxy_target=${options.proxyTarget || '-'}`,
+    'upstream=127.0.0.1:8082',
+    'content_length=-',
+    'body_bytes_seen=0',
+    'protection_class=api',
+    'protection_client=127.0.0.1',
+    'elapsed_ms=2',
+    'error=-',
+  ].join('\t');
+}
+
+function runParity(fixture, args = []) {
+  return spawnSync(
+    'node',
+    [
+      PARITY_SCRIPT,
+      '--nginx-log-file',
+      fixture.nginxLogFile,
+      '--pingora-log-file',
+      fixture.pingoraLogFile,
+      ...args,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+}
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  if ((result.status ?? 0) !== expected) {
+    failures.push(
+      `${reason} 实际退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 实际 ${actual}，预期 ${expected}。`);
+  }
+}
+
+function assertIncludes(value, expected, reason) {
+  const haystack = Array.isArray(value) ? value.join('\n') : String(value);
+  if (!haystack.includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
diff --git a/scripts/check-pingora-canary-access-log-parity.mjs b/scripts/check-pingora-canary-access-log-parity.mjs
new file mode 100644
index 000000000..f2e4cc289
--- /dev/null
+++ b/scripts/check-pingora-canary-access-log-parity.mjs
@@ -0,0 +1,427 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_CANARY_PREFIX = '/__genarrative_pingora_canary';
+const REALPATH_HEALTHZ_PATH = '/__genarrative_pingora_realpath_canary/healthz';
+const SHADOW_HEALTHZ_PATH = '/__genarrative_pingora/healthz';
+
+const config = parseArgs(process.argv.slice(2));
+const failures = [];
+
+const nginxRecords = readLogRecords(config.nginxLogFile, parseNginxAccessLine);
+const pingoraRecords = readLogRecords(
+  config.pingoraLogFile,
+  parseKeyValueAccessLine,
+);
+const parity = buildParity(nginxRecords, pingoraRecords);
+
+if (config.json) {
+  console.log(`${JSON.stringify(parity, null, 2)}\n`);
+}
+
+if (failures.length > 0) {
+  console.error('[pingora-canary-access-log-parity] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+if (!config.json) {
+  console.log(
+    `[pingora-canary-access-log-parity] OK (${parity.summary.matchedCount}/${parity.summary.nginxCanaryCount} matched)`,
+  );
+}
+
+function parseArgs(argv) {
+  const result = {
+    nginxLogFile:
+      process.env.GENARRATIVE_PINGORA_CANARY_NGINX_ACCESS_LOG ||
+      '/var/log/nginx/genarrative.access.log',
+    pingoraLogFile:
+      process.env.GENARRATIVE_PINGORA_CANARY_PINGORA_ACCESS_LOG ||
+      '/var/log/genarrative/pingora-gateway.access.log',
+    prefix:
+      process.env.GENARRATIVE_PINGORA_CANARY_PREFIX || DEFAULT_CANARY_PREFIX,
+    mode: normalizeMode(
+      process.env.GENARRATIVE_PINGORA_CANARY_MODE || 'prefix',
+      'GENARRATIVE_PINGORA_CANARY_MODE',
+    ),
+    sinceLines: parseOptionalPositiveInt(
+      process.env.GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES,
+      2000,
+      'GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES',
+    ),
+    requiredPaths: [],
+    json: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        usage();
+        process.exit(0);
+        break;
+      case '--nginx-log-file':
+        result.nginxLogFile = requireValue(argv, ++index, arg);
+        break;
+      case '--pingora-log-file':
+        result.pingoraLogFile = requireValue(argv, ++index, arg);
+        break;
+      case '--prefix':
+        result.prefix = normalizePrefix(requireValue(argv, ++index, arg), arg);
+        break;
+      case '--mode':
+        result.mode = normalizeMode(requireValue(argv, ++index, arg), arg);
+        break;
+      case '--realpath':
+        result.mode = 'realpath';
+        break;
+      case '--since-lines':
+        result.sinceLines = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          '--since-lines',
+        );
+        break;
+      case '--path':
+        result.requiredPaths.push(
+          normalizeRequestPath(requireValue(argv, ++index, arg), arg),
+        );
+        break;
+      case '--json':
+        result.json = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  result.prefix = normalizePrefix(result.prefix, '--prefix');
+  for (const [label, file] of [
+    ['--nginx-log-file', result.nginxLogFile],
+    ['--pingora-log-file', result.pingoraLogFile],
+  ]) {
+    validateSafeAbsoluteFilePath(file, label);
+  }
+  return result;
+}
+
+function usage() {
+  console.log(`Usage:
+  node scripts/check-pingora-canary-access-log-parity.mjs [options]
+
+Options:
+  --nginx-log-file <path>    Nginx access log，默认 /var/log/nginx/genarrative.access.log。
+  --pingora-log-file <path>  Pingora access log，默认 /var/log/genarrative/pingora-gateway.access.log。
+  --prefix <path>            canary 前缀，默认 /__genarrative_pingora_canary。
+  --mode <prefix|realpath>   对账模式，默认 prefix；realpath 要求 Nginx path 与 Pingora path 对齐。
+  --realpath                 Shortcut for --mode realpath。
+  --since-lines <count>      只读取日志尾部行数，默认 2000。
+  --path <path>              必须出现并完成对照的原始 canary 路径，可重复。
+  --json                     输出 JSON。
+
+该脚本只读比较 Nginx canary handoff access log 和 Pingora access log，不修改日志、不 reload Nginx 或 Pingora。
+Nginx canary exact healthz 会转发到 Pingora shadow healthz，其余前缀路径按 rewrite 后路径对照。
+真实路径 canary 使用独立 Nginx access log；除 realpath healthz 探针外，Nginx 与 Pingora path 必须一致。
+`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function parseOptionalPositiveInt(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parseRequiredPositiveInt(raw, label);
+}
+
+function parseRequiredPositiveInt(raw, label) {
+  const rawText = String(raw ?? '');
+  validateNoControlCharacters(rawText, label);
+  const text = rawText.trim();
+  if (!/^[1-9]\d*$/.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  return Number.parseInt(text, 10);
+}
+
+function normalizeMode(raw, label) {
+  validateNoControlCharacters(raw, label);
+  const value = String(raw || '').trim();
+  if (!value || value === 'prefix') {
+    return 'prefix';
+  }
+  if (value === 'realpath') {
+    return 'realpath';
+  }
+  throw new Error(`${label} 必须是 prefix 或 realpath。`);
+}
+
+function validateSafeAbsoluteFilePath(value, flag) {
+  validateNoControlCharacters(value, flag);
+  if (!path.isAbsolute(value)) {
+    throw new Error(`${flag} 必须是绝对路径。`);
+  }
+  if (isFilesystemRootPath(value)) {
+    throw new Error(`${flag} 不能是文件系统根目录。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function normalizePrefix(prefix, label) {
+  validateNoControlCharacters(prefix, label);
+  if (!prefix || prefix === '/') {
+    return DEFAULT_CANARY_PREFIX;
+  }
+  const withLeadingSlash = prefix.startsWith('/') ? prefix : `/${prefix}`;
+  return withLeadingSlash.endsWith('/')
+    ? withLeadingSlash.slice(0, -1)
+    : withLeadingSlash;
+}
+
+function normalizeRequestPath(value, label = '--path') {
+  validateNoControlCharacters(value, label);
+  const raw = String(value || '').trim();
+  if (!raw) {
+    return '/';
+  }
+  const pathOnly = raw.includes('://') ? new URL(raw).pathname : raw.split('?')[0];
+  return pathOnly.startsWith('/') ? pathOnly : `/${pathOnly}`;
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value ?? ''))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function readLogRecords(filePath, parser) {
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf8');
+  } catch (error) {
+    failures.push(`无法读取日志文件 ${filePath}: ${error.message}`);
+    return [];
+  }
+  return text
+    .split(/\r?\n/u)
+    .filter(Boolean)
+    .slice(-config.sinceLines)
+    .map((line, index) => parseLogRecord(parser, line, index + 1, filePath))
+    .filter(Boolean);
+}
+
+function parseLogRecord(parser, line, lineNumber, filePath) {
+  try {
+    return parser(line, lineNumber);
+  } catch (error) {
+    failures.push(
+      `日志文件 ${filePath} 第 ${lineNumber} 行解析失败: ${error.message}`,
+    );
+    return null;
+  }
+}
+
+function parseNginxAccessLine(line, lineNumber) {
+  const requestMatch = line.match(/"([A-Z]+)\s+([^"\s]+)\s+HTTP\/[^"]+"/u);
+  const statusMatch = line.match(/"\s+(\d{3})\s+/u);
+  const requestIdMatch = line.match(/(?:^|\s)request_id=([^\s]+)/u);
+  if (!requestMatch || !statusMatch || !requestIdMatch) {
+    return null;
+  }
+  const uri = requestMatch[2];
+  return {
+    source: 'nginx',
+    lineNumber,
+    requestId: requestIdMatch[1],
+    method: requestMatch[1],
+    uri,
+    path: normalizeRequestPath(uri, `Nginx access log 第 ${lineNumber} 行 URI`),
+    status: Number.parseInt(statusMatch[1], 10),
+    raw: line,
+  };
+}
+
+function parseKeyValueAccessLine(line, lineNumber) {
+  const fields = {};
+  for (const part of line.split(/\t/u)) {
+    const separator = part.indexOf('=');
+    if (separator <= 0) {
+      continue;
+    }
+    fields[part.slice(0, separator)] = unescapeAccessLogValue(
+      part.slice(separator + 1),
+    );
+  }
+  if (!fields.request_id || !fields.path || !fields.status) {
+    return null;
+  }
+  return {
+    source: 'pingora',
+    lineNumber,
+    requestId: fields.request_id,
+    method: fields.method || '',
+    uri: fields.uri || fields.path,
+    path: normalizeRequestPath(
+      fields.path,
+      `Pingora access log 第 ${lineNumber} 行 path`,
+    ),
+    status: Number.parseInt(fields.status, 10),
+    route: fields.route || '',
+    proxyTarget: fields.proxy_target || '',
+    upstream: fields.upstream || '',
+    raw: line,
+  };
+}
+
+function unescapeAccessLogValue(value) {
+  return String(value)
+    .replaceAll('%09', '\t')
+    .replaceAll('%0A', '\n')
+    .replaceAll('%0D', '\r');
+}
+
+function buildParity(nginxRecords, pingoraRecords) {
+  const pingoraByRequestId = new Map();
+  for (const record of pingoraRecords) {
+    if (!pingoraByRequestId.has(record.requestId)) {
+      pingoraByRequestId.set(record.requestId, []);
+    }
+    pingoraByRequestId.get(record.requestId).push(record);
+  }
+
+  const nginxCanary = nginxRecords.filter((record) => isCanaryRecord(record));
+  if (nginxCanary.length === 0) {
+    failures.push(noCanaryRecordsMessage());
+  }
+
+  const matches = [];
+  const missing = [];
+  const mismatches = [];
+  const seenCanaryPaths = new Set();
+
+  for (const nginxRecord of nginxCanary) {
+    seenCanaryPaths.add(nginxRecord.path);
+    const expectedPath = stripCanaryPrefix(nginxRecord.path);
+    const candidates = pingoraByRequestId.get(nginxRecord.requestId) || [];
+    const match = candidates.find((record) => record.path === expectedPath);
+    if (!match) {
+      missing.push({
+        requestId: nginxRecord.requestId,
+        nginxPath: nginxRecord.path,
+        expectedPingoraPath: expectedPath,
+      });
+      continue;
+    }
+    const mismatch = {
+      requestId: nginxRecord.requestId,
+      nginxPath: nginxRecord.path,
+      pingoraPath: match.path,
+      problems: [],
+    };
+    if (nginxRecord.method && match.method && nginxRecord.method !== match.method) {
+      mismatch.problems.push(`method ${nginxRecord.method} != ${match.method}`);
+    }
+    if (nginxRecord.status !== match.status) {
+      mismatch.problems.push(`status ${nginxRecord.status} != ${match.status}`);
+    }
+    if (mismatch.problems.length > 0) {
+      mismatches.push(mismatch);
+      continue;
+    }
+    matches.push({
+      requestId: nginxRecord.requestId,
+      nginxPath: nginxRecord.path,
+      pingoraPath: match.path,
+      status: nginxRecord.status,
+      route: match.route,
+      proxyTarget: match.proxyTarget,
+    });
+  }
+
+  for (const requiredPath of config.requiredPaths) {
+    if (!seenCanaryPaths.has(requiredPath)) {
+      failures.push(`Nginx canary 日志缺少必需路径: ${requiredPath}`);
+    }
+  }
+  for (const item of missing) {
+    failures.push(
+      `缺少对应 Pingora access log: request_id=${item.requestId} nginx_path=${item.nginxPath} expected_pingora_path=${item.expectedPingoraPath}`,
+    );
+  }
+  for (const item of mismatches) {
+    failures.push(
+      `Nginx/Pingora access log 不一致: request_id=${item.requestId} nginx_path=${item.nginxPath} pingora_path=${item.pingoraPath} ${item.problems.join(', ')}`,
+    );
+  }
+
+  return {
+    ok: failures.length === 0,
+    mode: config.mode,
+    prefix: config.prefix,
+    summary: {
+      nginxCanaryCount: nginxCanary.length,
+      pingoraCount: pingoraRecords.length,
+      matchedCount: matches.length,
+      missingCount: missing.length,
+      mismatchCount: mismatches.length,
+    },
+    matches,
+    missing,
+    mismatches,
+  };
+}
+
+function isCanaryRecord(record) {
+  if (config.mode === 'realpath') {
+    return (
+      record.path === REALPATH_HEALTHZ_PATH ||
+      record.path === '/api/creation-entry/config' ||
+      record.path.startsWith('/v1/database/') ||
+      record.path.startsWith('/v1/identity') ||
+      record.path === '/assets/app.js' ||
+      record.path === '/generated-pingora-canary-smoke'
+    );
+  }
+  return (
+    record.path.startsWith(`${config.prefix}/`) || record.path === config.prefix
+  );
+}
+
+function noCanaryRecordsMessage() {
+  if (config.mode === 'realpath') {
+    return `Nginx 日志尾部 ${config.sinceLines} 行中没有真实路径 canary 请求`;
+  }
+  return `Nginx 日志尾部 ${config.sinceLines} 行中没有 canary 前缀请求: ${config.prefix}`;
+}
+
+function stripCanaryPrefix(canaryPath) {
+  if (config.mode === 'realpath') {
+    if (canaryPath === REALPATH_HEALTHZ_PATH) {
+      return SHADOW_HEALTHZ_PATH;
+    }
+    return canaryPath;
+  }
+  if (canaryPath === `${config.prefix}/healthz`) {
+    return SHADOW_HEALTHZ_PATH;
+  }
+  if (canaryPath === config.prefix) {
+    return '/';
+  }
+  const stripped = canaryPath.slice(config.prefix.length);
+  return stripped || '/';
+}
diff --git a/scripts/check-pingora-canary-docker.mjs b/scripts/check-pingora-canary-docker.mjs
new file mode 100644
index 000000000..e7bcae174
--- /dev/null
+++ b/scripts/check-pingora-canary-docker.mjs
@@ -0,0 +1,1116 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+const SNIPPET_PATH = 'deploy/nginx/snippets/genarrative-pingora-canary.conf';
+const REALPATH_SNIPPET_PATH =
+  'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf';
+const PROBE_TOKEN_PLACEHOLDER = '__GENARRATIVE_PINGORA_PROBE_TOKEN__';
+const REALPATH_CANARY_ACCESS_LOG =
+  '/var/log/nginx/genarrative-pingora-realpath-canary.access.log';
+const REALPATH_LISTEN = 'listen 127.0.0.1:18083;';
+const DEFAULT_IMAGE = 'nginx:1.27-alpine';
+
+const repoRoot = process.cwd();
+const failures = [];
+const childProcesses = [];
+const containers = [];
+const servers = [];
+const sockets = new Set();
+const tempDirs = [];
+let skipped = false;
+
+const config = parseArgs(process.argv.slice(2));
+
+try {
+  await main();
+} catch (error) {
+  failures.push(error instanceof Error ? error.message : String(error));
+} finally {
+  await cleanup();
+}
+
+if (failures.length > 0) {
+  console.error('\n[pingora-canary-docker] 未通过：');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log(
+  skipped ? '\n[pingora-canary-docker] 跳过' : '\n[pingora-canary-docker] 通过',
+);
+
+async function main() {
+  if (!ensureDockerReady()) {
+    return;
+  }
+  if (!ensureDockerImage()) {
+    return;
+  }
+
+  const tempRoot = await mkdtemp(
+    path.join(os.tmpdir(), 'genarrative-pingora-canary-docker-'),
+  );
+  tempDirs.push(tempRoot);
+
+  const webRoot = path.join(tempRoot, 'web');
+  const acmeRoot = path.join(tempRoot, 'acme');
+  const logsRoot = path.join(tempRoot, 'logs');
+  const nginxAccessLogFile = path.join(logsRoot, 'nginx.access.log');
+  const realpathNginxAccessLogFile = path.join(
+    logsRoot,
+    'nginx.realpath.access.log',
+  );
+  const accessLogFile = path.join(logsRoot, 'pingora.access.log');
+  await mkdir(logsRoot, { recursive: true });
+  await chmod(logsRoot, 0o777);
+
+  const gatewayWebRoot = config.webRoot || webRoot;
+  const gatewayAcmeRoot = config.acmeRoot || acmeRoot;
+  if (!config.webRoot) {
+    await prepareStaticWebRoot(webRoot);
+  }
+  if (!config.acmeRoot) {
+    await prepareAcmeRoot(acmeRoot);
+  }
+
+  const realUpstreams = config.realUpstreams || config.apiUpstream || config.spacetimeUpstream;
+  if (realUpstreams && (!config.apiUpstream || !config.spacetimeUpstream)) {
+    throw new Error(
+      '真实上游模式必须同时提供 --api-upstream 与 --spacetime-upstream。',
+    );
+  }
+
+  const api = realUpstreams
+    ? { upstream: config.apiUpstream, state: null }
+    : await startApiMock();
+  const spacetime = realUpstreams
+    ? { upstream: config.spacetimeUpstream, state: null }
+    : await startSpacetimeMock();
+  if (realUpstreams) {
+    console.log(
+      `[pingora-canary-docker] 使用真实上游 api=${api.upstream} spacetime=${spacetime.upstream} webRoot=${gatewayWebRoot}`,
+    );
+    await assertRealUpstreamsReady(api.upstream, spacetime.upstream);
+  }
+  const pingoraPort = await getFreePort();
+  const nginxPort = await getFreePort();
+  const realpathNginxPort = await getFreePort();
+  const probeToken = `docker-${randomBytes(12).toString('hex')}`;
+
+  if (!config.skipBuild) {
+    runCommand('cargo', [
+      'build',
+      '-p',
+      'pingora-gateway',
+      '--manifest-path',
+      'server-rs/Cargo.toml',
+    ]);
+  }
+
+  const gatewayBinary = resolveGatewayBinary();
+  const gateway = spawn(gatewayBinary, [], {
+    cwd: repoRoot,
+    env: {
+      ...smokeEnv(),
+      GENARRATIVE_PINGORA_GATEWAY_LISTEN: `0.0.0.0:${pingoraPort}`,
+      GENARRATIVE_PINGORA_GATEWAY_API_UPSTREAM: api.upstream,
+      GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM: spacetime.upstream,
+      GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT: gatewayWebRoot,
+      GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT: gatewayAcmeRoot,
+      GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE: path.join(
+        tempRoot,
+        'maintenance',
+        'enabled',
+      ),
+      GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE: accessLogFile,
+      GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN: probeToken,
+      GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO: 'https',
+      GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES: '1048576',
+      GENARRATIVE_PINGORA_GATEWAY_API_MAX_CONCURRENT: '16',
+      GENARRATIVE_PINGORA_GATEWAY_API_RATE_PER_SECOND: '100',
+      GENARRATIVE_PINGORA_GATEWAY_API_BURST: '100',
+      GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_MAX_CONCURRENT: '16',
+      GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_RATE_PER_SECOND: '100',
+      GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_BURST: '100',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_MAX_CONCURRENT: '16',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_RATE_PER_SECOND: '100',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_BURST: '100',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_MAX_CONCURRENT: '16',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_RATE_PER_SECOND: '100',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_BURST: '100',
+      GENARRATIVE_PINGORA_GATEWAY_SPACETIME_MAX_CONCURRENT: '16',
+      GENARRATIVE_PINGORA_GATEWAY_SPACETIME_RATE_PER_SECOND: '100',
+      GENARRATIVE_PINGORA_GATEWAY_SPACETIME_BURST: '100',
+      GENARRATIVE_PINGORA_GATEWAY_LOG: config.verbose
+        ? 'info,pingora=info,pingora_gateway=info'
+        : 'warn,pingora=warn,pingora_gateway=warn',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  childProcesses.push({ child: gateway, name: 'pingora-gateway' });
+  collectProcessLogs(gateway, 'pingora-gateway');
+
+  await waitForHttp(`http://127.0.0.1:${pingoraPort}/`, 200, {
+    label: '等待 Pingora 网关就绪',
+  });
+
+  const renderedSnippetPath = path.join(
+    tempRoot,
+    'genarrative-pingora-canary.conf',
+  );
+  const nginxConfigPath = path.join(tempRoot, 'nginx.conf');
+  await renderNginxConfig({
+    renderedSnippetPath,
+    nginxConfigPath,
+    nginxAccessLogFile,
+    realpathNginxAccessLogFile,
+    pingoraPort,
+    nginxPort,
+    realpathNginxPort,
+    probeToken,
+  });
+
+  const containerName = `genarrative-pingora-canary-${process.pid}-${randomBytes(4).toString('hex')}`;
+  containers.push(containerName);
+  const docker = spawn(
+    'docker',
+    [
+      'run',
+      '--rm',
+      '--name',
+      containerName,
+      '--network',
+      'host',
+      '-v',
+      `${tempRoot}:${tempRoot}`,
+      config.image,
+      'nginx',
+      '-c',
+      nginxConfigPath,
+      '-g',
+      'daemon off;',
+    ],
+    {
+      cwd: repoRoot,
+      env: smokeEnv(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+  childProcesses.push({ child: docker, name: 'docker-nginx' });
+  collectProcessLogs(docker, 'docker-nginx');
+
+  const baseUrl = `http://127.0.0.1:${nginxPort}`;
+  const realpathBaseUrl = `http://127.0.0.1:${realpathNginxPort}`;
+  await waitForHttp(`${baseUrl}/__genarrative_pingora_canary/healthz`, 200, {
+    headers: { Host: 'example.test' },
+    label: '等待 Docker Nginx canary 就绪',
+    validate: (response) =>
+      response.headers['x-genarrative-nginx-handoff'] === 'pingora-canary' &&
+      response.body.includes('"gateway":"pingora-shadow"'),
+  });
+  await waitForHttp(
+    `${realpathBaseUrl}/__genarrative_pingora_realpath_canary/healthz`,
+    200,
+    {
+      headers: { Host: 'example.test' },
+      label: '等待 Docker Nginx realpath canary 就绪',
+      validate: (response) =>
+        response.headers['x-genarrative-nginx-handoff'] ===
+          'pingora-realpath-canary' &&
+        response.body.includes('"gateway":"pingora-shadow"'),
+    },
+  );
+
+  await runCommandAsync(process.execPath, [
+    'scripts/check-pingora-canary-live.mjs',
+    '--base-url',
+    baseUrl,
+    '--host',
+    'example.test',
+    '--timeout-ms',
+    '5000',
+  ]);
+  await runCommandAsync(process.execPath, [
+    'scripts/check-pingora-canary-live.mjs',
+    '--realpath',
+    '--base-url',
+    realpathBaseUrl,
+    '--host',
+    'example.test',
+    '--timeout-ms',
+    '5000',
+  ]);
+
+  await expectAccessLogContains(nginxAccessLogFile, [
+    '/__genarrative_pingora_canary/healthz',
+    '/__genarrative_pingora_canary/api/creation-entry/config',
+    '/__genarrative_pingora_canary/v1/identity',
+    '/__genarrative_pingora_canary/assets/app.js',
+  ]);
+  await expectAccessLogContains(realpathNginxAccessLogFile, [
+    '/__genarrative_pingora_realpath_canary/healthz',
+    '/api/creation-entry/config',
+    '/v1/identity',
+    '/assets/app.js',
+  ]);
+  await expectAccessLogContains(accessLogFile, [
+    'path=/__genarrative_pingora/healthz',
+    'path=/api/creation-entry/config',
+    'path=/v1/identity',
+    'path=/assets/app.js',
+  ]);
+
+  await runCommandAsync(process.execPath, [
+    'scripts/check-pingora-canary-access-log-parity.mjs',
+    '--nginx-log-file',
+    nginxAccessLogFile,
+    '--pingora-log-file',
+    accessLogFile,
+    '--since-lines',
+    '2000',
+    '--path',
+    '/__genarrative_pingora_canary/healthz',
+    '--path',
+    '/__genarrative_pingora_canary/api/creation-entry/config',
+    '--path',
+    '/__genarrative_pingora_canary/v1/identity',
+    '--path',
+    '/__genarrative_pingora_canary/assets/app.js',
+  ]);
+  await runCommandAsync(process.execPath, [
+    'scripts/check-pingora-canary-access-log-parity.mjs',
+    '--realpath',
+    '--nginx-log-file',
+    realpathNginxAccessLogFile,
+    '--pingora-log-file',
+    accessLogFile,
+    '--since-lines',
+    '2000',
+    '--path',
+    '/__genarrative_pingora_realpath_canary/healthz',
+    '--path',
+    '/api/creation-entry/config',
+    '--path',
+    '/v1/identity',
+    '--path',
+    '/assets/app.js',
+  ]);
+
+  if (!realUpstreams) {
+    ensure(
+      api.state.requests.some(
+        (request) => request.url === '/api/creation-entry/config',
+      ),
+      'Docker Nginx canary 未把 API 代表路径交给 mock api-server',
+    );
+    ensure(
+      spacetime.state.requests.some((request) => request.url === '/v1/identity'),
+      'Docker Nginx canary 未把 SpacetimeDB identity 代表路径交给 mock SpacetimeDB',
+    );
+    ensure(
+      api.state.requests.filter(
+        (request) => request.url === '/api/creation-entry/config',
+      ).length >= 2,
+      'Docker Nginx realpath canary 未把真实 API 代表路径交给 mock api-server',
+    );
+    ensure(
+      spacetime.state.requests.filter((request) => request.url === '/v1/identity')
+        .length >= 2,
+      'Docker Nginx realpath canary 未把真实 SpacetimeDB identity 路径交给 mock SpacetimeDB',
+    );
+  }
+}
+
+function parseArgs(argv) {
+  const result = {
+    image: process.env.GENARRATIVE_PINGORA_CANARY_DOCKER_IMAGE || DEFAULT_IMAGE,
+    pull: false,
+    requireDocker: false,
+    skipBuild: false,
+    verbose: false,
+    realUpstreams: false,
+    apiUpstream: normalizeOptionalHostPort(
+      process.env.GENARRATIVE_PINGORA_CANARY_REAL_API_UPSTREAM,
+      'GENARRATIVE_PINGORA_CANARY_REAL_API_UPSTREAM',
+    ),
+    spacetimeUpstream: normalizeOptionalHostPort(
+      process.env.GENARRATIVE_PINGORA_CANARY_REAL_SPACETIME_UPSTREAM,
+      'GENARRATIVE_PINGORA_CANARY_REAL_SPACETIME_UPSTREAM',
+    ),
+    webRoot: normalizeOptionalDirectory(
+      process.env.GENARRATIVE_PINGORA_CANARY_REAL_WEB_ROOT,
+      'GENARRATIVE_PINGORA_CANARY_REAL_WEB_ROOT',
+    ),
+    acmeRoot: normalizeOptionalDirectory(
+      process.env.GENARRATIVE_PINGORA_CANARY_REAL_ACME_ROOT,
+      'GENARRATIVE_PINGORA_CANARY_REAL_ACME_ROOT',
+    ),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        console.log(`Usage:
+  node scripts/check-pingora-canary-docker.mjs [options]
+
+Options:
+  --image <image>       Nginx image, default ${DEFAULT_IMAGE}.
+  --pull                Pull the image when it is not present locally.
+  --require-docker      Treat missing Docker/image/host-network as failure instead of skip.
+  --skip-build          Reuse an existing pingora-gateway debug binary.
+  --real-upstreams      Require real api-server and SpacetimeDB upstream arguments.
+  --api-upstream <host:port>
+                        Use a real api-server upstream instead of the built-in mock.
+  --spacetime-upstream <host:port>
+                        Use a real SpacetimeDB upstream instead of the built-in mock.
+  --web-root <path>     Serve an existing web root, for example dist/.
+  --acme-root <path>    Serve an existing ACME root; temp root is used by default.
+  --verbose             Print Pingora and Docker Nginx process logs.
+
+Environment aliases:
+  GENARRATIVE_PINGORA_CANARY_DOCKER_IMAGE
+  GENARRATIVE_PINGORA_CANARY_REAL_API_UPSTREAM
+  GENARRATIVE_PINGORA_CANARY_REAL_SPACETIME_UPSTREAM
+  GENARRATIVE_PINGORA_CANARY_REAL_WEB_ROOT
+  GENARRATIVE_PINGORA_CANARY_REAL_ACME_ROOT
+  GENARRATIVE_PINGORA_GATEWAY_BINARY
+
+默认不会拉取镜像；本机或 CI 要做强验收时建议：
+  node scripts/check-pingora-canary-docker.mjs --require-docker --pull
+`);
+        process.exit(0);
+        break;
+      case '--image':
+        result.image = requireValue(argv, ++index, arg);
+        break;
+      case '--pull':
+        result.pull = true;
+        break;
+      case '--require-docker':
+        result.requireDocker = true;
+        break;
+      case '--skip-build':
+        result.skipBuild = true;
+        break;
+      case '--real-upstreams':
+        result.realUpstreams = true;
+        break;
+      case '--api-upstream':
+        result.apiUpstream = normalizeHostPort(requireValue(argv, ++index, arg), arg);
+        break;
+      case '--spacetime-upstream':
+        result.spacetimeUpstream = normalizeHostPort(
+          requireValue(argv, ++index, arg),
+          arg,
+        );
+        break;
+      case '--web-root':
+        result.webRoot = normalizeDirectory(requireValue(argv, ++index, arg), arg);
+        break;
+      case '--acme-root':
+        result.acmeRoot = normalizeDirectory(requireValue(argv, ++index, arg), arg);
+        break;
+      case '--verbose':
+        result.verbose = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  return result;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function normalizeOptionalHostPort(value, label) {
+  if (!value) {
+    return '';
+  }
+  return normalizeHostPort(value, label);
+}
+
+function normalizeHostPort(value, label) {
+  validateNoControlCharacters(value, label);
+  const raw = String(value || '').trim();
+  if (!raw) {
+    throw new Error(`${label} 不能为空。`);
+  }
+  if (raw.includes('://') || /[\s/?#@]/u.test(raw)) {
+    throw new Error(`${label} 必须是 host:port，不能包含 scheme、路径、查询、片段或空白字符。`);
+  }
+  try {
+    const parsed = new URL(`http://${raw}`);
+    const port = Number.parseInt(parsed.port, 10);
+    if (!parsed.hostname || !Number.isInteger(port) || port <= 0 || port > 65535) {
+      throw new Error('invalid host:port');
+    }
+  } catch {
+    throw new Error(`${label} 必须是合法 host:port。`);
+  }
+  return raw;
+}
+
+function normalizeOptionalDirectory(value, label) {
+  if (!value) {
+    return '';
+  }
+  return normalizeDirectory(value, label);
+}
+
+function normalizeDirectory(value, label) {
+  validateNoControlCharacters(value, label);
+  const resolved = path.resolve(repoRoot, String(value || '').trim());
+  if (!existsSync(resolved)) {
+    throw new Error(`${label} 不存在：${resolved}`);
+  }
+  return resolved;
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value ?? ''))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function ensureDockerReady() {
+  const result = spawnSync(
+    'docker',
+    ['version', '--format', '{{.Server.Version}}'],
+    {
+      cwd: repoRoot,
+      env: smokeEnv(),
+      encoding: 'utf8',
+      shell: false,
+      stdio: 'pipe',
+    },
+  );
+
+  if (result.status === 0) {
+    console.log(
+      `[pingora-canary-docker] Docker daemon ${result.stdout.trim() || 'ready'}`,
+    );
+    return true;
+  }
+
+  return skipOrFail(
+    `Docker daemon 不可用；需要强制验证时先启动 Docker。${formatSpawnFailure(result)}`,
+  );
+}
+
+function ensureDockerImage() {
+  const inspect = spawnSync('docker', ['image', 'inspect', config.image], {
+    cwd: repoRoot,
+    env: smokeEnv(),
+    encoding: 'utf8',
+    shell: false,
+    stdio: 'pipe',
+  });
+
+  if (inspect.status === 0) {
+    return true;
+  }
+
+  if (!config.pull) {
+    return skipOrFail(
+      `本机没有 ${config.image} 镜像；可追加 --pull 拉取，或预先 docker pull ${config.image}。`,
+    );
+  }
+
+  runCommand('docker', ['pull', config.image]);
+  return true;
+}
+
+function skipOrFail(message) {
+  if (config.requireDocker) {
+    failures.push(message);
+  } else {
+    skipped = true;
+    console.log(`[pingora-canary-docker] SKIP: ${message}`);
+  }
+  return false;
+}
+
+async function prepareStaticWebRoot(webRoot) {
+  await mkdir(path.join(webRoot, 'admin', 'assets'), { recursive: true });
+  await mkdir(path.join(webRoot, 'assets'), { recursive: true });
+
+  await writeFile(path.join(webRoot, 'index.html'), '<main>site-shell</main>');
+  await writeFile(
+    path.join(webRoot, 'admin', 'index.html'),
+    '<main>admin-shell</main>',
+  );
+  await writeFile(
+    path.join(webRoot, 'assets', 'app.js'),
+    'console.log("site asset");',
+  );
+  await writeFile(
+    path.join(webRoot, 'admin', 'assets', 'admin.js'),
+    'console.log("admin asset");',
+  );
+}
+
+async function prepareAcmeRoot(acmeRoot) {
+  await mkdir(path.join(acmeRoot, '.well-known', 'acme-challenge'), {
+    recursive: true,
+  });
+  await writeFile(
+    path.join(acmeRoot, '.well-known', 'acme-challenge', 'token'),
+    'acme-token',
+  );
+}
+
+async function startApiMock() {
+  const state = {
+    requests: [],
+  };
+  const server = net.createServer((socket) => {
+    sockets.add(socket);
+    socket.on('close', () => {
+      sockets.delete(socket);
+    });
+    if (config.verbose) {
+      console.log('[api-mock] connection');
+    }
+
+    let raw = Buffer.alloc(0);
+    socket.on('data', (chunk) => {
+      raw = Buffer.concat([raw, chunk]);
+      const headerEnd = raw.indexOf('\r\n\r\n');
+      if (headerEnd < 0 || socket.writableEnded) {
+        return;
+      }
+
+      const request = parseRawHttpRequest(raw.slice(0, headerEnd + 4));
+      if (config.verbose) {
+        console.log(
+          `[api-mock] ${request.method} ${request.url} headers=${JSON.stringify(request.headers)}`,
+        );
+      }
+      state.requests.push(request);
+      const body = JSON.stringify({
+        ok: true,
+        upstream: 'api',
+        method: request.method,
+        url: request.url,
+        host: request.headers.host || '',
+      });
+      socket.end(
+        [
+          'HTTP/1.1 200 OK',
+          'Content-Type: application/json; charset=utf-8',
+          'X-Upstream: api',
+          `Content-Length: ${Buffer.byteLength(body)}`,
+          'Connection: close',
+          '',
+          body,
+        ].join('\r\n'),
+      );
+    });
+  });
+
+  const port = await listen(server);
+  return { upstream: `127.0.0.1:${port}`, state };
+}
+
+async function startSpacetimeMock() {
+  const state = {
+    requests: [],
+  };
+  const server = net.createServer((socket) => {
+    sockets.add(socket);
+    socket.on('close', () => {
+      sockets.delete(socket);
+    });
+    let raw = Buffer.alloc(0);
+    socket.on('data', (chunk) => {
+      raw = Buffer.concat([raw, chunk]);
+      const headerEnd = raw.indexOf('\r\n\r\n');
+      if (headerEnd < 0 || socket.writableEnded) {
+        return;
+      }
+
+      const request = parseRawHttpRequest(raw.slice(0, headerEnd + 4));
+      state.requests.push(request);
+      const body = JSON.stringify({
+        ok: true,
+        upstream: 'spacetime',
+        url: request.url,
+      });
+      socket.end(
+        [
+          'HTTP/1.1 200 OK',
+          'Content-Type: application/json; charset=utf-8',
+          `Content-Length: ${Buffer.byteLength(body)}`,
+          'Connection: close',
+          '',
+          body,
+        ].join('\r\n'),
+      );
+    });
+  });
+
+  const port = await listen(server);
+  return { upstream: `127.0.0.1:${port}`, state };
+}
+
+async function assertRealUpstreamsReady(apiUpstream, spacetimeUpstream) {
+  await waitForHttp(`http://${apiUpstream}/healthz`, 200, {
+    label: '等待真实 api-server 就绪',
+  });
+  await waitForHttp(`http://${spacetimeUpstream}/v1/ping`, 200, {
+    label: '等待真实 SpacetimeDB 就绪',
+  });
+}
+
+async function renderNginxConfig({
+  renderedSnippetPath,
+  nginxConfigPath,
+  nginxAccessLogFile,
+  realpathNginxAccessLogFile,
+  pingoraPort,
+  nginxPort,
+  realpathNginxPort,
+  probeToken,
+}) {
+  const snippet = await readFile(SNIPPET_PATH, 'utf8');
+  const renderedSnippet = snippet
+    .replaceAll(PROBE_TOKEN_PLACEHOLDER, probeToken)
+    .replaceAll('http://127.0.0.1:18081', `http://127.0.0.1:${pingoraPort}`);
+  const renderedRealpathSnippetPath = path.join(
+    path.dirname(renderedSnippetPath),
+    'genarrative-pingora-realpath-canary.conf',
+  );
+  const realpathSnippet = await readFile(REALPATH_SNIPPET_PATH, 'utf8');
+  const renderedRealpathSnippet = realpathSnippet
+    .replaceAll(PROBE_TOKEN_PLACEHOLDER, probeToken)
+    .replaceAll('http://127.0.0.1:18081', `http://127.0.0.1:${pingoraPort}`)
+    .replace(REALPATH_LISTEN, `listen 127.0.0.1:${realpathNginxPort};`)
+    .replace(REALPATH_CANARY_ACCESS_LOG, realpathNginxAccessLogFile);
+  const nginxConfig = `
+pid /tmp/genarrative-pingora-canary-docker.pid;
+error_log stderr notice;
+
+events {
+    worker_connections 128;
+}
+
+http {
+    log_format genarrative_upstream
+        '$remote_addr - $remote_user [$time_local] "$request" '
+        '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
+        'request_time=$request_time upstream_connect_time=$upstream_connect_time '
+        'upstream_header_time=$upstream_header_time upstream_response_time=$upstream_response_time '
+        'upstream_status=$upstream_status request_id=$request_id';
+
+    server {
+        listen 127.0.0.1:${nginxPort};
+        server_name example.test;
+        access_log ${nginxAccessLogFile} genarrative_upstream;
+
+        include ${renderedSnippetPath};
+    }
+
+    include ${renderedRealpathSnippetPath};
+}
+`;
+
+  await writeFile(renderedSnippetPath, renderedSnippet, 'utf8');
+  await writeFile(renderedRealpathSnippetPath, renderedRealpathSnippet, 'utf8');
+  await writeFile(nginxConfigPath, nginxConfig, 'utf8');
+}
+
+async function expectAccessLogContains(accessLogFile, needles) {
+  await waitForCondition(async () => {
+    try {
+      const content = await readFile(accessLogFile, 'utf8');
+      return needles.every((needle) => content.includes(needle));
+    } catch {
+      return false;
+    }
+  }, 5000);
+}
+
+function requestHttp(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const socket = net.connect(
+      { host: target.hostname, port: Number(target.port) },
+      () => {
+        const headers = {
+          Host: target.host,
+          Connection: 'close',
+          ...(options.headers || {}),
+        };
+        const headerLines = Object.entries(headers).map(
+          ([name, value]) => `${name}: ${value}`,
+        );
+        socket.write(
+          [
+            `${options.method || 'GET'} ${target.pathname}${target.search} HTTP/1.1`,
+            ...headerLines,
+            '',
+            '',
+          ].join('\r\n'),
+        );
+      },
+    );
+    let raw = Buffer.alloc(0);
+    const timeout = setTimeout(() => {
+      socket.destroy(new Error(`HTTP 请求超时：${url}`));
+    }, options.timeoutMs || 5000);
+    socket.on('data', (chunk) => {
+      raw = Buffer.concat([raw, chunk]);
+      const response = tryParseRawHttpResponse(raw);
+      if (response) {
+        clearTimeout(timeout);
+        socket.destroy();
+        resolve(response);
+      }
+    });
+    socket.on('error', reject);
+    socket.on('close', () => {
+      clearTimeout(timeout);
+      const response = tryParseRawHttpResponse(raw, { final: true });
+      if (response) {
+        resolve(response);
+      }
+    });
+  });
+}
+
+function parseRawHttpRequest(raw) {
+  const text = raw.toString('latin1');
+  const [requestLine, ...headerLines] = text.trimEnd().split('\r\n');
+  const [method = '', url = ''] = requestLine.split(' ');
+  const headers = {};
+  for (const line of headerLines) {
+    const separator = line.indexOf(':');
+    if (separator <= 0) {
+      continue;
+    }
+    headers[line.slice(0, separator).trim().toLowerCase()] = line
+      .slice(separator + 1)
+      .trim();
+  }
+  return { method, url, headers };
+}
+
+function tryParseRawHttpResponse(raw, options = {}) {
+  const headerEnd = raw.indexOf('\r\n\r\n');
+  if (headerEnd < 0) {
+    return null;
+  }
+
+  const headerText = raw.slice(0, headerEnd).toString('latin1');
+  const [statusLine, ...headerLines] = headerText.split('\r\n');
+  const status = Number.parseInt(statusLine.split(' ')[1] || '0', 10);
+  const headers = {};
+  for (const line of headerLines) {
+    const separator = line.indexOf(':');
+    if (separator <= 0) {
+      continue;
+    }
+    headers[line.slice(0, separator).trim().toLowerCase()] = line
+      .slice(separator + 1)
+      .trim();
+  }
+
+  const bodyStart = headerEnd + 4;
+  const body = raw.slice(bodyStart);
+  const contentLength = Number.parseInt(headers['content-length'] || '', 10);
+  if (Number.isFinite(contentLength)) {
+    if (body.length < contentLength) {
+      return null;
+    }
+    return {
+      status: status,
+      headers,
+      body: body.slice(0, contentLength).toString('utf8'),
+    };
+  }
+
+  if (!options.final) {
+    return null;
+  }
+  return {
+    status,
+    headers,
+    body: body.toString('utf8'),
+  };
+}
+
+function listen(server) {
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.on('connection', (socket) => {
+      sockets.add(socket);
+      socket.on('close', () => {
+        sockets.delete(socket);
+      });
+    });
+    server.listen(0, '127.0.0.1', () => {
+      servers.push(server);
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        reject(new Error('无法读取 mock server 端口'));
+        return;
+      }
+      resolve(address.port);
+    });
+  });
+}
+
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        server.close();
+        reject(new Error('无法分配临时端口'));
+        return;
+      }
+      const { port } = address;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+async function waitForHttp(url, expectedStatus, options = {}) {
+  let lastError = '';
+  await waitForCondition(async () => {
+    try {
+      const response = await requestHttp(url, {
+        headers: options.headers,
+        timeoutMs: 2000,
+      });
+      if (
+        response.status === expectedStatus &&
+        (!options.validate || options.validate(response))
+      ) {
+        return true;
+      }
+      lastError = `HTTP ${response.status}`;
+      return false;
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      return false;
+    }
+  }, 15000).catch(() => {
+    throw new Error(`${options.label || '等待 HTTP 就绪'}超时：${lastError}`);
+  });
+}
+
+function runCommand(command, args) {
+  console.log(`[pingora-canary-docker] ${command} ${args.join(' ')}`);
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    env: smokeEnv(),
+    shell: false,
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    throw new Error(`${command} 启动失败：${result.error.message}`);
+  }
+  if (result.signal) {
+    throw new Error(`${command} 被信号终止：${result.signal}`);
+  }
+  if ((result.status ?? 0) !== 0) {
+    throw new Error(`${command} ${args.join(' ')} 退出码 ${result.status}`);
+  }
+}
+
+function runCommandAsync(command, args) {
+  console.log(`[pingora-canary-docker] ${command} ${args.join(' ')}`);
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: repoRoot,
+      env: smokeEnv(),
+      shell: false,
+      stdio: 'inherit',
+    });
+    child.on('error', (error) => {
+      reject(new Error(`${command} 启动失败：${error.message}`));
+    });
+    child.on('exit', (status, signal) => {
+      if (signal) {
+        reject(new Error(`${command} 被信号终止：${signal}`));
+        return;
+      }
+      if ((status ?? 0) !== 0) {
+        reject(new Error(`${command} ${args.join(' ')} 退出码 ${status}`));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function resolveGatewayBinary() {
+  const explicit = process.env.GENARRATIVE_PINGORA_GATEWAY_BINARY;
+  if (explicit) {
+    return explicit;
+  }
+
+  const candidates = [
+    path.join(repoRoot, 'server-rs', 'target', 'debug', 'pingora-gateway'),
+    path.join(repoRoot, 'target', 'debug', 'pingora-gateway'),
+  ];
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (!found) {
+    throw new Error(
+      `未找到 pingora-gateway debug 二进制，请先构建或设置 GENARRATIVE_PINGORA_GATEWAY_BINARY。候选：${candidates.join(', ')}`,
+    );
+  }
+  return found;
+}
+
+function smokeEnv() {
+  return {
+    ...process.env,
+    PATH: `${path.join(os.homedir(), '.local', 'bin')}:${process.env.PATH || ''}`,
+  };
+}
+
+function collectProcessLogs(child, name) {
+  child.stdout?.on('data', (chunk) => {
+    if (config.verbose) {
+      process.stdout.write(`[${name}] ${chunk}`);
+    }
+  });
+  child.stderr?.on('data', (chunk) => {
+    if (config.verbose) {
+      process.stderr.write(`[${name}] ${chunk}`);
+    }
+  });
+}
+
+function formatSpawnFailure(result) {
+  const chunks = [];
+  if (result.error) {
+    chunks.push(result.error.message);
+  }
+  if (result.stderr) {
+    chunks.push(result.stderr.trim());
+  }
+  if (result.stdout) {
+    chunks.push(result.stdout.trim());
+  }
+  return chunks.length > 0 ? ` ${chunks.join(' ')}` : '';
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForCondition(predicate, timeoutMs = 2000) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (await predicate()) {
+      return;
+    }
+    await delay(50);
+  }
+  throw new Error('等待 smoke 条件达成超时');
+}
+
+function ensure(condition, message) {
+  if (!condition) {
+    failures.push(message);
+  }
+}
+
+async function cleanup() {
+  for (const container of containers.reverse()) {
+    spawnSync('docker', ['rm', '-f', container], {
+      cwd: repoRoot,
+      env: smokeEnv(),
+      encoding: 'utf8',
+      shell: false,
+      stdio: config.verbose ? 'inherit' : 'pipe',
+    });
+  }
+
+  for (const { child, name } of childProcesses.reverse()) {
+    await stopChild(child, name);
+  }
+
+  for (const socket of sockets) {
+    socket.destroy();
+  }
+  sockets.clear();
+
+  await Promise.all(
+    servers.reverse().map(
+      (server) =>
+        new Promise((resolve) => {
+          const timer = setTimeout(resolve, 1000);
+          server.close(() => {
+            clearTimeout(timer);
+            resolve();
+          });
+        }),
+    ),
+  );
+
+  await Promise.all(
+    tempDirs.reverse().map((dir) => rm(dir, { recursive: true, force: true })),
+  );
+}
+
+async function stopChild(child, name) {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+
+  child.kill('SIGTERM');
+  const exited = await waitForExit(child, 3000);
+  if (!exited) {
+    child.kill('SIGKILL');
+    const killed = await waitForExit(child, 3000);
+    if (!killed) {
+      failures.push(`${name} 未能退出`);
+    }
+  }
+}
+
+function waitForExit(child, timeoutMs) {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve(true);
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      child.off('exit', onExit);
+      resolve(false);
+    }, timeoutMs);
+
+    function onExit() {
+      clearTimeout(timer);
+      resolve(true);
+    }
+
+    child.once('exit', onExit);
+  });
+}
diff --git a/scripts/check-pingora-canary-live-guard.mjs b/scripts/check-pingora-canary-live-guard.mjs
new file mode 100644
index 000000000..16247989b
--- /dev/null
+++ b/scripts/check-pingora-canary-live-guard.mjs
@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+
+const CANARY_LIVE_SCRIPT = 'scripts/check-pingora-canary-live.mjs';
+const failures = [];
+
+main();
+
+if (failures.length > 0) {
+  console.error('[check:pingora-canary-live-guard] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-canary-live-guard] OK');
+
+function main() {
+  assertRejectsControlCharacter('--base-url', [
+    '--base-url',
+    'http://127.0.0.1\n--fake-flag',
+  ]);
+  assertRejectsControlCharacter('--prefix', [
+    '--base-url',
+    'http://127.0.0.1',
+    '--prefix',
+    '/__genarrative_pingora_canary\nX-Injected: yes',
+  ]);
+  assertRejectsControlCharacter('--host', [
+    '--base-url',
+    'http://127.0.0.1',
+    '--host',
+    'example.com\nX-Injected: yes',
+  ]);
+  assertRejectsControlCharacter('--path', [
+    '--base-url',
+    'http://127.0.0.1',
+    '--path',
+    '/api/creation-entry/config\nX-Injected: yes',
+  ]);
+  assertRejectsControlCharacter('--timeout-ms', [
+    '--base-url',
+    'http://127.0.0.1',
+    '--timeout-ms',
+    '5000\n1',
+  ]);
+}
+
+function assertRejectsControlCharacter(label, args) {
+  const result = spawnSync('node', [CANARY_LIVE_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: process.env,
+  });
+  if ((result.status ?? 0) === 0) {
+    failures.push(`${label} 带控制字符时必须在发起 canary 请求前失败。`);
+    return;
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    `${label} 不能包含换行或 NUL 字符`,
+    `${label} 带控制字符时必须给出明确错误。`,
+  );
+}
+
+function assertIncludes(value, expected, reason) {
+  if (!String(value).includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
diff --git a/scripts/check-pingora-canary-live.mjs b/scripts/check-pingora-canary-live.mjs
new file mode 100644
index 000000000..0527a32d0
--- /dev/null
+++ b/scripts/check-pingora-canary-live.mjs
@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+
+import http from 'node:http';
+import https from 'node:https';
+
+const DEFAULT_CANARY_PREFIX = '/__genarrative_pingora_canary';
+const REALPATH_HEALTHZ_PATH = '/__genarrative_pingora_realpath_canary/healthz';
+const HANDOFF_HEADER_DISPLAY = 'X-Genarrative-Nginx-Handoff';
+const HANDOFF_HEADER = 'x-genarrative-nginx-handoff';
+const HANDOFF_VALUES = {
+  prefix: 'pingora-canary',
+  realpath: 'pingora-realpath-canary',
+};
+
+const failures = [];
+let config;
+
+try {
+  config = parseArgs(process.argv.slice(2));
+  await main();
+} catch (error) {
+  failures.push(error instanceof Error ? error.message : String(error));
+}
+
+if (failures.length > 0) {
+  console.error('[pingora-canary-live] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[pingora-canary-live] OK');
+
+function usage() {
+  console.log(`Usage:
+  node scripts/check-pingora-canary-live.mjs --base-url <url> [options]
+
+Options:
+  --base-url <url>        Nginx/public base URL with canary snippet enabled.
+  --prefix <path>         Canary prefix, default /__genarrative_pingora_canary.
+  --mode <prefix|realpath>
+                           Canary mode, default prefix.
+  --realpath              Shortcut for --mode realpath.
+  --host <host>           Optional Host header for local --resolve style checks.
+  --path <path>           Extra canary path to probe; repeatable.
+  --timeout-ms <ms>       Request timeout, default 5000.
+  --json                  Print JSON result.
+
+Environment aliases:
+  GENARRATIVE_PINGORA_CANARY_BASE_URL
+  GENARRATIVE_PINGORA_CANARY_PREFIX
+  GENARRATIVE_PINGORA_CANARY_MODE
+  GENARRATIVE_PINGORA_CANARY_HOST
+  GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS
+`);
+}
+
+function parseArgs(argv) {
+  const result = {
+    baseUrl: process.env.GENARRATIVE_PINGORA_CANARY_BASE_URL || '',
+    prefix:
+      process.env.GENARRATIVE_PINGORA_CANARY_PREFIX || DEFAULT_CANARY_PREFIX,
+    mode: normalizeMode(
+      process.env.GENARRATIVE_PINGORA_CANARY_MODE || 'prefix',
+      'GENARRATIVE_PINGORA_CANARY_MODE',
+    ),
+    host: process.env.GENARRATIVE_PINGORA_CANARY_HOST || '',
+    timeoutMs: parseOptionalPositiveInt(
+      process.env.GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS,
+      5000,
+      'GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS',
+    ),
+    json: false,
+    extraPaths: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        usage();
+        process.exit(0);
+        break;
+      case '--base-url':
+        result.baseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--prefix':
+        result.prefix = normalizePrefix(requireValue(argv, ++index, arg));
+        break;
+      case '--mode':
+        result.mode = normalizeMode(requireValue(argv, ++index, arg), arg);
+        break;
+      case '--realpath':
+        result.mode = 'realpath';
+        break;
+      case '--host':
+        result.host = requireValue(argv, ++index, arg);
+        break;
+      case '--path':
+        result.extraPaths.push(requireValue(argv, ++index, arg));
+        break;
+      case '--timeout-ms':
+        result.timeoutMs = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          '--timeout-ms',
+        );
+        break;
+      case '--json':
+        result.json = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  result.prefix = normalizePrefix(result.prefix);
+  if (!result.baseUrl) {
+    throw new Error('缺少 --base-url 或 GENARRATIVE_PINGORA_CANARY_BASE_URL');
+  }
+  validateNoControlCharacters(result.baseUrl, '--base-url');
+  new URL(result.baseUrl);
+  validateNoControlCharacters(result.prefix, '--prefix');
+  if (result.host) {
+    validateHostOption(result.host, '--host');
+  }
+  for (const extraPath of result.extraPaths) {
+    validateNoControlCharacters(extraPath, '--path');
+  }
+
+  return result;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function validateHostOption(value, flag) {
+  const raw = String(value);
+  validateNoControlCharacters(raw, flag);
+  if (raw !== raw.trim() || raw.includes('://') || /[\s/?#@]/.test(raw)) {
+    throw new Error(
+      `${flag} 只能是 host 或 host:port，不能包含 scheme、路径、查询、片段或空白字符`,
+    );
+  }
+  try {
+    const parsed = new URL(`https://${raw}`);
+    if (
+      !parsed.hostname ||
+      parsed.pathname !== '/' ||
+      parsed.search ||
+      parsed.hash ||
+      parsed.username ||
+      parsed.password
+    ) {
+      throw new Error('invalid host');
+    }
+  } catch {
+    throw new Error(`${flag} 不是合法的 host 或 host:port`);
+  }
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function parseOptionalPositiveInt(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parseRequiredPositiveInt(raw, label);
+}
+
+function parseRequiredPositiveInt(raw, label) {
+  validateNoControlCharacters(raw, label);
+  const text = String(raw ?? '').trim();
+  if (!/^[1-9]\d*$/.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  return Number.parseInt(text, 10);
+}
+
+function normalizeMode(raw, label) {
+  validateNoControlCharacters(raw, label);
+  const value = String(raw || '').trim();
+  if (!value || value === 'prefix') {
+    return 'prefix';
+  }
+  if (value === 'realpath') {
+    return 'realpath';
+  }
+  throw new Error(`${label} 必须是 prefix 或 realpath。`);
+}
+
+function normalizePrefix(prefix) {
+  if (!prefix || prefix === '/') {
+    return DEFAULT_CANARY_PREFIX;
+  }
+  const withLeadingSlash = prefix.startsWith('/') ? prefix : `/${prefix}`;
+  return withLeadingSlash.endsWith('/')
+    ? withLeadingSlash.slice(0, -1)
+    : withLeadingSlash;
+}
+
+function joinUrl(baseUrl, path) {
+  const base = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+  const suffix = path.startsWith('/') ? path : `/${path}`;
+  return `${base}${suffix}`;
+}
+
+function canaryUrl(path) {
+  const suffix = path.startsWith('/') ? path : `/${path}`;
+  if (config.mode === 'realpath') {
+    return joinUrl(config.baseUrl, suffix);
+  }
+  return joinUrl(config.baseUrl, `${config.prefix}${suffix}`);
+}
+
+async function main() {
+  const handoffValue = HANDOFF_VALUES[config.mode];
+  const checks = [
+    {
+      name: 'healthz',
+      path:
+        config.mode === 'realpath' ? REALPATH_HEALTHZ_PATH : '/healthz',
+      expectedStatus: 200,
+      assertBody: (body) => body.includes('"gateway":"pingora-shadow"'),
+      bodyReason: 'body 应包含 gateway=pingora-shadow',
+    },
+    {
+      name: 'api-config',
+      path: '/api/creation-entry/config',
+      expectedStatuses: [200, 401, 403, 503],
+    },
+    {
+      name: 'spacetime-identity',
+      path: '/v1/identity',
+      expectedStatuses: [200, 401, 403, 404, 405, 503],
+    },
+    {
+      name: 'web-assets',
+      path: '/assets/app.js',
+      expectedStatuses: [200, 404, 503],
+    },
+    {
+      name: 'generated-forbidden',
+      path: '/generated-pingora-canary-smoke',
+      expectedStatus: 404,
+    },
+  ];
+
+  for (const path of config.extraPaths) {
+    checks.push({
+      name: `extra:${path}`,
+      path,
+      expectedStatuses: [200, 204, 301, 302, 304, 401, 403, 404, 503],
+    });
+  }
+
+  const results = [];
+  for (const check of checks) {
+    const result = await runCheck(check, handoffValue);
+    results.push(result);
+  }
+
+  if (config.json) {
+    console.log(
+      JSON.stringify({ ok: failures.length === 0, results }, null, 2),
+    );
+  }
+}
+
+async function runCheck(check, handoffValue) {
+  const url = canaryUrl(check.path);
+  const response = await requestUrl(url);
+  const expectedStatuses =
+    check.expectedStatuses ?? [check.expectedStatus].filter(Boolean);
+  const handoff = response.headers[HANDOFF_HEADER] || '';
+
+  if (!expectedStatuses.includes(response.statusCode)) {
+    failures.push(
+      `${check.name}: ${url} 返回 ${response.statusCode}，预期 ${expectedStatuses.join('/')}`,
+    );
+  }
+  if (handoff !== handoffValue) {
+    failures.push(
+      `${check.name}: 缺少 ${HANDOFF_HEADER_DISPLAY}: ${handoffValue}，实际 ${handoff || '-'}`,
+    );
+  }
+  if (check.assertBody && !check.assertBody(response.body)) {
+    failures.push(`${check.name}: ${check.bodyReason}`);
+  }
+
+  console.log(
+    `[pingora-canary-live] ${check.name} ${response.statusCode} ${response.elapsedMs}ms`,
+  );
+  return {
+    name: check.name,
+    mode: config.mode,
+    url,
+    statusCode: response.statusCode,
+    elapsedMs: response.elapsedMs,
+    handoff,
+  };
+}
+
+function requestUrl(url) {
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const parsed = new URL(url);
+    const client = parsed.protocol === 'https:' ? https : http;
+    const headers = {
+      'User-Agent': 'genarrative-pingora-canary-live/1.0',
+      Accept: 'application/json,text/plain,*/*',
+      Connection: 'close',
+    };
+    if (config.host) {
+      headers.Host = config.host;
+    }
+
+    const request = client.request(
+      parsed,
+      {
+        method: 'GET',
+        timeout: config.timeoutMs,
+        headers,
+      },
+      (response) => {
+        let body = '';
+        response.setEncoding('utf8');
+        response.on('data', (chunk) => {
+          if (body.length < 4096) {
+            body += chunk;
+          }
+        });
+        response.on('end', () => {
+          resolve({
+            elapsedMs: Date.now() - startedAt,
+            statusCode: response.statusCode || 0,
+            headers: response.headers,
+            body,
+          });
+        });
+      },
+    );
+
+    request.on('timeout', () => {
+      request.destroy(new Error(`请求超时: ${url}`));
+    });
+    request.on('error', reject);
+    request.end();
+  });
+}
diff --git a/scripts/check-pingora-current-release-audit.mjs b/scripts/check-pingora-current-release-audit.mjs
new file mode 100644
index 000000000..dd87e6220
--- /dev/null
+++ b/scripts/check-pingora-current-release-audit.mjs
@@ -0,0 +1,694 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  symlinkSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const AUDIT_SCRIPT = 'scripts/ops/pingora-current-release-audit.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-current-release-audit-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-current-release-audit] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-current-release-audit] OK');
+
+function main() {
+  assertScriptShape();
+  assertCompleteReleasePasses();
+  assertChecksumMismatchFails();
+  assertRequirePingoraGatewayFailsWhenChecksumMissing();
+  assertManifestMustRegisterIncludedPingoraGateway();
+  assertMissingCutoverScriptFails();
+  assertRequirePingoraGatewayFailsWhenMissing();
+  assertIncludedPingoraGatewayMustBeExecutable();
+  assertSystemdShowRequiresCurrentReleaseExecStart();
+  assertSystemdShowAcceptsCurrentSymlinkExecStart();
+  assertRejectsRelativeReleaseRoot();
+  assertRejectsFilesystemRootReleaseRoot();
+  assertRejectsPathArgsWithControlCharacters();
+  assertRejectsInvalidTimeout();
+  assertRejectsInvalidBoolEnv();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(AUDIT_SCRIPT, 'utf8');
+  assertIncludes(
+    content,
+    '该脚本只读检查 current release 自包含能力',
+    'current release 自审脚本 usage 必须说明只读边界。',
+  );
+  assertIncludes(
+    content,
+    'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    'current release 自审必须检查切换证据包脚本。',
+  );
+  assertIncludes(
+    content,
+    'scripts/deploy/pingora-tls-cert-sync.mjs',
+    'current release 自审必须检查 TLS 证书同步脚本。',
+  );
+  assertIncludes(
+    content,
+    'scripts/ops/pingora-current-release-audit.mjs',
+    'current release 自审必须检查自身已随包发布。',
+  );
+  assertIncludes(
+    content,
+    'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    'current release 自审必须检查直连彩排状态脚本已随包发布。',
+  );
+  assertIncludes(
+    content,
+    'scripts/check-pingora-release-readiness.mjs',
+    'current release 自审必须检查 release readiness 聚合门禁脚本。',
+  );
+  assertIncludes(
+    content,
+    'scripts/check-pingora-canary-live.mjs',
+    'current release 自审必须检查 canary live smoke 脚本。',
+  );
+  assertIncludes(
+    content,
+    'scripts/check-pingora-canary-access-log-parity.mjs',
+    'current release 自审必须检查 canary access log 对账脚本。',
+  );
+  if (
+    content.includes('writeFile') ||
+    content.includes('rmSync(') ||
+    content.includes('systemctl reload') ||
+    content.includes('daemon-reload')
+  ) {
+    failures.push('current release 自审脚本不应写文件、删除文件或 reload systemd。');
+  }
+}
+
+function assertCompleteReleasePasses() {
+  const fixture = prepareFixture('complete-release');
+  const result = runAudit(fixture, ['--require-pingora-gateway']);
+
+  assertStatus(result, 0, '完整 current release 自审应通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const payload = parseJson(result.stdout, '完整 release 自审输出');
+  assertEqual(payload.summary.status, 'OK', '完整 release summary 应为 OK。');
+  assertEqual(
+    payload.pingoraGateway.included,
+    true,
+    '完整 release 应识别已包含 pingora-gateway。',
+  );
+  assertEqual(
+    payload.pingoraGateway.executable,
+    true,
+    '完整 release 应识别 pingora-gateway 可执行。',
+  );
+  const pingoraChecksum = payload.checksums.find(
+    (checksum) => checksum.path === 'pingora-gateway',
+  );
+  if (!pingoraChecksum || pingoraChecksum.matches !== true) {
+    failures.push('完整 release 自审必须确认 pingora-gateway checksum 匹配。');
+  }
+  assertEqual(
+    payload.releaseManifest.status,
+    'OK',
+    '完整 release manifest 自审应通过。',
+  );
+  if (
+    !payload.releaseManifest.artifacts?.some(
+      (artifact) => artifact.path === 'pingora-gateway',
+    )
+  ) {
+    failures.push('完整 release manifest 必须登记 pingora-gateway。');
+  }
+  const bundleArtifact = payload.artifacts.find(
+    (artifact) =>
+      artifact.path === 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+  );
+  if (!bundleArtifact || bundleArtifact.status !== 'OK') {
+    failures.push('完整 release 自审必须确认切换证据包脚本存在。');
+  }
+  const canaryLogParityArtifact = payload.artifacts.find(
+    (artifact) =>
+      artifact.path === 'scripts/check-pingora-canary-access-log-parity.mjs',
+  );
+  if (!canaryLogParityArtifact || canaryLogParityArtifact.status !== 'OK') {
+    failures.push('完整 release 自审必须确认 canary access log 对账脚本存在。');
+  }
+  const canaryLiveArtifact = payload.artifacts.find(
+    (artifact) => artifact.path === 'scripts/check-pingora-canary-live.mjs',
+  );
+  if (!canaryLiveArtifact || canaryLiveArtifact.status !== 'OK') {
+    failures.push('完整 release 自审必须确认 canary live smoke 脚本存在。');
+  }
+  const tlsCertSyncArtifact = payload.artifacts.find(
+    (artifact) => artifact.path === 'scripts/deploy/pingora-tls-cert-sync.mjs',
+  );
+  if (!tlsCertSyncArtifact || tlsCertSyncArtifact.status !== 'OK') {
+    failures.push('完整 release 自审必须确认 TLS 证书同步脚本存在且可执行。');
+  }
+}
+
+function assertChecksumMismatchFails() {
+  const fixture = prepareFixture('checksum-mismatch');
+  writeFileSync(
+    path.join(fixture.releaseRoot, 'pingora-gateway.sha256'),
+    `${'0'.repeat(64)}  pingora-gateway\n`,
+    'utf8',
+  );
+  const result = runAudit(fixture, ['--require-pingora-gateway']);
+
+  assertStatus(result, 1, 'pingora-gateway checksum 不匹配时自审必须失败。');
+  const payload = parseJson(result.stdout, 'checksum 不匹配自审输出');
+  const checksum = payload.checksums?.find(
+    (item) => item.path === 'pingora-gateway',
+  );
+  if (!checksum || checksum.status !== 'CRITICAL') {
+    failures.push('checksum 不匹配时 pingora-gateway checksum 必须标记 CRITICAL。');
+  }
+}
+
+function assertRequirePingoraGatewayFailsWhenChecksumMissing() {
+  const fixture = prepareFixture('missing-gateway-checksum');
+  rmSync(path.join(fixture.releaseRoot, 'pingora-gateway.sha256'));
+  const result = runAudit(fixture, ['--require-pingora-gateway']);
+
+  assertStatus(result, 1, '要求 Pingora 但 checksum 缺失时自审必须失败。');
+  const payload = parseJson(result.stdout, '缺少 Pingora checksum 自审输出');
+  const checksum = payload.checksums?.find(
+    (item) => item.path === 'pingora-gateway',
+  );
+  if (!checksum || checksum.status !== 'CRITICAL') {
+    failures.push('缺少 Pingora checksum 时必须标记 CRITICAL。');
+  }
+}
+
+function assertManifestMustRegisterIncludedPingoraGateway() {
+  const fixture = prepareFixture('manifest-missing-gateway', {
+    includePingoraInManifest: false,
+  });
+  const result = runAudit(fixture, ['--require-pingora-gateway']);
+
+  assertStatus(result, 1, 'manifest 未登记 Pingora 时自审必须失败。');
+  const payload = parseJson(result.stdout, 'manifest 缺少 Pingora 自审输出');
+  assertEqual(
+    payload.releaseManifest?.status,
+    'CRITICAL',
+    'manifest 缺少 Pingora 时 releaseManifest 必须标记 CRITICAL。',
+  );
+  assertIncludes(
+    payload.releaseManifest?.diagnostics?.join('\n') || '',
+    'release manifest 缺少 pingora-gateway artifact',
+    'manifest 缺少 Pingora 时必须给出明确诊断。',
+  );
+}
+
+function assertMissingCutoverScriptFails() {
+  const fixture = prepareFixture('missing-evidence-bundle');
+  rmSync(
+    path.join(
+      fixture.releaseRoot,
+      'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    ),
+  );
+  const result = runAudit(fixture);
+
+  assertStatus(result, 1, '缺少切换证据包脚本时自审必须失败。');
+  const payload = parseJson(result.stdout, '缺少证据包自审输出');
+  assertEqual(
+    payload.summary.status,
+    'CRITICAL',
+    '缺少证据包时 summary 必须是 CRITICAL。',
+  );
+  const artifact = payload.artifacts.find(
+    (item) => item.path === 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+  );
+  if (!artifact || artifact.status !== 'CRITICAL') {
+    failures.push('缺少证据包时对应 artifact 必须标记 CRITICAL。');
+  }
+}
+
+function assertRequirePingoraGatewayFailsWhenMissing() {
+  const fixture = prepareFixture('missing-required-gateway', {
+    includePingoraGateway: false,
+  });
+  const result = runAudit(fixture, ['--require-pingora-gateway']);
+
+  assertStatus(result, 1, '要求 Pingora 二进制但 release 未包含时必须失败。');
+  const payload = parseJson(result.stdout, '缺少 Pingora 二进制自审输出');
+  assertEqual(
+    payload.pingoraGateway.status,
+    'CRITICAL',
+    '缺少必需 Pingora 二进制必须标记 CRITICAL。',
+  );
+}
+
+function assertIncludedPingoraGatewayMustBeExecutable() {
+  const fixture = prepareFixture('non-executable-gateway');
+  chmodSync(path.join(fixture.releaseRoot, 'pingora-gateway'), 0o644);
+  const result = runAudit(fixture);
+
+  assertStatus(result, 1, '包含不可执行 pingora-gateway 时必须失败。');
+  const payload = parseJson(result.stdout, '不可执行 Pingora 二进制自审输出');
+  assertEqual(
+    payload.pingoraGateway.status,
+    'CRITICAL',
+    '不可执行 Pingora 二进制必须标记 CRITICAL。',
+  );
+}
+
+function assertSystemdShowRequiresCurrentReleaseExecStart() {
+  const fixture = prepareFixture('systemd-old-path');
+  const result = runAudit(fixture, ['--systemd-show'], {
+    systemdExecStart: '/opt/genarrative/old-release/pingora-gateway',
+  });
+
+  assertStatus(result, 1, 'systemd ExecStart 指向旧 release 时必须失败。');
+  const payload = parseJson(result.stdout, '旧 ExecStart 自审输出');
+  assertEqual(
+    payload.systemd.status,
+    'CRITICAL',
+    '旧 ExecStart 必须让 systemd 自审标记 CRITICAL。',
+  );
+  assertIncludes(
+    payload.systemd.diagnostics.join('\n'),
+    'ExecStart 未指向 current release 网关二进制',
+    '旧 ExecStart 必须给出明确诊断。',
+  );
+}
+
+function assertSystemdShowAcceptsCurrentSymlinkExecStart() {
+  const fixture = prepareFixture('systemd-current-symlink', {
+    releaseDirectoryName: 'releases/current-build',
+  });
+  const currentRoot = path.join(fixture.root, 'current');
+  symlinkSync(fixture.releaseRoot, currentRoot, 'dir');
+  const currentBinary = path.join(currentRoot, 'pingora-gateway');
+  const result = runAudit(fixture, ['--systemd-show'], {
+    systemdExecStart: currentBinary,
+  });
+
+  assertStatus(
+    result,
+    0,
+    'systemd ExecStart 指向 current symlink 且解析到本次 release 时必须通过。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const payload = parseJson(result.stdout, 'current symlink ExecStart 自审输出');
+  assertEqual(
+    payload.systemd.status,
+    'OK',
+    'current symlink ExecStart 必须让 systemd 自审通过。',
+  );
+  assertEqual(
+    payload.systemd.execStartBinary,
+    currentBinary,
+    'systemd 自审必须记录 ExecStart 中的原始 current symlink 路径。',
+  );
+  assertEqual(
+    payload.systemd.expectedRealpath,
+    payload.systemd.execStartRealpath,
+    'systemd 自审必须用真实路径确认 current symlink 指向本次 release 二进制。',
+  );
+}
+
+function assertRejectsRelativeReleaseRoot() {
+  const result = spawnSync(
+    'node',
+    [AUDIT_SCRIPT, '--release-root', 'build/current'],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('current release 自审必须拒绝相对 release root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--release-root 必须是绝对路径',
+    '相对 release root 必须给出明确错误。',
+  );
+}
+
+function assertRejectsFilesystemRootReleaseRoot() {
+  const result = spawnSync(
+    'node',
+    [AUDIT_SCRIPT, '--release-root', '/'],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('current release 自审必须拒绝文件系统根目录 release root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--release-root 不能是文件系统根目录',
+    '文件系统根目录 release root 必须给出明确错误。',
+  );
+}
+
+function assertRejectsPathArgsWithControlCharacters() {
+  const fixture = prepareFixture('control-character-release-root');
+  const result = runAudit(fixture, [
+    '--systemd-show',
+    '--release-root',
+    `${fixture.releaseRoot}\n--fake-flag`,
+  ]);
+
+  if ((result.status ?? 0) === 0) {
+    failures.push('current release 自审必须拒绝带换行的 release root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--release-root 不能包含换行或 NUL 字符',
+    '带换行的 release root 必须给出明确错误。',
+  );
+
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  if (commandsLog.includes('systemctl')) {
+    failures.push('release root 含控制字符时必须在执行 systemctl 前失败。');
+  }
+}
+
+function assertRejectsInvalidTimeout() {
+  const fixture = prepareFixture('invalid-timeout');
+  const cliResult = runAudit(fixture, ['--timeout-ms', '0']);
+  if ((cliResult.status ?? 0) === 0) {
+    failures.push('current release 自审必须拒绝非正数 --timeout-ms。');
+  }
+  assertIncludes(
+    `${cliResult.stdout}\n${cliResult.stderr}`,
+    '--timeout-ms 必须是正整数',
+    '非法 --timeout-ms 必须给出明确错误。',
+  );
+
+  const envResult = runAudit(fixture, [], {
+    timeoutEnv: 'abc',
+  });
+  if ((envResult.status ?? 0) === 0) {
+    failures.push('current release 自审必须拒绝非法 timeout env。');
+  }
+  assertIncludes(
+    `${envResult.stdout}\n${envResult.stderr}`,
+    'GENARRATIVE_PINGORA_CURRENT_RELEASE_TIMEOUT_MS 必须是正整数',
+    '非法 timeout env 必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidBoolEnv() {
+  const fixture = prepareFixture('invalid-bool-env');
+  const cases = [
+    {
+      env: { GENARRATIVE_PINGORA_CURRENT_RELEASE_REQUIRE_GATEWAY: 'ture' },
+      expected: 'GENARRATIVE_PINGORA_CURRENT_RELEASE_REQUIRE_GATEWAY 必须是布尔值',
+      reason: 'current release 自审必须拒绝拼写错误的 require gateway env。',
+    },
+    {
+      env: { GENARRATIVE_PINGORA_CURRENT_RELEASE_SYSTEMD_SHOW: 'enabled' },
+      expected: 'GENARRATIVE_PINGORA_CURRENT_RELEASE_SYSTEMD_SHOW 必须是布尔值',
+      reason: 'current release 自审必须拒绝非法 systemd show env。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = runAudit(fixture, [], { extraEnv: testCase.env });
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function prepareFixture(name, options = {}) {
+  const root = path.join(tmpRoot, name);
+  const releaseRoot = path.join(root, options.releaseDirectoryName || 'current');
+  const fakeBin = path.join(root, 'bin');
+  const commandsLog = path.join(root, 'commands.log');
+  const includePingoraGateway = options.includePingoraGateway !== false;
+
+  mkdirSync(fakeBin, { recursive: true });
+  writeFileSync(commandsLog, '', 'utf8');
+  prepareReleaseRoot(releaseRoot, {
+    includePingoraGateway,
+    includePingoraInManifest: options.includePingoraInManifest !== false,
+  });
+  writeFakeSystemctl(fakeBin, commandsLog, releaseRoot);
+
+  return {
+    root,
+    releaseRoot,
+    fakeBin,
+    commandsLog,
+  };
+}
+
+function prepareReleaseRoot(releaseRoot, options) {
+  for (const dir of [
+    'scripts',
+    'scripts/ops',
+    'scripts/deploy',
+    'deploy/systemd',
+    'deploy/nginx',
+    'deploy/env',
+    'deploy/pingora',
+  ]) {
+    mkdirSync(path.join(releaseRoot, dir), { recursive: true });
+  }
+
+  writeFileSync(path.join(releaseRoot, 'api-server'), '#!/usr/bin/env bash\n', 'utf8');
+  chmodExecutable(path.join(releaseRoot, 'api-server'));
+  writeChecksum(releaseRoot, 'api-server');
+
+  for (const file of [
+    'scripts/database-backup-to-oss.mjs',
+    'scripts/ops/production-health-patrol.mjs',
+    'scripts/ops/pingora-current-release-audit.mjs',
+    'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    'scripts/check-production-health-patrol-env.mjs',
+    'scripts/check-pingora-release-readiness.mjs',
+    'scripts/check-pingora-direct-preflight.mjs',
+    'scripts/check-pingora-direct-live.mjs',
+    'scripts/check-pingora-canary-live.mjs',
+    'scripts/check-pingora-canary-access-log-parity.mjs',
+    'scripts/deploy/pingora-direct-enable.sh',
+    'scripts/deploy/pingora-direct-rollback.sh',
+    'scripts/deploy/pingora-realpath-canary-enable.sh',
+    'scripts/deploy/pingora-realpath-canary-disable.sh',
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    'scripts/deploy/pingora-tls-cert-sync.mjs',
+    'deploy/systemd/genarrative-pingora-gateway.service',
+    'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    'deploy/nginx/snippets/genarrative-pingora-canary.conf',
+    'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    'deploy/env/health-patrol.env.example',
+    'deploy/env/pingora-direct-live.env.example',
+    'deploy/env/pingora-canary-live.env.example',
+    'deploy/pingora/pingora-gateway.env.example',
+    'deploy/pingora/nginx-route-parity.matrix.json',
+  ]) {
+    const target = path.join(releaseRoot, file);
+    mkdirSync(path.dirname(target), { recursive: true });
+    if (existsSync(file)) {
+      copyFileSync(file, target);
+    } else {
+      writeFileSync(target, '', 'utf8');
+    }
+  }
+
+  for (const file of [
+    'scripts/deploy/pingora-direct-enable.sh',
+    'scripts/deploy/pingora-direct-rollback.sh',
+    'scripts/deploy/pingora-realpath-canary-enable.sh',
+    'scripts/deploy/pingora-realpath-canary-disable.sh',
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    'scripts/deploy/pingora-tls-cert-sync.mjs',
+  ]) {
+    chmodExecutable(path.join(releaseRoot, file));
+  }
+
+  if (options.includePingoraGateway) {
+    writeFileSync(
+      path.join(releaseRoot, 'pingora-gateway'),
+      '#!/usr/bin/env bash\n',
+      'utf8',
+    );
+    chmodExecutable(path.join(releaseRoot, 'pingora-gateway'));
+    writeChecksum(releaseRoot, 'pingora-gateway');
+  }
+  writeReleaseManifest(releaseRoot, {
+    includePingoraGateway: options.includePingoraGateway,
+    includePingoraInManifest: options.includePingoraInManifest !== false,
+  });
+}
+
+function writeFakeSystemctl(fakeBin, commandsLog, releaseRoot) {
+  writeFileSync(
+    path.join(fakeBin, 'systemctl'),
+    [
+      '#!/usr/bin/env bash',
+      `printf 'systemctl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      'if [[ "$1" == "show" ]]; then',
+      '  exec_start="${FAKE_SYSTEMD_EXEC_START:-' +
+        shellEscapeForDoubleQuote(path.join(releaseRoot, 'pingora-gateway')) +
+        '}"',
+      '  cat <<SHOW',
+      'FragmentPath=/etc/systemd/system/genarrative-pingora-gateway.service',
+      'DropInPaths=',
+      'User=genarrative',
+      'SHOW',
+      '  printf "ExecStart={ path=%s ; argv[]=%s ; }\\n" "$exec_start" "$exec_start"',
+      '  exit 0',
+      'fi',
+      'exit 1',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(path.join(fakeBin, 'systemctl'));
+}
+
+function runAudit(fixture, args = [], options = {}) {
+  return spawnSync(
+    'node',
+    [
+      AUDIT_SCRIPT,
+      '--release-root',
+      fixture.releaseRoot,
+      ...args,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        PATH: `${fixture.fakeBin}:${process.env.PATH || ''}`,
+        ...(options.timeoutEnv
+          ? { GENARRATIVE_PINGORA_CURRENT_RELEASE_TIMEOUT_MS: options.timeoutEnv }
+          : {}),
+        ...(options.extraEnv || {}),
+        FAKE_SYSTEMD_EXEC_START:
+          options.systemdExecStart || path.join(fixture.releaseRoot, 'pingora-gateway'),
+      },
+    },
+  );
+}
+
+function chmodExecutable(filePath) {
+  chmodSync(filePath, 0o755);
+}
+
+function writeChecksum(directory, fileName) {
+  const content = readFileSync(path.join(directory, fileName));
+  const checksum = createHash('sha256').update(content).digest('hex');
+  writeFileSync(
+    path.join(directory, `${fileName}.sha256`),
+    `${checksum}  ${fileName}\n`,
+    'utf8',
+  );
+}
+
+function writeReleaseManifest(releaseRoot, options) {
+  const artifacts = [
+    {
+      component: 'api-server',
+      path: 'api-server',
+      checksum_path: 'api-server.sha256',
+    },
+  ];
+  if (options.includePingoraGateway && options.includePingoraInManifest) {
+    artifacts.push({
+      component: 'pingora-gateway',
+      path: 'pingora-gateway',
+      checksum_path: 'pingora-gateway.sha256',
+    });
+  }
+  writeFileSync(
+    path.join(releaseRoot, 'release-manifest.api-server.json'),
+    `${JSON.stringify(
+      {
+        version: 'check-current-release',
+        component_type: 'api-server',
+        artifacts,
+      },
+      null,
+      2,
+    )}\n`,
+    'utf8',
+  );
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function shellEscapeForDoubleQuote(value) {
+  return String(value).replace(/["\\$`]/g, '\\$&');
+}
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  if ((result.status ?? 0) !== expected) {
+    failures.push(
+      `${reason} 实际退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 实际 ${actual}，预期 ${expected}。`);
+  }
+}
+
+function assertIncludes(value, expected, reason) {
+  const haystack = Array.isArray(value) ? value.join('\n') : String(value);
+  if (!haystack.includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
diff --git a/scripts/check-pingora-cutover-command-evidence.mjs b/scripts/check-pingora-cutover-command-evidence.mjs
new file mode 100644
index 000000000..6e2d4be94
--- /dev/null
+++ b/scripts/check-pingora-cutover-command-evidence.mjs
@@ -0,0 +1,908 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const COMMAND_EVIDENCE_SCRIPT =
+  'scripts/ops/pingora-cutover-command-evidence.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-cutover-command-evidence-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-cutover-command-evidence] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-cutover-command-evidence] OK');
+
+function main() {
+  assertScriptShape();
+  assertCommandEvidenceSucceedsAndWritesArtifacts();
+  assertCommandEvidenceWritesCutoverRunId();
+  assertCommandFailureStillWritesEvidenceAndFails();
+  assertCommandEvidenceRedactsProbeTokensFromArtifacts();
+  assertRejectsUnsafeNames();
+  assertRejectsRelativeOutputRoot();
+  assertRejectsFilesystemRootOutputRoot();
+  assertRejectsOutputRootWithControlCharacters();
+  assertRejectsSymlinkOutputRootBeforeCommand();
+  assertRejectsFileOutputRootBeforeCommand();
+  assertRejectsRelativeCommandPath();
+  assertRejectsBareCommandName();
+  assertRejectsFilesystemRootCommand();
+  assertRejectsCommandWithControlCharacters();
+  assertRejectsCommandArgWithControlCharacters();
+  assertRejectsRelativeExpectedExecutable();
+  assertRejectsFilesystemRootExpectedExecutable();
+  assertRejectsExpectedExecutableWithControlCharacters();
+  assertRejectsMismatchedExpectedExecutableBeforeCommand();
+  assertRejectsMissingRequiredArgBeforeCommand();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(COMMAND_EVIDENCE_SCRIPT, 'utf8');
+  assertIncludes(
+    content,
+    'command.stdout.txt',
+    '命令证据脚本必须保存真实命令 stdout。',
+  );
+  assertIncludes(
+    content,
+    'command.stderr.txt',
+    '命令证据脚本必须保存真实命令 stderr。',
+  );
+  assertIncludes(
+    content,
+    'command-record.json',
+    '命令证据脚本必须保存结构化命令记录。',
+  );
+  assertIncludes(
+    content,
+    'manifest.json',
+    '命令证据脚本必须写 manifest。',
+  );
+  assertIncludes(
+    content,
+    'cutoverRunId',
+    '命令证据脚本必须支持写入切换批次 ID。',
+  );
+  assertIncludes(
+    content,
+    '--cutover-run-id',
+    '命令证据脚本 usage 必须公开切换批次 ID 参数。',
+  );
+  assertIncludes(
+    content,
+    '--expected-executable',
+    '命令证据脚本 usage 必须公开预期真实命令参数。',
+  );
+  assertIncludes(
+    content,
+    '--require-arg',
+    '命令证据脚本 usage 必须公开真实命令必需参数。',
+  );
+  assertIncludes(
+    content,
+    'SECRET_VALUE_FLAGS',
+    '命令证据脚本必须集中维护敏感参数脱敏列表。',
+  );
+  assertIncludes(
+    content,
+    'redactSecrets(text',
+    '命令证据脚本必须脱敏 stdout/stderr 中的敏感值。',
+  );
+  assertIncludes(
+    content,
+    "flag: 'wx'",
+    '命令证据脚本写证据文件时必须避免覆盖既有文件。',
+  );
+  assertIncludes(
+    content,
+    'BUNDLE_DIR_MODE = 0o750',
+    '命令证据目录必须显式固定权限。',
+  );
+  assertIncludes(
+    content,
+    'EVIDENCE_FILE_MODE = 0o640',
+    '命令证据文件必须显式固定权限。',
+  );
+}
+
+function assertCommandEvidenceSucceedsAndWritesArtifacts() {
+  const fixture = prepareFixture('success');
+  const result = runCommandEvidence(fixture, [
+    '--phase',
+    'enable-apply',
+    '--command-name',
+    'pingora-direct-enable-apply',
+    '--output-root',
+    fixture.outputRoot,
+    '--expected-executable',
+    fixture.commandScript,
+    '--',
+    fixture.commandScript,
+    '--message',
+    'hello-command',
+  ]);
+
+  assertStatus(result, 0, '真实命令成功时命令证据脚本应成功退出。');
+  assertIncludes(
+    result.stdout,
+    'hello-command',
+    '命令证据脚本必须把真实命令 stdout 透传到终端。',
+  );
+  const output = parseLastJsonObject(result.stdout, '成功命令证据 stdout');
+  assertEqual(output.status, 'OK', 'stdout JSON 必须记录 OK 状态。');
+  assertFileExists(output.bundleDir, '命令证据目录必须存在。');
+
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(manifest.summary.status, 'OK', 'manifest 必须记录 OK 状态。');
+  assertEqual(
+    manifest.command?.name,
+    'pingora-direct-enable-apply',
+    'manifest 必须记录命令名。',
+  );
+  assertEqual(
+    manifest.command?.exitCode,
+    0,
+    'manifest 必须记录真实命令退出码。',
+  );
+  assertEqual(
+    manifest.expectedExecutable,
+    fixture.commandScript,
+    'manifest 必须记录预期真实命令路径。',
+  );
+  assertEqual(
+    manifest.command?.expectedExecutable,
+    fixture.commandScript,
+    'command-record 必须记录预期真实命令路径。',
+  );
+  assertEqual(
+    manifest.command?.executable,
+    fixture.commandScript,
+    'manifest.command 必须记录真实命令绝对路径。',
+  );
+  const commandRecord = readJson(path.join(output.bundleDir, 'command-record.json'));
+  assertEqual(
+    commandRecord.executable,
+    fixture.commandScript,
+    'command-record.json 必须记录真实命令绝对路径。',
+  );
+  assertEqual(
+    output.expectedExecutable,
+    fixture.commandScript,
+    'stdout JSON 必须返回预期真实命令路径。',
+  );
+  assertIncludes(
+    manifest.command?.args || [],
+    '--message',
+    'manifest 必须记录结构化命令参数。',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.stdout,
+    'command.stdout.txt',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.stderr,
+    'command.stderr.txt',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.commandRecord,
+    'command-record.json',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'command.stdout.txt'),
+    '命令证据必须保存 stdout。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'command.stderr.txt'),
+    '命令证据必须保存 stderr。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'command-record.json'),
+    '命令证据必须保存 command-record.json。',
+  );
+  assertMode(output.bundleDir, 0o750, '命令证据目录权限必须是 0750。');
+  for (const fileName of [
+    'manifest.json',
+    'command.stdout.txt',
+    'command.stderr.txt',
+    'command-record.json',
+  ]) {
+    assertMode(
+      path.join(output.bundleDir, fileName),
+      0o640,
+      `${fileName} 权限必须是 0640。`,
+    );
+  }
+}
+
+function assertCommandEvidenceWritesCutoverRunId() {
+  const fixture = prepareFixture('cutover-run-id');
+  const result = runCommandEvidence(fixture, [
+    '--phase',
+    'enable-apply',
+    '--command-name',
+    'pingora-direct-enable-apply',
+    '--cutover-run-id',
+    'cutover-20260617T020000Z',
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    fixture.commandScript,
+    '--message',
+    'hello-cutover-run',
+  ]);
+
+  assertStatus(result, 0, '提供 cutover run id 时命令证据脚本应成功退出。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseLastJsonObject(result.stdout, 'cutover run id 命令证据 stdout');
+  assertEqual(
+    output.cutoverRunId,
+    'cutover-20260617T020000Z',
+    '命令证据 stdout 必须返回 cutoverRunId。',
+  );
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.cutoverRunId,
+    'cutover-20260617T020000Z',
+    '命令证据 manifest 必须记录 cutoverRunId。',
+  );
+  assertEqual(
+    manifest.command?.cutoverRunId,
+    'cutover-20260617T020000Z',
+    'command-record 必须同步记录 cutoverRunId。',
+  );
+}
+
+function assertCommandFailureStillWritesEvidenceAndFails() {
+  const fixture = prepareFixture('failure');
+  const result = runCommandEvidence(fixture, [
+    '--phase',
+    'rollback-apply',
+    '--command-name',
+    'pingora-direct-rollback-apply',
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    fixture.commandScript,
+    '--message',
+    'rollback-output',
+    '--fail',
+  ]);
+
+  assertStatus(result, 37, '真实命令失败时命令证据脚本应返回真实退出码。');
+  const output = parseLastJsonObject(result.stdout, '失败命令证据 stdout');
+  assertEqual(output.status, 'FAILED', '失败 stdout JSON 必须记录 FAILED。');
+  assertFileExists(output.bundleDir, '失败时仍必须保留命令证据目录。');
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.exitCode,
+    37,
+    '失败 manifest 必须记录真实退出码。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'command.stdout.txt'),
+    '失败时仍必须保存 stdout。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'command.stderr.txt'),
+    '失败时仍必须保存 stderr。',
+  );
+}
+
+function assertCommandEvidenceRedactsProbeTokensFromArtifacts() {
+  const fixture = prepareFixture('redact-token');
+  const result = runCommandEvidence(fixture, [
+    '--phase',
+    'rollback-apply',
+    '--command-name',
+    'pingora-direct-rollback-apply',
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    fixture.commandScript,
+    '--message',
+    'probe-token=secret-shadow-token',
+    '--pingora-shadow-probe-token',
+    'secret-shadow-token',
+    '--direct-probe-token=secret-inline-token',
+    '--echo-env-token',
+  ]);
+
+  assertStatus(result, 0, '带 token 的命令证据脚本应成功退出。');
+  for (const secret of [
+    'secret-shadow-token',
+    'secret-inline-token',
+    'secret-env-token',
+  ]) {
+    assertNotIncludes(
+      result.stdout,
+      secret,
+      '命令证据脚本透传 stdout 时不能泄露 token。',
+    );
+  }
+  const output = parseLastJsonObject(result.stdout, '脱敏命令证据 stdout');
+  for (const fileName of [
+    'manifest.json',
+    'command.stdout.txt',
+    'command.stderr.txt',
+    'command-record.json',
+  ]) {
+    const content = readFileSync(path.join(output.bundleDir, fileName), 'utf8');
+    for (const secret of [
+      'secret-shadow-token',
+      'secret-inline-token',
+      'secret-env-token',
+    ]) {
+      assertNotIncludes(
+        content,
+        secret,
+        `${fileName} 不能泄露 token 原文。`,
+      );
+    }
+    assertIncludes(content, '<redacted>', `${fileName} 必须保留脱敏占位符。`);
+  }
+}
+
+function assertRejectsUnsafeNames() {
+  const fixture = prepareFixture('unsafe-name');
+  for (const [flag, value, expected] of [
+    ['--phase', '../rollback', '--phase 只能包含 ASCII'],
+    ['--command-name', '回退', '--command-name 只能包含 ASCII'],
+    ['--cutover-run-id', 'cutover 1', '--cutover-run-id 只能包含 ASCII'],
+  ]) {
+    const result = runCommandEvidence(fixture, [
+      flag,
+      value,
+      '--output-root',
+      fixture.outputRoot,
+      '--',
+      fixture.commandScript,
+    ]);
+    if ((result.status ?? 0) === 0) {
+      failures.push(`${flag} 使用不安全值时必须失败。`);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      expected,
+      `${flag} 不安全值必须给出明确错误。`,
+    );
+    assertNotIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      '[fake-command]',
+      `${flag} 不安全值被拒绝时不应执行真实命令。`,
+    );
+  }
+}
+
+function assertRejectsRelativeOutputRoot() {
+  const fixture = prepareFixture('relative-output-root');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    'pingora-evidence',
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝相对 --output-root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--output-root 必须是绝对路径',
+    '相对 output-root 必须给出明确错误。',
+  );
+}
+
+function assertRejectsFilesystemRootOutputRoot() {
+  const fixture = prepareFixture('root-output-root');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    '/',
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝文件系统根目录 output-root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--output-root 不能是文件系统根目录',
+    '根目录 output-root 必须给出明确错误。',
+  );
+}
+
+function assertRejectsOutputRootWithControlCharacters() {
+  const fixture = prepareFixture('output-root-control-characters');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    `${fixture.outputRoot}\n--phase rollback-apply`,
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝带换行的 --output-root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--output-root 不能包含换行或 NUL 字符',
+    '带换行 output-root 必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '带换行 output-root 被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsSymlinkOutputRootBeforeCommand() {
+  const fixture = prepareFixture('symlink-output-root');
+  const realTarget = path.join(tmpRoot, 'symlink-output-root-real-target');
+  rmSync(fixture.outputRoot, { recursive: true, force: true });
+  mkdirSync(realTarget, { recursive: true });
+  symlinkSync(realTarget, fixture.outputRoot, 'dir');
+
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝符号链接 output-root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--output-root 不能是符号链接',
+    '符号链接 output-root 必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '符号链接 output-root 被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsFileOutputRootBeforeCommand() {
+  const fixture = prepareFixture('file-output-root');
+  rmSync(fixture.outputRoot, { recursive: true, force: true });
+  writeFileSync(fixture.outputRoot, 'not a directory\n', 'utf8');
+
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝非目录 output-root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--output-root 已存在但不是目录',
+    '非目录 output-root 必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '非目录 output-root 被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsRelativeCommandPath() {
+  const fixture = prepareFixture('relative-command-path');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    'scripts/deploy/pingora-direct-rollback.sh',
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝带路径的相对命令。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '真实命令必须是绝对路径',
+    '相对命令路径必须给出明确错误。',
+  );
+}
+
+function assertRejectsBareCommandName() {
+  const fixture = prepareFixture('bare-command-name');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    'echo',
+    'SHOULD_NOT_RUN',
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝 PATH 裸命令名。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '真实命令必须是绝对路径',
+    'PATH 裸命令名必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'SHOULD_NOT_RUN',
+    'PATH 裸命令名被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsFilesystemRootCommand() {
+  const fixture = prepareFixture('filesystem-root-command');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    path.parse(process.cwd()).root,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝文件系统根目录真实命令。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '真实命令不能是文件系统根目录',
+    '文件系统根目录真实命令必须给出明确错误。',
+  );
+}
+
+function assertRejectsCommandWithControlCharacters() {
+  const fixture = prepareFixture('command-control-characters');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    `${fixture.commandScript}\n`,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝带换行的真实命令。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '真实命令不能包含换行或 NUL 字符',
+    '带换行的真实命令必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '带换行的真实命令被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsCommandArgWithControlCharacters() {
+  const fixture = prepareFixture('command-arg-control-characters');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--',
+    fixture.commandScript,
+    '--message',
+    'line1\nline2',
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝带换行的真实命令参数。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '真实命令参数不能包含换行或 NUL 字符',
+    '带换行的真实命令参数必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '带换行的真实命令参数被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsRelativeExpectedExecutable() {
+  const fixture = prepareFixture('relative-expected-executable');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--expected-executable',
+    'scripts/deploy/pingora-direct-enable.sh',
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝相对 --expected-executable。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--expected-executable 必须是绝对路径',
+    '相对 expected executable 必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '相对 expected executable 被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsFilesystemRootExpectedExecutable() {
+  const fixture = prepareFixture('filesystem-root-expected-executable');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--expected-executable',
+    path.parse(process.cwd()).root,
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝文件系统根目录 --expected-executable。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--expected-executable 不能是文件系统根目录',
+    '文件系统根目录 expected executable 必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '文件系统根目录 expected executable 被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsExpectedExecutableWithControlCharacters() {
+  const fixture = prepareFixture('expected-executable-control-characters');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--expected-executable',
+    `${fixture.commandScript}\n`,
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝带换行的 --expected-executable。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--expected-executable 不能包含换行或 NUL 字符',
+    '带换行的 expected executable 必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '带换行 expected executable 被拒绝时不应执行真实命令。',
+  );
+}
+
+function assertRejectsMismatchedExpectedExecutableBeforeCommand() {
+  const fixture = prepareFixture('mismatched-expected-executable');
+  const expected = path.join(fixture.root, 'expected-enable.sh');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--expected-executable',
+    expected,
+    '--',
+    fixture.commandScript,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝与 --expected-executable 不一致的真实命令。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '真实命令与 --expected-executable 不一致',
+    '真实命令与 expected executable 不一致时必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '真实命令与 expected executable 不一致时不应执行真实命令。',
+  );
+}
+
+function assertRejectsMissingRequiredArgBeforeCommand() {
+  const fixture = prepareFixture('missing-required-arg');
+  const result = runCommandEvidence(fixture, [
+    '--output-root',
+    fixture.outputRoot,
+    '--require-arg',
+    '--apply',
+    '--',
+    fixture.commandScript,
+    '--message',
+    'dry-run-only',
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('命令证据脚本必须拒绝缺少 --require-arg 的真实命令。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '真实命令参数缺少 --require-arg 要求的 --apply',
+    '真实命令缺少 required arg 时必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-command]',
+    '真实命令缺少 required arg 时不应执行真实命令。',
+  );
+}
+
+function prepareFixture(name) {
+  const root = path.join(tmpRoot, name);
+  const outputRoot = path.join(root, 'evidence');
+  const commandScript = path.join(root, 'fake-command.sh');
+  mkdirSync(outputRoot, { recursive: true });
+  writeFileSync(
+    commandScript,
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'message="ok"',
+      'exit_code=0',
+      'while [[ $# -gt 0 ]]; do',
+      '  case "$1" in',
+      '    --message)',
+      '      message="$2"',
+      '      shift 2',
+      '      ;;',
+      '    --fail)',
+      '      exit_code=37',
+      '      shift',
+      '      ;;',
+      '    --echo-env-token)',
+      '      echo "[fake-command] env=${GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN:-}"',
+      '      shift',
+      '      ;;',
+      '    --pingora-shadow-probe-token)',
+      '      echo "[fake-command] token=$2" >&2',
+      '      shift 2',
+      '      ;;',
+      '    *)',
+      '      shift',
+      '      ;;',
+      '  esac',
+      'done',
+      'echo "[fake-command] stdout ${message}"',
+      'echo "[fake-command] stderr ${message}" >&2',
+      'exit "${exit_code}"',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  spawnSync('chmod', ['0755', commandScript], { encoding: 'utf8' });
+  return { root, outputRoot, commandScript };
+}
+
+function runCommandEvidence(fixture, args) {
+  return spawnSync('node', [COMMAND_EVIDENCE_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      GENARRATIVE_PINGORA_CUTOVER_RUN_ID: '',
+      GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_ROOT: fixture.outputRoot,
+      GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN: 'secret-env-token',
+    },
+  });
+}
+
+function parseLastJsonObject(text, label) {
+  const end = text.lastIndexOf('}');
+  if (end < 0) {
+    failures.push(`${label} 未包含 JSON 结果。`);
+    return {};
+  }
+  for (let start = text.lastIndexOf('{', end); start >= 0; start = text.lastIndexOf('{', start - 1)) {
+    try {
+      return JSON.parse(text.slice(start, end + 1));
+    } catch {
+      // 继续向前找外层 JSON 起点。
+    }
+  }
+  failures.push(`${label} 未包含合法 JSON 结果。`);
+  return {};
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    failures.push(`${filePath} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function assertManifestFileMetadata(bundleDir, metadata, expectedPath) {
+  if (!metadata || typeof metadata !== 'object') {
+    failures.push(`${expectedPath} 必须在 manifest.files 中记录结构化元数据。`);
+    return;
+  }
+  assertEqual(
+    metadata.path,
+    expectedPath,
+    `${expectedPath} manifest 元数据必须记录文件名。`,
+  );
+  const filePath = path.join(bundleDir, expectedPath);
+  const content = readFileSync(filePath);
+  assertEqual(
+    metadata.sizeBytes,
+    content.length,
+    `${expectedPath} manifest 元数据必须记录文件大小。`,
+  );
+  assertEqual(
+    metadata.sha256,
+    createHash('sha256').update(content).digest('hex'),
+    `${expectedPath} manifest 元数据必须记录 sha256。`,
+  );
+}
+
+function assertFileExists(filePath, reason) {
+  if (!existsSync(filePath)) {
+    failures.push(`${reason} 缺少: ${filePath}`);
+  }
+}
+
+function assertMode(filePath, expected, reason) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  const actual = statSync(filePath).mode & 0o777;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 实际 ${actual.toString(8)}，预期 ${expected.toString(8)}。`,
+    );
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 实际 ${JSON.stringify(actual)}，预期 ${JSON.stringify(expected)}。`);
+  }
+}
+
+function assertIncludes(value, expected, reason) {
+  if (!String(value).includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
+
+function assertNotIncludes(value, unexpected, reason) {
+  if (String(value).includes(unexpected)) {
+    failures.push(`${reason} 不应包含: ${unexpected}`);
+  }
+}
diff --git a/scripts/check-pingora-cutover-evidence-audit.mjs b/scripts/check-pingora-cutover-evidence-audit.mjs
new file mode 100644
index 000000000..99979b377
--- /dev/null
+++ b/scripts/check-pingora-cutover-evidence-audit.mjs
@@ -0,0 +1,3194 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const AUDIT_SCRIPT = 'scripts/ops/pingora-cutover-evidence-audit.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-cutover-evidence-audit-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-cutover-evidence-audit] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-cutover-evidence-audit] OK');
+
+function main() {
+  assertScriptShape();
+  assertRequiredPhasesSucceed();
+  assertRequirePhaseDirectLiveAccessLogSucceeds();
+  assertRequirePhaseDirectLiveAccessLogFailsWhenMissing();
+  assertRequirePhaseDirectLiveAccessLogFailsWhenPhaseMissing();
+  assertRequirePhaseDirectLiveStaticHeadersSucceeds();
+  assertRequirePhaseDirectLiveStaticHeadersFailsWhenMissing();
+  assertRequirePhasePingoraEnvShadowSucceeds();
+  assertRequirePhasePingoraEnvShadowFailsWhenMissing();
+  assertRequirePhasePingoraEnvShadowFailsWhenDirectLowPortsRemain();
+  assertRequiredCommandsSucceed();
+  assertRequiredCommandExecutableImplicitlyRequiresCommand();
+  assertRequiredCommandArgImplicitlyRequiresCommand();
+  assertRequiredCommandExecutableMismatchFails();
+  assertInvalidTopLevelExpectedExecutableFails();
+  assertInvalidEmbeddedExpectedExecutableFails();
+  assertManifestCommandExecutableMismatchExpectedFails();
+  assertRelativeCommandExecutableFails();
+  assertMissingCommandExecutableFails();
+  assertRequiredCommandArgMissingFails();
+  assertCommandRecordMismatchFails();
+  assertCommandRecordTimelineMismatchFails();
+  assertCommandRecordOutputPathMismatchFails();
+  assertCommandRecordArgsMismatchFails();
+  assertCommandRecordArgsControlCharacterFails();
+  assertCommandNameMismatchFails();
+  assertInvalidTopLevelCommandNameFails();
+  assertInvalidEmbeddedCommandNameFails();
+  assertFullCutoverTimelineSucceed();
+  assertFullCutoverTimelineFailsWhenPostEnableAccessLogMissing();
+  assertFullCutoverTimelineFailsWhenPostEnableStaticHeadersMissing();
+  assertFullCutoverTimelineWithRunIdSucceed();
+  assertLongCutoverTimelineFails();
+  assertTimelineMaxSpanOverrideSucceed();
+  assertTimelineNonOkItemFails();
+  assertMixedTimelineCutoverRunIdFails();
+  assertPartialTimelineCutoverRunIdFails();
+  assertEmptyCutoverRunIdFails();
+  assertCutoverRunIdMismatchFails();
+  assertMissingCutoverRunIdFailsWhenRequired();
+  assertMissingGeneratedAtFails();
+  assertInvalidCommandGeneratedAtFails();
+  assertNonCanonicalGeneratedAtFails();
+  assertNonCanonicalCommandRecordTimesFail();
+  assertAmbiguousLatestPhaseFails();
+  assertAmbiguousLatestCommandFails();
+  assertMissingManifestSchemaVersionFails();
+  assertCommandRecordSchemaVersionMismatchFails();
+  assertCanAuditSinglePhase();
+  assertMissingPhaseFails();
+  assertCommandBundleCannotSatisfyPhaseRequirement();
+  assertMissingCommandFails();
+  assertOutOfOrderCutoverTimelineFails();
+  assertCriticalPhaseSummaryFails();
+  assertFailedCommandSummaryFails();
+  assertLatestBrokenBundleFails();
+  assertLatestBrokenCommandBundleFails();
+  assertManifestDiagnosticsFailAudit();
+  assertExtraRootFileFailsByDefault();
+  assertExtraRootDirectoryFailsByDefault();
+  assertExtraRootSymlinkFailsByDefault();
+  assertAllowExtraRootEntriesSucceeds();
+  assertRejectsUnsafeInputs();
+  assertManifestFileNameControlCharacterFails();
+  assertRejectsInvalidTimelineMaxSpan();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(AUDIT_SCRIPT, 'utf8');
+  assertIncludes(
+    content,
+    '不会修改证据目录',
+    '证据根审计脚本 usage 必须说明只读边界。',
+  );
+  assertIncludes(
+    content,
+    'execFile',
+    '证据根审计脚本必须复用 verifier 逐包验真。',
+  );
+  assertIncludes(
+    content,
+    "'--require-summary-ok'",
+    '证据根审计脚本调用 verifier 时必须使用 strict summary 模式。',
+  );
+  assertIncludes(
+    content,
+    'manifest.phase',
+    '证据根审计脚本必须按 manifest.phase 分组。',
+  );
+  assertIncludes(
+    content,
+    'manifest.commandName',
+    '证据根审计脚本必须能按 manifest.commandName 锁定命令证据。',
+  );
+  assertIncludes(
+    content,
+    'manifest.commandName 与 manifest.command.name 必须一致',
+    '证据根审计脚本必须拒绝 manifest.commandName 与 manifest.command.name 漂移。',
+  );
+  assertIncludes(
+    content,
+    'candidate.commandName === null',
+    '证据根审计脚本必须防止命令证据冒充阶段证据。',
+  );
+  assertIncludes(
+    content,
+    '--require-command <phase>:<commandName>',
+    '证据根审计脚本 usage 必须公开命令证据强制审计参数。',
+  );
+  assertIncludes(
+    content,
+    '--require-phase-direct-live-access-log',
+    '证据根审计脚本 usage 必须公开 direct live access log 摘要强制审计参数。',
+  );
+  assertIncludes(
+    content,
+    '--require-phase-direct-live-static-headers',
+    '证据根审计脚本 usage 必须公开 direct live 静态响应头摘要强制审计参数。',
+  );
+  assertIncludes(
+    content,
+    '--require-phase-pingora-env-shadow',
+    '证据根审计脚本 usage 必须公开 Pingora env shadow 摘要强制审计参数。',
+  );
+  assertIncludes(
+    content,
+    'manifest.summary.pingoraEnvShadow',
+    '证据根审计脚本必须能校验 Pingora env shadow 摘要。',
+  );
+  assertIncludes(
+    content,
+    '--require-command-executable <phase>:<commandName>:<absolutePath>',
+    '证据根审计脚本 usage 必须公开命令证据真实脚本身份强制参数。',
+  );
+  assertIncludes(
+    content,
+    '--require-command-arg <phase>:<commandName>:<arg>',
+    '证据根审计脚本 usage 必须公开命令证据必需参数强制参数。',
+  );
+  assertIncludes(
+    content,
+    'manifest.expectedExecutable 必须是',
+    '证据根审计脚本必须能校验命令证据 expectedExecutable。',
+  );
+  assertIncludes(
+    content,
+    'readCommandRecord',
+    '证据根审计脚本必须读取独立命令记录。',
+  );
+  assertIncludes(
+    content,
+    'compareCommandRecords',
+    '证据根审计脚本必须阻断 manifest.command 与 command-record.json 语义漂移。',
+  );
+  assertIncludes(
+    content,
+    'checkCommandRecordTimes',
+    '证据根审计脚本必须校验命令记录时间字段。',
+  );
+  assertIncludes(
+    content,
+    'stdoutPath',
+    '证据根审计脚本必须校验命令 stdout 引用一致性。',
+  );
+  assertIncludes(
+    content,
+    'stderrPath',
+    '证据根审计脚本必须校验命令 stderr 引用一致性。',
+  );
+  assertIncludes(
+    content,
+    'jsonValuesEqual',
+    '证据根审计脚本必须校验独立命令记录参数一致性。',
+  );
+  assertIncludes(
+    content,
+    "'args'",
+    '证据根审计脚本必须把 args 纳入命令记录一致性比较。',
+  );
+  assertIncludes(
+    content,
+    '最新证据目录 manifest 验真失败',
+    '证据根审计脚本必须在最新证据损坏时给出明确诊断。',
+  );
+  assertIncludes(
+    content,
+    'manifest.summary.status 必须是 OK',
+    '证据根审计脚本必须检查 manifest 业务结论。',
+  );
+  assertIncludes(
+    content,
+    'pre-cutover',
+    '证据根审计脚本必须内置标准切换时间线。',
+  );
+  assertIncludes(
+    content,
+    '疑似混入不同切换窗口证据',
+    '证据根审计脚本必须在标准切换时间线倒序时给出明确诊断。',
+  );
+  assertIncludes(
+    content,
+    '--timeline-max-span-ms',
+    '证据根审计脚本必须公开标准切换时间线最大跨度配置。',
+  );
+  assertIncludes(
+    content,
+    '--require-cutover-run-id',
+    '证据根审计脚本必须公开切换批次 ID 强制参数。',
+  );
+  assertIncludes(
+    content,
+    'manifest.cutoverRunId',
+    '证据根审计脚本必须读取并校验 manifest.cutoverRunId。',
+  );
+  assertIncludes(
+    content,
+    'manifest.generatedAt 必须是合法 ISO 时间',
+    '证据根审计脚本必须拒绝缺少合法 generatedAt 的证据。',
+  );
+  assertIncludes(
+    content,
+    'manifest.schemaVersion 必须是 1',
+    '证据根审计脚本必须拒绝未知 manifest schemaVersion。',
+  );
+  assertIncludes(
+    content,
+    "['schemaVersion', 1]",
+    '证据根审计脚本必须校验命令记录 schemaVersion。',
+  );
+  assertIncludes(
+    content,
+    '不能依赖目录 mtime',
+    '证据根审计脚本不能用目录 mtime 兜底选择最新证据。',
+  );
+  assertIncludes(
+    content,
+    '不能按目录名打平选择',
+    '证据根审计脚本必须拒绝同一阶段或命令的重复最新 generatedAt。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS',
+    '证据根审计脚本必须支持用 env 覆盖标准切换时间线最大跨度。',
+  );
+  assertIncludes(
+    content,
+    '时间跨度',
+    '证据根审计脚本必须在标准切换时间线跨度过大时给出明确诊断。',
+  );
+  if (content.includes('writeFile') || content.includes('chmod(')) {
+    failures.push('证据根审计脚本必须保持只读，不能写文件或改权限。');
+  }
+  if (content.includes('mtimeMs')) {
+    failures.push('证据根审计脚本不能依赖目录 mtimeMs 选择最新证据。');
+  }
+}
+
+function assertRequiredPhasesSucceed() {
+  const root = path.join(tmpRoot, 'required-ok');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  prepareBundle(root, '20260617T020000Z-post-enable', 'post-enable', {
+    directLiveSummary: true,
+  });
+  prepareBundle(root, '20260617T030000Z-post-rollback', 'post-rollback');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+    '--require-phase',
+    'post-enable',
+    '--require-phase',
+    'post-rollback',
+  ]);
+  assertStatus(result, 0, '三阶段证据齐全且 manifest 验真通过时应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '三阶段证据审计 stdout');
+  assertEqual(output.ok, true, '三阶段证据审计 stdout 必须 ok=true。');
+  assertEqual(output.checkedCount, 3, '三阶段证据审计必须检查三项 phase。');
+  assertEqual(output.failedCount, 0, '三阶段证据审计不能有失败项。');
+  assertEqual(
+    output.phases?.every((phase) => phase.status === 'OK'),
+    true,
+    '三阶段证据审计每个 phase 都应 OK。',
+  );
+  assertEqual(
+    output.phases?.every((phase) => phase.verify?.requireSummaryOk === true),
+    true,
+    '三阶段证据审计必须让 verifier 启用 --require-summary-ok。',
+  );
+  const postEnablePhase = output.phases?.find(
+    (phase) => phase.phase === 'post-enable',
+  );
+  assertEqual(
+    postEnablePhase?.directLiveStaticHeaders?.normal?.cacheControl,
+    'no-cache',
+    '证据根审计输出必须提升 post-enable direct live 普通静态 Cache-Control 摘要。',
+  );
+  assertEqual(
+    postEnablePhase?.directLiveStaticHeaders?.fingerprinted?.cacheControl,
+    'public, max-age=31536000, immutable',
+    '证据根审计输出必须提升 post-enable direct live 指纹静态 Cache-Control 摘要。',
+  );
+  assertEqual(
+    postEnablePhase?.directLiveAccessLog?.matchedCount,
+    20,
+    '证据根审计输出必须提升 post-enable direct live access log 摘要。',
+  );
+}
+
+function assertRequirePhaseDirectLiveAccessLogSucceeds() {
+  const root = path.join(tmpRoot, 'required-access-log-ok');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  prepareBundle(root, '20260617T020000Z-post-enable', 'post-enable', {
+    directLiveSummary: true,
+    directLiveStaticHeaders: false,
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+    '--require-phase-direct-live-access-log',
+    'post-enable',
+  ]);
+  assertStatus(
+    result,
+    0,
+    '要求 post-enable access log 摘要且 manifest 已包含完整 directLiveAccessLog 时应成功。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'access log 摘要强制审计 stdout');
+  assertEqual(
+    output.phases?.[0]?.requiredDirectLiveAccessLog,
+    true,
+    'access log 摘要强制审计输出必须标记该 phase 已要求 direct live access log 摘要。',
+  );
+  assertEqual(
+    output.phases?.[0]?.manifestCheck?.directLiveAccessLogCheck?.ok,
+    true,
+    'access log 摘要强制审计必须输出 directLiveAccessLogCheck.ok=true。',
+  );
+  assertEqual(
+    output.summary?.directLiveEvidence?.[0]?.staticHeaders?.ok,
+    null,
+    '只要求 access log 且没有静态头摘要时 operator summary 不应把 staticHeaders 标成 false。',
+  );
+}
+
+function assertRequirePhaseDirectLiveAccessLogFailsWhenMissing() {
+  const root = path.join(tmpRoot, 'required-access-log-missing');
+  prepareBundle(root, '20260617T020000Z-post-enable', 'post-enable');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+    '--require-phase-direct-live-access-log',
+    'post-enable',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '要求 post-enable access log 摘要但 manifest 缺少 directLiveAccessLog 时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.directLiveAccessLog',
+    '缺少 access log 摘要时必须给出 directLiveAccessLog 诊断。',
+  );
+}
+
+function assertRequirePhaseDirectLiveAccessLogFailsWhenPhaseMissing() {
+  const root = path.join(tmpRoot, 'required-access-log-phase-missing');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+    '--require-phase-direct-live-access-log',
+    'post-enable',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '要求 post-enable access log 摘要但 post-enable 阶段证据缺失时必须失败。',
+  );
+  const output = parseJson(result.stdout, '缺 post-enable 阶段 access log 审计 stdout');
+  assertEqual(
+    output.summary?.directLiveEvidence?.[0]?.phase,
+    'post-enable',
+    '缺 post-enable 阶段时 operator summary 仍必须列出 direct live 证据要求。',
+  );
+  assertEqual(
+    output.summary?.directLiveEvidence?.[0]?.accessLog?.ok,
+    false,
+    '缺 post-enable 阶段时 operator summary accessLog.ok 必须是 false。',
+  );
+  assertIncludes(
+    output.summary?.directLiveEvidence?.[0]?.accessLog?.reason || '',
+    '没有找到该阶段的证据 manifest',
+    '缺 post-enable 阶段时 operator summary 必须给出缺阶段 reason。',
+  );
+}
+
+function assertRequirePhaseDirectLiveStaticHeadersSucceeds() {
+  const root = path.join(tmpRoot, 'required-static-headers-ok');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  prepareBundle(root, '20260617T020000Z-post-enable', 'post-enable', {
+    directLiveSummary: true,
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+    '--require-phase-direct-live-static-headers',
+    'post-enable',
+  ]);
+  assertStatus(
+    result,
+    0,
+    '要求 post-enable 静态头摘要且 manifest 已包含完整 directLiveStaticHeaders 时应成功。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '静态头摘要强制审计 stdout');
+  assertEqual(
+    output.phases?.[0]?.requiredDirectLiveStaticHeaders,
+    true,
+    '静态头摘要强制审计输出必须标记该 phase 已要求 direct live 静态头摘要。',
+  );
+  assertEqual(
+    output.phases?.[0]?.manifestCheck?.directLiveStaticHeadersCheck?.ok,
+    true,
+    '静态头摘要强制审计必须输出 directLiveStaticHeadersCheck.ok=true。',
+  );
+}
+
+function assertRequirePhaseDirectLiveStaticHeadersFailsWhenMissing() {
+  const root = path.join(tmpRoot, 'required-static-headers-missing');
+  prepareBundle(root, '20260617T020000Z-post-enable', 'post-enable');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+    '--require-phase-direct-live-static-headers',
+    'post-enable',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '要求 post-enable 静态头摘要但 manifest 缺少 directLiveStaticHeaders 时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.directLiveStaticHeaders',
+    '缺少静态头摘要时必须给出 directLiveStaticHeaders 诊断。',
+  );
+}
+
+function assertRequirePhasePingoraEnvShadowSucceeds() {
+  const root = path.join(tmpRoot, 'required-pingora-env-shadow-ok');
+  prepareBundle(root, '20260617T030000Z-post-rollback', 'post-rollback', {
+    pingoraEnvShadow: true,
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-rollback',
+    '--require-phase-pingora-env-shadow',
+    'post-rollback',
+  ]);
+  assertStatus(
+    result,
+    0,
+    '要求 post-rollback Pingora env shadow 摘要且 manifest 已包含完整摘要时应成功。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'Pingora env shadow 强制审计 stdout');
+  assertEqual(
+    output.phases?.[0]?.requiredPingoraEnvShadow,
+    true,
+    'Pingora env shadow 强制审计输出必须标记该 phase 已要求 shadow 摘要。',
+  );
+  assertEqual(
+    output.phases?.[0]?.manifestCheck?.pingoraEnvShadowCheck?.ok,
+    true,
+    'Pingora env shadow 强制审计必须输出 pingoraEnvShadowCheck.ok=true。',
+  );
+  assertEqual(
+    output.summary?.pingoraEnvShadowEvidence?.[0]?.shadow?.ok,
+    true,
+    'operator summary 必须标记 Pingora env shadow 摘要通过。',
+  );
+}
+
+function assertRequirePhasePingoraEnvShadowFailsWhenMissing() {
+  const root = path.join(tmpRoot, 'required-pingora-env-shadow-missing');
+  prepareBundle(root, '20260617T030000Z-post-rollback', 'post-rollback', {
+    pingoraEnvShadow: false,
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-rollback',
+    '--require-phase-pingora-env-shadow',
+    'post-rollback',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '要求 post-rollback Pingora env shadow 摘要但 manifest 缺少 pingoraEnvShadow 时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.pingoraEnvShadow',
+    '缺少 Pingora env shadow 摘要时必须给出 pingoraEnvShadow 诊断。',
+  );
+  const output = parseJson(result.stdout, '缺 Pingora env shadow 摘要审计 stdout');
+  assertEqual(
+    output.summary?.pingoraEnvShadowEvidence?.[0]?.shadow?.ok,
+    false,
+    '缺 Pingora env shadow 摘要时 operator summary 必须标记 shadow.ok=false。',
+  );
+}
+
+function assertRequirePhasePingoraEnvShadowFailsWhenDirectLowPortsRemain() {
+  const root = path.join(tmpRoot, 'required-pingora-env-shadow-low-ports');
+  prepareBundle(root, '20260617T030000Z-post-rollback', 'post-rollback', {
+    pingoraEnvShadow: {
+      present: true,
+      listen: '127.0.0.1:18081',
+      tlsListen: '0.0.0.0:443',
+      httpRedirectListen: '0.0.0.0:80',
+      tlsCertFile: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+      tlsKeyFile: '/etc/genarrative/pingora-tls/example/privkey.pem',
+      mode: 'direct',
+      shadowReady: false,
+      ok: false,
+      diagnostics: [
+        'tlsListen 应为空，实际 0.0.0.0:443',
+        'httpRedirectListen 应为空，实际 0.0.0.0:80',
+        'tlsCertFile 应为空，实际 /etc/genarrative/pingora-tls/example/fullchain.pem',
+      ],
+    },
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-rollback',
+    '--require-phase-pingora-env-shadow',
+    'post-rollback',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '要求 post-rollback Pingora env shadow 摘要但低端口监听仍残留时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'tlsListen 必须为空',
+    '低端口 TLS 残留时必须给出 tlsListen 诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'httpRedirectListen 必须为空',
+    '低端口 HTTP redirect 残留时必须给出 httpRedirectListen 诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'tlsCertFile 必须为空',
+    'TLS 证书路径残留时必须给出 tlsCertFile 诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'shadowReady 必须为 true',
+    'snapshot 姿态不是 shadow 时必须给出 shadowReady 诊断。',
+  );
+}
+
+function assertRequiredCommandsSucceed() {
+  const root = path.join(tmpRoot, 'required-command-ok');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  prepareCommandBundle(
+    root,
+    '20260617T030000Z-rollback-apply-pingora-direct-rollback-apply',
+    'rollback-apply',
+    'pingora-direct-rollback-apply',
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+    '--require-command',
+    'rollback-apply:pingora-direct-rollback-apply',
+    '--require-command-executable',
+    'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+    '--require-command-executable',
+    'rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+  ]);
+  assertStatus(result, 0, '要求的 enable / rollback 命令证据齐全时应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '命令证据审计 stdout');
+  assertEqual(output.ok, true, '命令证据审计 stdout 必须 ok=true。');
+  assertEqual(output.checkedCount, 2, '命令证据审计必须检查两项 command。');
+  assertEqual(output.phases?.length, 0, '只要求 command 时不应隐式检查 phase。');
+  assertEqual(
+    output.commands?.every((command) => command.status === 'OK'),
+    true,
+    '命令证据审计每个 command 都应 OK。',
+  );
+  assertEqual(
+    output.commands?.every(
+      (command) => command.verify?.requireSummaryOk === true,
+    ),
+    true,
+    '命令证据审计必须让 verifier 启用 --require-summary-ok。',
+  );
+  assertEqual(
+    output.commands?.[0]?.commandName,
+    'pingora-direct-enable-apply',
+    '命令证据审计必须输出 commandName。',
+  );
+  assertEqual(
+    output.commands?.[0]?.requiredExecutable,
+    '/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+    '命令证据审计必须输出 requiredExecutable。',
+  );
+  assertEqual(
+    Array.isArray(output.commands?.[0]?.requiredArgs),
+    true,
+    '命令证据审计必须输出 requiredArgs。',
+  );
+}
+
+function assertRequiredCommandExecutableImplicitlyRequiresCommand() {
+  const root = path.join(tmpRoot, 'required-command-executable-only-ok');
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command-executable',
+    'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+  ]);
+  assertStatus(
+    result,
+    0,
+    '--require-command-executable 必须隐式要求对应命令证据并通过身份校验。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '仅要求命令真实脚本身份审计 stdout');
+  assertEqual(
+    output.checkedCount,
+    1,
+    '--require-command-executable 必须让总审计检查对应 command。',
+  );
+  assertEqual(
+    output.commands?.[0]?.requiredExecutable,
+    '/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+    '--require-command-executable 隐式命令审计必须输出 requiredExecutable。',
+  );
+}
+
+function assertRequiredCommandArgImplicitlyRequiresCommand() {
+  const root = path.join(tmpRoot, 'required-command-arg-only-ok');
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command-arg',
+    'enable-apply:pingora-direct-enable-apply:--apply',
+  ]);
+  assertStatus(
+    result,
+    0,
+    '--require-command-arg 必须隐式要求对应命令证据并通过 args 校验。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '仅要求命令必需参数审计 stdout');
+  assertEqual(
+    output.checkedCount,
+    1,
+    '--require-command-arg 必须让总审计检查对应 command。',
+  );
+  assertEqual(
+    output.commands?.[0]?.requiredArgs?.includes('--apply'),
+    true,
+    '--require-command-arg 隐式命令审计必须输出 requiredArgs。',
+  );
+}
+
+function assertRequiredCommandExecutableMismatchFails() {
+  const root = path.join(tmpRoot, 'required-command-executable-mismatch');
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+    '--require-command-executable',
+    'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+  ]);
+  assertStatus(result, 1, '命令证据真实脚本与要求不一致时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest.expectedExecutable 必须是',
+    'expectedExecutable 不匹配必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command.executable 必须是',
+    'command.executable 不匹配必须给出明确诊断。',
+  );
+}
+
+function assertInvalidTopLevelExpectedExecutableFails() {
+  const root = path.join(tmpRoot, 'invalid-top-level-expected-executable');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  manifest.expectedExecutable = '';
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '顶层 manifest.expectedExecutable 为空时必须作为坏 manifest 失败，不能退化成未声明字段。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.expectedExecutable 必须是绝对路径',
+    '顶层 expectedExecutable 为空必须给出字段诊断。',
+  );
+}
+
+function assertInvalidEmbeddedExpectedExecutableFails() {
+  const root = path.join(tmpRoot, 'invalid-embedded-expected-executable');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  delete manifest.expectedExecutable;
+  manifest.command = {
+    ...manifest.command,
+    expectedExecutable: 'scripts/deploy/pingora-direct-enable.sh',
+  };
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '内嵌 manifest.command.expectedExecutable 为相对路径时必须作为坏 manifest 失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.expectedExecutable 必须是绝对路径',
+    '内嵌 expectedExecutable 相对路径必须给出字段诊断。',
+  );
+}
+
+function assertManifestCommandExecutableMismatchExpectedFails() {
+  const root = path.join(tmpRoot, 'command-executable-mismatch-expected');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  const commandRecordPath = path.join(bundleDir, 'command-record.json');
+  const commandRecord = readJson(commandRecordPath, '命令记录 JSON');
+  const rollbackExecutable =
+    '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh';
+  const driftedRecord = {
+    ...commandRecord,
+    executable: rollbackExecutable,
+    command: `${rollbackExecutable} --apply`,
+  };
+  writeJson(commandRecordPath, driftedRecord);
+  manifest.command = driftedRecord;
+  manifest.files.commandRecord = metadataFor(commandRecordPath);
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '命令证据声明 expectedExecutable 后，真实 executable 与之不一致时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.executable 必须是',
+    'manifest.command executable 与 expectedExecutable 漂移必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command-record.json.executable 必须是',
+    'command-record executable 与 expectedExecutable 漂移必须给出明确诊断。',
+  );
+}
+
+function assertRelativeCommandExecutableFails() {
+  const root = path.join(tmpRoot, 'relative-command-executable');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  const commandRecordPath = path.join(bundleDir, 'command-record.json');
+  const commandRecord = readJson(commandRecordPath, '命令记录 JSON');
+  const relativeExecutable = 'scripts/deploy/pingora-direct-enable.sh';
+  const driftedRecord = {
+    ...commandRecord,
+    executable: relativeExecutable,
+    command: `${relativeExecutable} --apply`,
+  };
+  writeJson(commandRecordPath, driftedRecord);
+  manifest.command = driftedRecord;
+  manifest.files.commandRecord = metadataFor(commandRecordPath);
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '命令证据真实 executable 为相对路径时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.executable 必须是绝对路径',
+    'manifest.command executable 相对路径必须给出字段诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command-record.json.executable 必须是绝对路径',
+    'command-record executable 相对路径必须给出字段诊断。',
+  );
+}
+
+function assertMissingCommandExecutableFails() {
+  const root = path.join(tmpRoot, 'missing-command-executable');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  const commandRecordPath = path.join(bundleDir, 'command-record.json');
+  const commandRecord = readJson(commandRecordPath, '命令记录 JSON');
+  delete commandRecord.expectedExecutable;
+  delete commandRecord.executable;
+  commandRecord.command = '/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply';
+  writeJson(commandRecordPath, commandRecord);
+  delete manifest.expectedExecutable;
+  manifest.command = { ...commandRecord };
+  manifest.files.commandRecord = metadataFor(commandRecordPath);
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '命令证据缺少真实 executable 时必须失败，即使 command 字符串存在。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.executable 必须是绝对路径',
+    'manifest.command 缺少 executable 必须给出字段诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command-record.json.executable 必须是绝对路径',
+    'command-record 缺少 executable 必须给出字段诊断。',
+  );
+}
+
+function assertRequiredCommandArgMissingFails() {
+  const root = path.join(tmpRoot, 'required-command-arg-missing');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  const commandRecordPath = path.join(bundleDir, 'command-record.json');
+  const commandRecord = readJson(commandRecordPath, '命令记录 JSON');
+  const dryRunRecord = {
+    ...commandRecord,
+    args: ['--dry-run'],
+    command: `${commandRecord.executable} --dry-run`,
+  };
+  writeJson(commandRecordPath, dryRunRecord);
+  manifest.command = dryRunRecord;
+  manifest.files.commandRecord = metadataFor(commandRecordPath);
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command-arg',
+    'enable-apply:pingora-direct-enable-apply:--apply',
+  ]);
+  assertStatus(result, 1, '命令证据缺少必需 --apply 参数时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest.command.args 必须包含 \\"--apply\\"',
+    'manifest.command 缺少必需参数必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command-record.json.args 必须包含 \\"--apply\\"',
+    'command-record 缺少必需参数必须给出明确诊断。',
+  );
+}
+
+function assertCommandRecordMismatchFails() {
+  const root = path.join(tmpRoot, 'command-record-mismatch');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  const driftedRecord = {
+    ...manifest.command,
+    expectedExecutable:
+      '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+    executable: '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+    command:
+      '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply',
+  };
+  writeJson(path.join(bundleDir, 'command-record.json'), driftedRecord);
+  manifest.files.commandRecord = metadataFor(
+    path.join(bundleDir, 'command-record.json'),
+  );
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+    '--require-command-executable',
+    'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+  ]);
+  assertStatus(
+    result,
+    1,
+    'command-record.json 与 manifest.command 语义漂移时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command-record.json.executable 必须是',
+    'command-record executable 漂移必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.executable 与 command-record.json.executable 必须一致',
+    'manifest.command 与 command-record 不一致必须给出明确诊断。',
+  );
+}
+
+function assertCommandRecordTimelineMismatchFails() {
+  const root = path.join(tmpRoot, 'command-record-timeline-mismatch');
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+    {
+      generatedAt: '2026-06-17T01:59:59.000Z',
+      startedAt: '2026-06-17T02:00:00.000Z',
+      finishedAt: '2026-06-17T02:00:03.000Z',
+    },
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    'manifest.generatedAt 早于命令 finishedAt 时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.generatedAt 不能早于 manifest.command.finishedAt',
+    'manifest.command finishedAt 晚于 generatedAt 必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.generatedAt 不能早于 command-record.json.finishedAt',
+    'command-record finishedAt 晚于 generatedAt 必须给出明确诊断。',
+  );
+}
+
+function assertCommandRecordOutputPathMismatchFails() {
+  const root = path.join(tmpRoot, 'command-record-output-path-mismatch');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const commandRecordPath = path.join(bundleDir, 'command-record.json');
+  const commandRecord = readJson(commandRecordPath, '命令记录 JSON');
+  writeJson(commandRecordPath, {
+    ...commandRecord,
+    stdoutPath: 'manual.stdout.txt',
+  });
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  manifest.files.commandRecord = metadataFor(commandRecordPath);
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    'command-record.json 的 stdoutPath 与 manifest.files.stdout.path 漂移时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command-record.json.stdoutPath 必须是',
+    'command-record stdoutPath 漂移必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.stdoutPath 与 command-record.json.stdoutPath 必须一致',
+    'manifest.command 与 command-record stdoutPath 不一致必须给出明确诊断。',
+  );
+}
+
+function assertCommandRecordArgsMismatchFails() {
+  const root = path.join(tmpRoot, 'command-record-args-mismatch');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const commandRecordPath = path.join(bundleDir, 'command-record.json');
+  const commandRecord = readJson(commandRecordPath, '命令记录 JSON');
+  writeJson(commandRecordPath, {
+    ...commandRecord,
+    args: ['--dry-run'],
+    command: `${commandRecord.executable} --dry-run`,
+  });
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  manifest.files.commandRecord = metadataFor(commandRecordPath);
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    'command-record.json 的 args / command 与 manifest.command 漂移时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.args 与 command-record.json.args 必须一致',
+    'command-record args 漂移必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.command 与 command-record.json.command 必须一致',
+    'command-record command 漂移必须给出明确诊断。',
+  );
+}
+
+function assertCommandRecordArgsControlCharacterFails() {
+  const root = path.join(tmpRoot, 'command-record-args-control-character');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  const commandRecordPath = path.join(bundleDir, 'command-record.json');
+  const commandRecord = readJson(commandRecordPath, '命令记录 JSON');
+  const taintedRecord = {
+    ...commandRecord,
+    args: ['--apply', '--note=line1\nline2'],
+    command: `${commandRecord.executable} --apply --note=line1`,
+  };
+  writeJson(commandRecordPath, taintedRecord);
+  manifest.command = taintedRecord;
+  manifest.files.commandRecord = metadataFor(commandRecordPath);
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '命令证据 args 含换行控制字符时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.args 不能包含换行或 NUL 字符',
+    'manifest.command args 控制字符必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command-record.json.args 不能包含换行或 NUL 字符',
+    'command-record args 控制字符必须给出明确诊断。',
+  );
+}
+
+function assertCommandNameMismatchFails() {
+  const root = path.join(tmpRoot, 'command-name-mismatch');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  manifest.command = {
+    ...manifest.command,
+    name: 'pingora-direct-rollback-apply',
+  };
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    'manifest.commandName 与 manifest.command.name 漂移时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.commandName 与 manifest.command.name 必须一致',
+    '命令名双字段漂移必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'pingora-direct-enable-apply',
+    '命令名双字段漂移诊断必须包含顶层 commandName。',
+  );
+  assertIncludes(
+    result.stdout,
+    'pingora-direct-rollback-apply',
+    '命令名双字段漂移诊断必须包含内嵌 command.name。',
+  );
+}
+
+function assertInvalidTopLevelCommandNameFails() {
+  const root = path.join(tmpRoot, 'invalid-top-level-command-name');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  manifest.commandName = '';
+  delete manifest.command.name;
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '顶层 manifest.commandName 为空时必须作为坏 manifest 失败，不能退化成阶段证据。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.commandName 只能包含 ASCII',
+    '顶层 commandName 为空必须给出字段诊断。',
+  );
+}
+
+function assertInvalidEmbeddedCommandNameFails() {
+  const root = path.join(tmpRoot, 'invalid-embedded-command-name');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  delete manifest.commandName;
+  manifest.command = {
+    ...manifest.command,
+    name: '',
+  };
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '内嵌 manifest.command.name 为空时必须作为坏 manifest 失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.name 只能包含 ASCII',
+    '内嵌 command.name 为空必须给出字段诊断。',
+  );
+}
+
+function assertFullCutoverTimelineSucceed() {
+  const root = path.join(tmpRoot, 'full-timeline-ok');
+  prepareFullCutoverTimeline(root, {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+    postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-17T04:00:00.000Z',
+    postRollback: '2026-06-17T05:00:00.000Z',
+  });
+
+  const result = runFullCutoverAudit(root);
+  assertStatus(result, 0, '完整标准切换时间线顺序正确时应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '完整切换时间线审计 stdout');
+  assertEqual(output.timeline?.checked, true, '完整切换时间线必须被检查。');
+  assertEqual(output.timeline?.ok, true, '完整切换时间线顺序正确时 timeline.ok 必须为 true。');
+  assertEqual(
+    output.timeline?.maxSpanMs,
+    86400000,
+    '完整切换时间线默认最大跨度必须是 24 小时。',
+  );
+  assertEqual(
+    output.timeline?.spanMs,
+    14400000,
+    '完整切换时间线必须输出实际跨度。',
+  );
+  assertEqual(output.checkedCount, 8, '完整切换时间线总审计必须检查三阶段和五条命令。');
+  assertEqual(
+    output.summary?.status,
+    'OK',
+    '完整切换时间线总审计通过时 operator summary.status 必须是 OK。',
+  );
+  assertEqual(
+    output.summary?.directLiveEvidence?.[0]?.phase,
+    'post-enable',
+    '完整切换时间线 operator summary 必须突出 post-enable direct live 证据。',
+  );
+  assertEqual(
+    output.summary?.directLiveEvidence?.[0]?.accessLog?.ok,
+    true,
+    '完整切换时间线 operator summary 必须标记 access log 摘要通过。',
+  );
+  assertEqual(
+    output.summary?.directLiveEvidence?.[0]?.staticHeaders?.ok,
+    true,
+    '完整切换时间线 operator summary 必须标记静态头摘要通过。',
+  );
+  const postEnablePhase = output.phases?.find(
+    (phase) => phase.phase === 'post-enable',
+  );
+  assertEqual(
+    postEnablePhase?.requiredDirectLiveStaticHeaders,
+    true,
+    '完整切换时间线总审计必须默认要求 post-enable direct live 静态头摘要。',
+  );
+  assertEqual(
+    postEnablePhase?.requiredDirectLiveAccessLog,
+    true,
+    '完整切换时间线总审计必须默认要求 post-enable direct live access log 摘要。',
+  );
+  const postRollbackPhase = output.phases?.find(
+    (phase) => phase.phase === 'post-rollback',
+  );
+  assertEqual(
+    postRollbackPhase?.requiredPingoraEnvShadow,
+    true,
+    '完整切换时间线总审计必须默认要求 post-rollback Pingora env shadow 摘要。',
+  );
+  assertEqual(
+    output.summary?.pingoraEnvShadowEvidence?.[0]?.shadow?.ok,
+    true,
+    '完整切换时间线 operator summary 必须标记 post-rollback Pingora env shadow 摘要通过。',
+  );
+}
+
+function assertFullCutoverTimelineFailsWhenPostEnableAccessLogMissing() {
+  const root = path.join(tmpRoot, 'full-timeline-missing-access-log');
+  prepareFullCutoverTimeline(
+    root,
+    {
+      preCutover: '2026-06-17T01:00:00.000Z',
+      enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+      postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+      rollbackApply: '2026-06-17T04:00:00.000Z',
+      postRollback: '2026-06-17T05:00:00.000Z',
+    },
+    { postEnableDirectLiveAccessLog: false },
+  );
+
+  const result = runFullCutoverAudit(root);
+  assertStatus(
+    result,
+    1,
+    '正式 runbook 风格总审计遇到缺 directLiveAccessLog 的 post-enable 旧证据包必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.directLiveAccessLog',
+    '完整时间线缺 post-enable access log 摘要时必须给出 directLiveAccessLog 诊断。',
+  );
+  const output = parseJson(result.stdout, '缺 access log 完整时间线审计 stdout');
+  assertEqual(
+    output.summary?.status,
+    'CRITICAL',
+    '缺 access log 摘要时 operator summary.status 必须是 CRITICAL。',
+  );
+  assertEqual(
+    output.summary?.failedItems?.[0]?.phase,
+    'post-enable',
+    '缺 access log 摘要时 operator summary.failedItems 必须指出 post-enable。',
+  );
+  assertEqual(
+    output.summary?.directLiveEvidence?.[0]?.accessLog?.ok,
+    false,
+    '缺 access log 摘要时 operator summary.directLiveEvidence 必须标记 accessLog.ok=false。',
+  );
+  assertIncludes(
+    output.summary?.directLiveEvidence?.[0]?.accessLog?.reason || '',
+    '字段缺失或不是对象',
+    '缺 access log 摘要时 operator summary 必须给出短 reason。',
+  );
+}
+
+function assertFullCutoverTimelineFailsWhenPostEnableStaticHeadersMissing() {
+  const root = path.join(tmpRoot, 'full-timeline-missing-static-headers');
+  prepareFullCutoverTimeline(
+    root,
+    {
+      preCutover: '2026-06-17T01:00:00.000Z',
+      enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+      postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+      rollbackApply: '2026-06-17T04:00:00.000Z',
+      postRollback: '2026-06-17T05:00:00.000Z',
+    },
+    { postEnableDirectLiveSummary: false },
+  );
+
+  const result = runFullCutoverAudit(root);
+  assertStatus(
+    result,
+    1,
+    '正式 runbook 风格总审计遇到缺 directLiveStaticHeaders 的 post-enable 旧证据包必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.directLiveStaticHeaders',
+    '完整时间线缺 post-enable 静态头摘要时必须给出 directLiveStaticHeaders 诊断。',
+  );
+  const output = parseJson(result.stdout, '缺静态头完整时间线审计 stdout');
+  assertEqual(
+    output.summary?.status,
+    'CRITICAL',
+    '缺静态头摘要时 operator summary.status 必须是 CRITICAL。',
+  );
+  assertEqual(
+    output.summary?.failedItems?.[0]?.phase,
+    'post-enable',
+    '缺静态头摘要时 operator summary.failedItems 必须指出 post-enable。',
+  );
+  assertEqual(
+    output.summary?.directLiveEvidence?.[0]?.staticHeaders?.ok,
+    false,
+    '缺静态头摘要时 operator summary.directLiveEvidence 必须标记 staticHeaders.ok=false。',
+  );
+  assertIncludes(
+    output.summary?.directLiveEvidence?.[0]?.staticHeaders?.reason || '',
+    '字段缺失或不是对象',
+    '缺静态头摘要时 operator summary 必须给出短 reason。',
+  );
+}
+
+function assertFullCutoverTimelineWithRunIdSucceed() {
+  const root = path.join(tmpRoot, 'full-timeline-run-id-ok');
+  prepareFullCutoverTimeline(
+    root,
+    {
+      preCutover: '2026-06-17T01:00:00.000Z',
+      enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+      postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+      rollbackApply: '2026-06-17T04:00:00.000Z',
+      postRollback: '2026-06-17T05:00:00.000Z',
+    },
+    { cutoverRunId: 'cutover-20260617T010000Z' },
+  );
+
+  const result = runFullCutoverAudit(root, [
+    '--require-cutover-run-id',
+    'cutover-20260617T010000Z',
+  ]);
+  assertStatus(result, 0, '完整标准切换时间线同一 cutoverRunId 时应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '同批次完整切换时间线审计 stdout');
+  assertEqual(
+    output.requiredCutoverRunId,
+    'cutover-20260617T010000Z',
+    '审计 stdout 必须记录要求的 cutoverRunId。',
+  );
+  assertEqual(
+    output.phases?.every(
+      (phase) => phase.cutoverRunId === 'cutover-20260617T010000Z',
+    ),
+    true,
+    '每个 phase 输出都必须记录匹配的 cutoverRunId。',
+  );
+  assertEqual(
+    output.commands?.every(
+      (command) => command.cutoverRunId === 'cutover-20260617T010000Z',
+    ),
+    true,
+    '每个 command 输出都必须记录匹配的 cutoverRunId。',
+  );
+  assertEqual(
+    output.timeline?.items?.every(
+      (item) => item.cutoverRunId === 'cutover-20260617T010000Z',
+    ),
+    true,
+    '标准切换时间线条目必须输出匹配的 cutoverRunId。',
+  );
+}
+
+function assertLongCutoverTimelineFails() {
+  const root = path.join(tmpRoot, 'long-timeline');
+  prepareFullCutoverTimeline(root, {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+    postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-18T04:00:00.000Z',
+    postRollback: '2026-06-18T05:00:00.000Z',
+  });
+
+  const result = runFullCutoverAudit(root);
+  assertStatus(result, 1, '完整标准切换时间线超过默认 24 小时时必须失败。');
+  assertIncludes(
+    result.stdout,
+    '时间跨度',
+    '完整标准切换时间线跨度过大必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    '"maxSpanMs": 86400000',
+    '完整标准切换时间线跨度过大必须输出默认最大跨度。',
+  );
+  assertIncludes(
+    result.stdout,
+    '"spanMs": 100800000',
+    '完整标准切换时间线跨度过大必须输出实际跨度。',
+  );
+}
+
+function assertTimelineMaxSpanOverrideSucceed() {
+  const root = path.join(tmpRoot, 'long-timeline-override');
+  prepareFullCutoverTimeline(root, {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+    postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-18T04:00:00.000Z',
+    postRollback: '2026-06-18T05:00:00.000Z',
+  });
+
+  const result = runFullCutoverAudit(root, ['--timeline-max-span-ms', '172800000']);
+  assertStatus(result, 0, '显式放宽切换时间线最大跨度后应允许长窗口证据。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '放宽跨度切换时间线审计 stdout');
+  assertEqual(output.timeline?.ok, true, '放宽跨度后 timeline.ok 必须为 true。');
+  assertEqual(
+    output.timeline?.maxSpanMs,
+    172800000,
+    '放宽跨度后 timeline.maxSpanMs 必须反映 CLI 参数。',
+  );
+  assertEqual(
+    output.timeline?.spanMs,
+    100800000,
+    '放宽跨度后 timeline.spanMs 仍必须输出实际跨度。',
+  );
+}
+
+function assertTimelineNonOkItemFails() {
+  const root = path.join(tmpRoot, 'timeline-non-ok-item');
+  prepareFullCutoverTimeline(root, {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+    postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-17T04:00:00.000Z',
+    postRollback: '2026-06-17T05:00:00.000Z',
+  });
+  const preCutoverManifestPath = path.join(
+    root,
+    '20260617T010000Z-pre-cutover',
+    'manifest.json',
+  );
+  const preCutoverManifest = readJson(
+    preCutoverManifestPath,
+    '切换前证据 manifest',
+  );
+  preCutoverManifest.summary.status = 'CRITICAL';
+  writeJson(preCutoverManifestPath, preCutoverManifest);
+  const postEnableManifestPath = path.join(
+    root,
+    '20260617T030000Z-post-enable',
+    'manifest.json',
+  );
+  const postEnableManifest = readJson(
+    postEnableManifestPath,
+    '启用后证据 manifest',
+  );
+  postEnableManifest.summary.status = 'CRITICAL';
+  writeJson(postEnableManifestPath, postEnableManifest);
+
+  const result = runFullCutoverAudit(root);
+  assertStatus(result, 1, '标准八段时间线包含非 OK 条目时 timeline 必须失败。');
+  assertIncludes(
+    result.stdout,
+    '标准切换时间线包含非 OK 证据',
+    'timeline 非 OK 条目必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'post-enable=MANIFEST_FAILED',
+    'timeline 非 OK 条目诊断必须指出具体阶段状态。',
+  );
+  assertIncludes(
+    result.stdout,
+    '"ok": false',
+    'timeline 非 OK 条目必须让输出中可见 ok=false。',
+  );
+  const output = parseJson(result.stdout, '非 OK 时间线审计 stdout');
+  assertEqual(
+    output.timeline?.failedCount,
+    2,
+    'timeline.failedCount 必须按非 OK 条目数量计数，不能只记一个笼统失败。',
+  );
+  assertEqual(
+    output.timeline?.failureBreakdown?.nonOkItems,
+    2,
+    'timeline.failureBreakdown 必须输出非 OK 条目数量，便于现场定位。',
+  );
+}
+
+function assertMixedTimelineCutoverRunIdFails() {
+  const root = path.join(tmpRoot, 'mixed-timeline-cutover-run-id');
+  prepareFullCutoverTimeline(
+    root,
+    {
+      preCutover: '2026-06-17T01:00:00.000Z',
+      enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+      postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+      rollbackApply: '2026-06-17T04:00:00.000Z',
+      postRollback: '2026-06-17T05:00:00.000Z',
+    },
+    { cutoverRunId: 'cutover-window-a' },
+  );
+  const postRollbackManifestPath = path.join(
+    root,
+    '20260617T050000Z-post-rollback',
+    'manifest.json',
+  );
+  const postRollbackManifest = readJson(
+    postRollbackManifestPath,
+    '回退后证据 manifest',
+  );
+  postRollbackManifest.cutoverRunId = 'cutover-window-b';
+  writeJson(postRollbackManifestPath, postRollbackManifest);
+
+  const result = runFullCutoverAudit(root);
+  assertStatus(result, 1, '完整标准时间线混入不同 cutoverRunId 时必须失败。');
+  assertIncludes(
+    result.stdout,
+    '不同 cutoverRunId',
+    '完整标准时间线混入不同 cutoverRunId 必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'post-rollback=\\"cutover-window-b\\"',
+    '完整标准时间线 cutoverRunId 漂移必须指出具体阶段。',
+  );
+  assertIncludes(
+    result.stdout,
+    'cutover-window-a',
+    '完整标准时间线 cutoverRunId 漂移必须输出原批次。',
+  );
+}
+
+function assertPartialTimelineCutoverRunIdFails() {
+  const root = path.join(tmpRoot, 'partial-timeline-cutover-run-id');
+  prepareFullCutoverTimeline(
+    root,
+    {
+      preCutover: '2026-06-17T01:00:00.000Z',
+      enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+      postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+      rollbackApply: '2026-06-17T04:00:00.000Z',
+      postRollback: '2026-06-17T05:00:00.000Z',
+    },
+    { cutoverRunId: 'cutover-window-a' },
+  );
+  const enableManifestPath = path.join(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'manifest.json',
+  );
+  const enableManifest = readJson(enableManifestPath, '启用命令证据 manifest');
+  delete enableManifest.cutoverRunId;
+  delete enableManifest.command.cutoverRunId;
+  writeJson(enableManifestPath, enableManifest);
+
+  const result = runFullCutoverAudit(root);
+  assertStatus(result, 1, '完整标准时间线部分缺少 cutoverRunId 时必须失败。');
+  assertIncludes(
+    result.stdout,
+    '缺少 cutoverRunId',
+    '完整标准时间线部分缺少 cutoverRunId 必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'enable-apply:pingora-direct-enable-apply=<missing>',
+    '完整标准时间线部分缺少 cutoverRunId 必须指出具体命令证据。',
+  );
+}
+
+function assertEmptyCutoverRunIdFails() {
+  const root = path.join(tmpRoot, 'empty-cutover-run-id');
+  const bundleDir = prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '阶段证据 manifest');
+  manifest.cutoverRunId = '';
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+  ]);
+  assertStatus(
+    result,
+    1,
+    'manifest.cutoverRunId 字段存在但为空时必须失败，不能当作缺省字段。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.cutoverRunId 只能包含 ASCII',
+    '空 cutoverRunId 必须给出字段诊断。',
+  );
+}
+
+function assertCutoverRunIdMismatchFails() {
+  const root = path.join(tmpRoot, 'cutover-run-id-mismatch');
+  prepareFullCutoverTimeline(
+    root,
+    {
+      preCutover: '2026-06-17T01:00:00.000Z',
+      enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+      postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+      rollbackApply: '2026-06-17T04:00:00.000Z',
+      postRollback: '2026-06-17T05:00:00.000Z',
+    },
+    { cutoverRunId: 'other-cutover-window' },
+  );
+
+  const result = runFullCutoverAudit(root, [
+    '--require-cutover-run-id',
+    'cutover-20260617T010000Z',
+  ]);
+  assertStatus(result, 1, '要求 cutoverRunId 时不应接受其它切换批次证据。');
+  assertIncludes(
+    result.stdout,
+    'cutoverRunId=cutover-20260617T010000Z',
+    'cutoverRunId 不匹配时必须在诊断中写出要求的批次 ID。',
+  );
+  assertIncludes(
+    result.stdout,
+    '其它切换批次',
+    'cutoverRunId 不匹配时必须说明已有证据属于其它切换批次。',
+  );
+}
+
+function assertMissingCutoverRunIdFailsWhenRequired() {
+  const root = path.join(tmpRoot, 'missing-cutover-run-id');
+  prepareFullCutoverTimeline(root, {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+    postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-17T04:00:00.000Z',
+    postRollback: '2026-06-17T05:00:00.000Z',
+  });
+
+  const result = runFullCutoverAudit(root, [
+    '--require-cutover-run-id',
+    'cutover-20260617T010000Z',
+  ]);
+  assertStatus(result, 1, '要求 cutoverRunId 时缺少批次 ID 的旧证据必须失败。');
+  assertIncludes(
+    result.stdout,
+    '缺少 cutoverRunId',
+    '缺少 cutoverRunId 时必须给出明确诊断。',
+  );
+}
+
+function assertMissingGeneratedAtFails() {
+  const root = path.join(tmpRoot, 'missing-generated-at');
+  const bundleDir = prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '阶段证据 manifest');
+  delete manifest.generatedAt;
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+  ]);
+  assertStatus(result, 1, '阶段证据缺少 manifest.generatedAt 时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest.generatedAt 必须是合法 ISO 时间',
+    '阶段证据缺少 generatedAt 必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    '不能依赖目录 mtime',
+    '阶段证据缺少 generatedAt 时必须说明不能用目录 mtime 兜底。',
+  );
+}
+
+function assertInvalidCommandGeneratedAtFails() {
+  const root = path.join(tmpRoot, 'invalid-command-generated-at');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  manifest.generatedAt = 'not-a-time';
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(result, 1, '命令证据 manifest.generatedAt 非法时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest.generatedAt 必须是合法 ISO 时间',
+    '命令证据 generatedAt 非法必须给出明确诊断。',
+  );
+}
+
+function assertNonCanonicalGeneratedAtFails() {
+  const root = path.join(tmpRoot, 'non-canonical-generated-at');
+  const bundleDir = prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '阶段证据 manifest');
+  manifest.generatedAt = '2026-06-17T01:00:00Z';
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '阶段证据 manifest.generatedAt 缺少毫秒时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.generatedAt 必须是合法 ISO 时间',
+    '非规范 generatedAt 必须给出明确诊断。',
+  );
+}
+
+function assertNonCanonicalCommandRecordTimesFail() {
+  const root = path.join(tmpRoot, 'non-canonical-command-times');
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+    {
+      startedAt: '2026-06-17T02:00:00Z',
+      finishedAt: '2026-06-17T02:00:03Z',
+    },
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '命令记录时间缺少毫秒时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.startedAt 必须是合法 ISO 时间',
+    'manifest.command 非规范 startedAt 必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'command-record.json.finishedAt 必须是合法 ISO 时间',
+    'command-record 非规范 finishedAt 必须给出明确诊断。',
+  );
+}
+
+function assertAmbiguousLatestPhaseFails() {
+  const root = path.join(tmpRoot, 'ambiguous-latest-phase');
+  prepareBundle(root, '20260617T010000Z-post-enable-a', 'post-enable', {
+    generatedAt: '2026-06-17T02:00:00.000Z',
+  });
+  prepareBundle(root, '20260617T010000Z-post-enable-b', 'post-enable', {
+    generatedAt: '2026-06-17T02:00:00.000Z',
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+  ]);
+  assertStatus(result, 1, '同阶段最新证据 generatedAt 重复时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'AMBIGUOUS_LATEST',
+    '同阶段最新证据 generatedAt 重复必须写入 AMBIGUOUS_LATEST。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.generatedAt=2026-06-17T02:00:00.000Z',
+    '同阶段最新证据 generatedAt 重复必须写出重复时间。',
+  );
+  assertIncludes(
+    result.stdout,
+    '20260617T010000Z-post-enable-a',
+    '同阶段最新证据 generatedAt 重复必须列出第一个证据目录。',
+  );
+  assertIncludes(
+    result.stdout,
+    '20260617T010000Z-post-enable-b',
+    '同阶段最新证据 generatedAt 重复必须列出第二个证据目录。',
+  );
+  assertIncludes(
+    result.stdout,
+    '不能按目录名打平选择',
+    '同阶段最新证据 generatedAt 重复必须说明不能靠目录名打平。',
+  );
+}
+
+function assertAmbiguousLatestCommandFails() {
+  const root = path.join(tmpRoot, 'ambiguous-latest-command');
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-a',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+    {
+      generatedAt: '2026-06-17T02:00:00.000Z',
+    },
+  );
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-b',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+    {
+      generatedAt: '2026-06-17T02:00:00.000Z',
+    },
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(result, 1, '同命令最新证据 generatedAt 重复时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'AMBIGUOUS_LATEST',
+    '同命令最新证据 generatedAt 重复必须写入 AMBIGUOUS_LATEST。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.generatedAt=2026-06-17T02:00:00.000Z',
+    '同命令最新证据 generatedAt 重复必须写出重复时间。',
+  );
+  assertIncludes(
+    result.stdout,
+    '20260617T020000Z-enable-apply-a',
+    '同命令最新证据 generatedAt 重复必须列出第一个证据目录。',
+  );
+  assertIncludes(
+    result.stdout,
+    '20260617T020000Z-enable-apply-b',
+    '同命令最新证据 generatedAt 重复必须列出第二个证据目录。',
+  );
+  assertIncludes(
+    result.stdout,
+    '不能按目录名打平选择',
+    '同命令最新证据 generatedAt 重复必须说明不能靠目录名打平。',
+  );
+}
+
+function assertMissingManifestSchemaVersionFails() {
+  const root = path.join(tmpRoot, 'missing-manifest-schema-version');
+  const bundleDir = prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '阶段证据 manifest');
+  delete manifest.schemaVersion;
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+  ]);
+  assertStatus(result, 1, '阶段证据 manifest 缺少 schemaVersion 时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest.schemaVersion 必须是 1',
+    '阶段证据缺少 manifest schemaVersion 必须给出明确诊断。',
+  );
+}
+
+function assertCommandRecordSchemaVersionMismatchFails() {
+  const root = path.join(tmpRoot, 'command-record-schema-version-mismatch');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const commandRecordPath = path.join(bundleDir, 'command-record.json');
+  const commandRecord = readJson(commandRecordPath, '命令记录 JSON');
+  writeJson(commandRecordPath, {
+    ...commandRecord,
+    schemaVersion: 2,
+  });
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '命令证据 manifest');
+  manifest.files.commandRecord = metadataFor(commandRecordPath);
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(result, 1, 'command-record.json schemaVersion 非 1 时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'command-record.json.schemaVersion 必须是 1',
+    '命令记录 schemaVersion 漂移必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.command.schemaVersion 与 command-record.json.schemaVersion 必须一致',
+    'manifest.command 与 command-record schemaVersion 不一致必须给出明确诊断。',
+  );
+}
+
+function assertCanAuditSinglePhase() {
+  const root = path.join(tmpRoot, 'single-phase');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--phase',
+    'pre-cutover',
+  ]);
+  assertStatus(result, 0, '只要求单个已有阶段时应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '单阶段证据审计 stdout');
+  assertEqual(output.checkedCount, 1, '单阶段证据审计只应检查一个 phase。');
+  assertEqual(
+    output.phases?.[0]?.latestBundleDir?.endsWith('pre-cutover'),
+    true,
+    '单阶段证据审计必须输出最新 bundleDir。',
+  );
+}
+
+function assertMissingPhaseFails() {
+  const root = path.join(tmpRoot, 'missing-phase');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+  ]);
+  assertStatus(result, 1, '要求的 phase 缺失时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'MISSING',
+    'phase 缺失失败必须写入 JSON status。',
+  );
+}
+
+function assertCommandBundleCannotSatisfyPhaseRequirement() {
+  const root = path.join(tmpRoot, 'command-bundle-not-phase');
+  prepareCommandBundle(
+    root,
+    '20260617T010000Z-post-enable-command',
+    'post-enable',
+    'pingora-direct-enable-apply',
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '命令证据不能满足同名 phase 的阶段证据要求。',
+  );
+  assertIncludes(
+    result.stdout,
+    'MISSING',
+    '命令证据冒充阶段证据时必须写入 MISSING。',
+  );
+  assertIncludes(
+    result.stdout,
+    '没有找到该阶段的证据 manifest',
+    '命令证据冒充阶段证据时必须给出缺少阶段证据的诊断。',
+  );
+}
+
+function assertMissingCommandFails() {
+  const root = path.join(tmpRoot, 'missing-command');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(result, 1, '要求的 command 证据缺失时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'MISSING',
+    'command 缺失失败必须写入 JSON status。',
+  );
+  assertIncludes(
+    result.stdout,
+    'pingora-direct-enable-apply',
+    'command 缺失失败必须写入 commandName。',
+  );
+}
+
+function assertOutOfOrderCutoverTimelineFails() {
+  const root = path.join(tmpRoot, 'out-of-order-timeline');
+  prepareFullCutoverTimeline(root, {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T03:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T03:10:00.000Z',
+    postEnable: '2026-06-17T02:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-17T04:00:00.000Z',
+    postRollback: '2026-06-17T05:00:00.000Z',
+  });
+
+  const result = runFullCutoverAudit(root);
+  assertStatus(result, 1, '完整标准切换时间线倒序时必须失败。');
+  assertIncludes(
+    result.stdout,
+    '疑似混入不同切换窗口证据',
+    '完整标准切换时间线倒序必须给出明确诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    '"checked": true',
+    '完整标准切换时间线倒序时必须显示 timeline 已检查。',
+  );
+}
+
+function assertCriticalPhaseSummaryFails() {
+  const root = path.join(tmpRoot, 'critical-phase-summary');
+  prepareBundle(root, '20260617T010000Z-post-enable', 'post-enable', {
+    summaryStatus: 'CRITICAL',
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+  ]);
+  assertStatus(result, 1, '最新阶段证据 manifest summary 非 OK 时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'MANIFEST_FAILED',
+    '阶段证据 summary 非 OK 必须写入 MANIFEST_FAILED。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.status 必须是 OK',
+    '阶段证据 summary 非 OK 必须给出明确诊断。',
+  );
+}
+
+function assertFailedCommandSummaryFails() {
+  const root = path.join(tmpRoot, 'failed-command-summary');
+  prepareCommandBundle(
+    root,
+    '20260617T010000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+    {
+      summaryStatus: 'FAILED',
+      exitCode: 1,
+    },
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(result, 1, '最新命令证据 manifest summary 失败时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'MANIFEST_FAILED',
+    '命令证据 summary 失败必须写入 MANIFEST_FAILED。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.exitCode 必须是 0',
+    '命令证据 exitCode 非 0 必须给出明确诊断。',
+  );
+}
+
+function assertLatestBrokenBundleFails() {
+  const root = path.join(tmpRoot, 'latest-broken');
+  prepareBundle(root, '20260617T010000Z-post-enable', 'post-enable', {
+    generatedAt: '2026-06-17T01:00:00.000Z',
+  });
+  const latest = prepareBundle(root, '20260617T020000Z-post-enable', 'post-enable', {
+    generatedAt: '2026-06-17T02:00:00.000Z',
+  });
+  writeFileSync(path.join(latest, 'snapshot.json'), '{"ok":false}\n', 'utf8');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-enable',
+  ]);
+  assertStatus(result, 1, '同阶段最新证据损坏时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'VERIFY_FAILED',
+    '最新证据损坏必须写入 VERIFY_FAILED。',
+  );
+  assertIncludes(
+    result.stdout,
+    'latest-broken/20260617T020000Z-post-enable',
+    '失败输出必须指向最新 bundleDir。',
+  );
+}
+
+function assertLatestBrokenCommandBundleFails() {
+  const root = path.join(tmpRoot, 'latest-broken-command');
+  prepareCommandBundle(
+    root,
+    '20260617T010000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+    {
+      generatedAt: '2026-06-17T01:00:00.000Z',
+    },
+  );
+  const latest = prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+    {
+      generatedAt: '2026-06-17T02:00:00.000Z',
+    },
+  );
+  writeFileSync(path.join(latest, 'command.stdout.txt'), 'drifted\n', 'utf8');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(result, 1, '同命令最新证据损坏时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'VERIFY_FAILED',
+    '最新命令证据损坏必须写入 VERIFY_FAILED。',
+  );
+  assertIncludes(
+    result.stdout,
+    '最新命令证据目录 manifest 验真失败',
+    '最新命令证据损坏必须给出 command 诊断。',
+  );
+}
+
+function assertManifestDiagnosticsFailAudit() {
+  const root = path.join(tmpRoot, 'diagnostic');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  const badDir = path.join(root, '20260617T020000Z-bad');
+  mkdirSync(badDir, { recursive: true });
+  writeFileSync(path.join(badDir, 'manifest.json'), '{ bad json\n', 'utf8');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+  ]);
+  assertStatus(result, 1, '证据根目录存在坏 manifest 诊断时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest 不是合法 JSON',
+    '坏 manifest 必须出现在 diagnostics 中。',
+  );
+}
+
+function assertExtraRootFileFailsByDefault() {
+  const root = path.join(tmpRoot, 'extra-root-file');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  writeFileSync(path.join(root, 'operator-note.txt'), 'manual note\n', 'utf8');
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+  ]);
+  assertStatus(result, 1, '证据根目录混入普通文件时默认必须失败。');
+  assertIncludes(
+    result.stdout,
+    '证据根目录只能包含证据目录，发现普通文件',
+    '证据根目录普通文件失败必须写入 diagnostics。',
+  );
+}
+
+function assertExtraRootDirectoryFailsByDefault() {
+  const root = path.join(tmpRoot, 'extra-root-directory');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  mkdirSync(path.join(root, 'manual-notes'), { recursive: true });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+  ]);
+  assertStatus(result, 1, '证据根目录混入无 manifest 目录时默认必须失败。');
+  assertIncludes(
+    result.stdout,
+    '证据根目录只能包含带 manifest.json 的证据目录',
+    '证据根目录无 manifest 目录失败必须写入 diagnostics。',
+  );
+}
+
+function assertExtraRootSymlinkFailsByDefault() {
+  const root = path.join(tmpRoot, 'extra-root-symlink');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  symlinkSync(
+    path.join(root, '20260617T010000Z-pre-cutover'),
+    path.join(root, 'pre-cutover-link'),
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+  ]);
+  assertStatus(result, 1, '证据根目录混入符号链接时默认必须失败。');
+  assertIncludes(
+    result.stdout,
+    '证据根目录下不能包含符号链接条目',
+    '证据根目录符号链接失败必须写入 diagnostics。',
+  );
+}
+
+function assertAllowExtraRootEntriesSucceeds() {
+  const root = path.join(tmpRoot, 'allow-extra-root-entries');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  writeFileSync(path.join(root, 'operator-note.txt'), 'manual note\n', 'utf8');
+  mkdirSync(path.join(root, 'manual-notes'), { recursive: true });
+  symlinkSync(
+    path.join(root, '20260617T010000Z-pre-cutover'),
+    path.join(root, 'pre-cutover-link'),
+  );
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+    '--allow-extra-root-entries',
+  ]);
+  assertStatus(result, 0, '显式允许额外根目录条目时审计应通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '允许额外根目录条目审计 stdout');
+  assertEqual(
+    output.allowExtraRootEntries,
+    true,
+    '允许额外根目录条目时 stdout 必须记录 allowExtraRootEntries=true。',
+  );
+  assertEqual(
+    output.diagnostics?.length,
+    0,
+    '允许额外根目录条目时不应输出根目录额外条目诊断。',
+  );
+}
+
+function assertRejectsUnsafeInputs() {
+  const root = path.join(tmpRoot, 'unsafe-target');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  const linkPath = path.join(tmpRoot, 'unsafe-link');
+  symlinkSync(root, linkPath);
+  const verifyLink = path.join(tmpRoot, 'verify-link.mjs');
+  symlinkSync(path.resolve('scripts/ops/pingora-cutover-evidence-verify.mjs'), verifyLink);
+
+  const cases = [
+    {
+      args: ['--evidence-root', 'relative-evidence'],
+      expected: '--evidence-root 必须是绝对路径',
+      reason: '证据根目录相对路径必须失败。',
+    },
+    {
+      args: ['--evidence-root', path.parse(process.cwd()).root],
+      expected: '--evidence-root 不能是文件系统根目录',
+      reason: '证据根目录为文件系统根目录必须失败。',
+    },
+    {
+      args: ['--evidence-root', `${root}\n--allow-extra-root-entries`],
+      expected: '--evidence-root 不能包含换行或 NUL 字符',
+      reason: '证据根目录带控制字符必须失败。',
+    },
+    {
+      args: ['--evidence-root', linkPath],
+      expected: '--evidence-root 不能是符号链接',
+      reason: '证据根目录为符号链接必须失败。',
+    },
+    {
+      args: ['--evidence-root', root, '--verify-script', 'relative.mjs'],
+      expected: '--verify-script 必须是绝对路径',
+      reason: 'verifier 相对路径必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--verify-script',
+        `${path.resolve('scripts/ops/pingora-cutover-evidence-verify.mjs')}\n--allow-extra-files`,
+      ],
+      expected: '--verify-script 不能包含换行或 NUL 字符',
+      reason: 'verifier 路径带控制字符必须失败。',
+    },
+    {
+      args: ['--evidence-root', root, '--verify-script', verifyLink],
+      expected: '--verify-script 不能是符号链接',
+      reason: 'verifier 符号链接必须失败。',
+    },
+    {
+      args: ['--evidence-root', root, '--require-phase', '../bad'],
+      expected: '--require-phase 只能包含 ASCII',
+      reason: 'phase 名称不安全必须失败。',
+    },
+    {
+      args: ['--evidence-root', root, '--require-command', 'enable-apply'],
+      expected: '--require-command 必须使用 <phase>:<commandName> 格式',
+      reason: 'command 证据要求缺少 commandName 必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command',
+        'enable-apply:../bad',
+      ],
+      expected: '--require-command commandName 只能包含 ASCII',
+      reason: 'command 名称不安全必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command-executable',
+        'enable-apply',
+      ],
+      expected:
+        '--require-command-executable 必须使用 <phase>:<commandName>:<absolutePath> 格式',
+      reason: 'command executable 要求缺少字段必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command-executable',
+        'enable-apply:../bad:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+      ],
+      expected: '--require-command-executable commandName 只能包含 ASCII',
+      reason: 'command executable 名称不安全必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command-executable',
+        'enable-apply:pingora-direct-enable-apply:relative.sh',
+      ],
+      expected: '--require-command-executable executable 必须是绝对路径',
+      reason: 'command executable 相对路径必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command-executable',
+        'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh\n--apply',
+      ],
+      expected:
+        '--require-command-executable executable 不能包含换行或 NUL 字符',
+      reason: 'command executable 带控制字符必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command-executable',
+        'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+        '--require-command-executable',
+        'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+      ],
+      expected:
+        '--require-command-executable 不能为同一个 <phase>:<commandName> 指定多个不同路径',
+      reason: '同一 command executable 重复绑定不同路径必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command-arg',
+        'enable-apply',
+      ],
+      expected:
+        '--require-command-arg 必须使用 <phase>:<commandName>:<arg> 格式',
+      reason: 'command arg 要求缺少字段必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command-arg',
+        'enable-apply:../bad:--apply',
+      ],
+      expected: '--require-command-arg commandName 只能包含 ASCII',
+      reason: 'command arg 名称不安全必须失败。',
+    },
+    {
+      args: [
+        '--evidence-root',
+        root,
+        '--require-command-arg',
+        'enable-apply:pingora-direct-enable-apply:',
+      ],
+      expected: '--require-command-arg arg 必须是非空且不包含换行的字符串',
+      reason: 'command arg 为空必须失败。',
+    },
+    {
+      args: ['--evidence-root', root, '--require-cutover-run-id', 'cutover 1'],
+      expected: '--require-cutover-run-id 只能包含 ASCII',
+      reason: 'cutoverRunId 不安全必须失败。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = runAudit(testCase.args);
+    assertStatus(result, 1, testCase.reason);
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function assertManifestFileNameControlCharacterFails() {
+  const root = path.join(tmpRoot, 'manifest-file-name-control-character');
+  const bundleDir = prepareCommandBundle(
+    root,
+    '20260617T010000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+  );
+  const manifestPath = path.join(bundleDir, 'manifest.json');
+  const manifest = readJson(manifestPath, '文件名控制字符 manifest');
+  manifest.files.commandRecord.path = 'command-record.json\noperator-note.txt';
+  writeJson(manifestPath, manifest);
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+  ]);
+  assertStatus(result, 1, '命令证据 manifest 文件名带控制字符时总审计必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest.files.commandRecord.path 只能是证据目录内的普通文件名',
+    '命令证据文件名控制字符必须给出明确诊断。',
+  );
+}
+
+function assertRejectsInvalidTimelineMaxSpan() {
+  const root = path.join(tmpRoot, 'invalid-timeline-max-span');
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
+  const cases = [
+    {
+      args: ['--evidence-root', root, '--timeline-max-span-ms', '0'],
+      env: {},
+      expected: '--timeline-max-span-ms 必须是正整数',
+      reason: 'timeline 最大跨度为 0 必须失败。',
+    },
+    {
+      args: ['--evidence-root', root],
+      env: {
+        GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS: 'oops',
+      },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS 必须是正整数',
+      reason: 'timeline 最大跨度 env 非正整数必须失败。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = runAudit(testCase.args, testCase.env);
+    assertStatus(result, 1, testCase.reason);
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function prepareFullCutoverTimeline(root, times, options = {}) {
+  const timelineTimes = {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+    postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-17T04:00:00.000Z',
+    postRollback: '2026-06-17T05:00:00.000Z',
+    ...times,
+  };
+  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover', {
+    generatedAt: timelineTimes.preCutover,
+    cutoverRunId: options.cutoverRunId,
+  });
+  prepareCommandBundle(
+    root,
+    '20260617T020000Z-enable-apply-pingora-direct-enable-apply',
+    'enable-apply',
+    'pingora-direct-enable-apply',
+    {
+      generatedAt: timelineTimes.enableApply,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareCommandBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.healthPatrolDirect)}-post-enable-pingora-health-patrol-direct-env-switch`,
+    'post-enable',
+    'pingora-health-patrol-direct-env-switch',
+    {
+      generatedAt: timelineTimes.healthPatrolDirect,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareBundle(root, '20260617T030000Z-post-enable', 'post-enable', {
+    generatedAt: timelineTimes.postEnable,
+    cutoverRunId: options.cutoverRunId,
+    directLiveSummary: true,
+    directLiveAccessLog: options.postEnableDirectLiveAccessLog !== false,
+    directLiveStaticHeaders: options.postEnableDirectLiveSummary !== false,
+  });
+  prepareCommandBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.gatewayShadow)}-rollback-prep-pingora-gateway-shadow-env-switch`,
+    'rollback-prep',
+    'pingora-gateway-shadow-env-switch',
+    {
+      generatedAt: timelineTimes.gatewayShadow,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareCommandBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.healthPatrolNginx)}-rollback-prep-pingora-health-patrol-nginx-env-switch`,
+    'rollback-prep',
+    'pingora-health-patrol-nginx-env-switch',
+    {
+      generatedAt: timelineTimes.healthPatrolNginx,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareCommandBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.rollbackApply)}-rollback-apply-pingora-direct-rollback-apply`,
+    'rollback-apply',
+    'pingora-direct-rollback-apply',
+    {
+      generatedAt: timelineTimes.rollbackApply,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.postRollback)}-post-rollback`,
+    'post-rollback',
+    {
+      generatedAt: timelineTimes.postRollback,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+}
+
+function directoryTimestamp(isoTime) {
+  return isoTime
+    .replace(/[-:]/gu, '')
+    .replace(/\.\d{3}Z$/u, 'Z')
+    .replace('T', 'T');
+}
+
+function prepareBundle(root, dirName, phase, options = {}) {
+  const dir = path.join(root, dirName);
+  const directLiveAccessLog =
+    options.directLiveSummary && options.directLiveAccessLog !== false
+      ? createDirectLiveAccessLogSummary()
+      : null;
+  const directLiveStaticHeaders =
+    options.directLiveSummary && options.directLiveStaticHeaders !== false
+      ? createDirectLiveStaticHeadersSummary()
+      : null;
+  const pingoraEnvShadow =
+    options.pingoraEnvShadow === false
+      ? null
+      : options.pingoraEnvShadow && typeof options.pingoraEnvShadow === 'object'
+      ? options.pingoraEnvShadow
+      : createPingoraEnvShadowSummary();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, 'snapshot.json'), '{"ok":true}\n', 'utf8');
+  writeFileSync(path.join(dir, 'snapshot.stdout.txt'), '{"ok":true}\n', 'utf8');
+  writeFileSync(path.join(dir, 'snapshot.stderr.txt'), '', 'utf8');
+  writeFileSync(
+    path.join(dir, 'snapshot-command.json'),
+    '{"executable":"node"}\n',
+    'utf8',
+  );
+  writeJson(path.join(dir, 'manifest.json'), {
+    schemaVersion: 1,
+    generatedAt: options.generatedAt || '2026-06-17T00:00:00.000Z',
+    phase,
+    ...(options.cutoverRunId ? { cutoverRunId: options.cutoverRunId } : {}),
+    summary: {
+      status: options.summaryStatus || 'OK',
+      ...(directLiveAccessLog
+        ? { directLiveAccessLog }
+        : {}),
+      ...(directLiveStaticHeaders
+        ? { directLiveStaticHeaders }
+        : {}),
+      ...(pingoraEnvShadow ? { pingoraEnvShadow } : {}),
+    },
+    files: {
+      manifest: 'manifest.json',
+      snapshot: metadataFor(path.join(dir, 'snapshot.json')),
+      snapshotParseError: null,
+      snapshotStdout: metadataFor(path.join(dir, 'snapshot.stdout.txt')),
+      snapshotStderr: metadataFor(path.join(dir, 'snapshot.stderr.txt')),
+      snapshotCommand: metadataFor(path.join(dir, 'snapshot-command.json')),
+      directLive: null,
+      directLiveParseError: null,
+      directLiveStdout: null,
+      directLiveStderr: null,
+      directLiveCommand: null,
+    },
+  });
+  return dir;
+}
+
+function createDirectLiveAccessLogSummary() {
+  return {
+    present: true,
+    checked: 20,
+    matchedCount: 20,
+    missingCount: 0,
+    mismatchCount: 0,
+  };
+}
+
+function createDirectLiveStaticHeadersSummary() {
+  return {
+    present: true,
+    normal: {
+      ok: true,
+      present: true,
+      cacheControl: 'no-cache',
+      etag: 'W/"1b-6a327f90"',
+      lastModified: 'Wed, 17 Jun 2026 11:05:52 GMT',
+      acceptRanges: 'bytes',
+      contentLength: '27',
+      rangeStatusCode: 206,
+      rangeContentRange: 'bytes 0-0/27',
+      etag304StatusCode: 304,
+      lastModified304StatusCode: 304,
+    },
+    fingerprinted: {
+      ok: true,
+      present: true,
+      cacheControl: 'public, max-age=31536000, immutable',
+      etag: 'W/"29-6a327f90"',
+      lastModified: 'Wed, 17 Jun 2026 11:05:52 GMT',
+      acceptRanges: 'bytes',
+      contentLength: '41',
+      rangeStatusCode: 206,
+      rangeContentRange: 'bytes 0-0/41',
+      etag304StatusCode: 304,
+      lastModified304StatusCode: 304,
+    },
+    diagnostics: [],
+  };
+}
+
+function createPingoraEnvShadowSummary() {
+  return {
+    present: true,
+    listen: '127.0.0.1:18081',
+    tlsListen: '',
+    httpRedirectListen: '',
+    tlsCertFile: '',
+    tlsKeyFile: '',
+    mode: 'shadow',
+    shadowReady: true,
+    directReady: false,
+    ok: true,
+    diagnostics: [],
+  };
+}
+
+function prepareCommandBundle(root, dirName, phase, commandName, options = {}) {
+  const dir = path.join(root, dirName);
+  const executable = options.executable || defaultCommandExecutable(commandName);
+  const args = options.args || defaultCommandArgs(commandName);
+  const generatedAt = options.generatedAt || '2026-06-17T00:00:00.000Z';
+  const startedAt = options.startedAt || generatedAt;
+  const finishedAt = options.finishedAt || generatedAt;
+  const durationMs = Date.parse(finishedAt) - Date.parse(startedAt);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, 'command.stdout.txt'), 'ok\n', 'utf8');
+  writeFileSync(path.join(dir, 'command.stderr.txt'), '', 'utf8');
+  const commandRecord = {
+    schemaVersion: 1,
+    name: commandName,
+    phase,
+    ...(options.cutoverRunId ? { cutoverRunId: options.cutoverRunId } : {}),
+    expectedExecutable: executable,
+    executable,
+    args,
+    command: [executable, ...args].join(' '),
+    cwd: process.cwd(),
+    exitCode: options.exitCode ?? 0,
+    signal: options.signal ?? null,
+    error: null,
+    startedAt,
+    finishedAt,
+    durationMs,
+    stdoutPath: 'command.stdout.txt',
+    stderrPath: 'command.stderr.txt',
+  };
+  writeJson(path.join(dir, 'command-record.json'), commandRecord);
+  writeJson(path.join(dir, 'manifest.json'), {
+    schemaVersion: 1,
+    generatedAt,
+    phase,
+    commandName,
+    ...(options.cutoverRunId ? { cutoverRunId: options.cutoverRunId } : {}),
+    expectedExecutable: executable,
+    summary: {
+      status: options.summaryStatus || 'OK',
+      exitCode: options.exitCode ?? 0,
+      signal: options.signal ?? null,
+    },
+    command: commandRecord,
+    files: {
+      manifest: 'manifest.json',
+      stdout: metadataFor(path.join(dir, 'command.stdout.txt')),
+      stderr: metadataFor(path.join(dir, 'command.stderr.txt')),
+      commandRecord: metadataFor(path.join(dir, 'command-record.json')),
+    },
+  });
+  return dir;
+}
+
+function defaultCommandExecutable(commandName) {
+  switch (commandName) {
+    case 'pingora-direct-rollback-apply':
+      return '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh';
+    case 'pingora-health-patrol-direct-env-switch':
+    case 'pingora-health-patrol-nginx-env-switch':
+      return '/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs';
+    case 'pingora-gateway-shadow-env-switch':
+      return '/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs';
+    case 'pingora-direct-enable-apply':
+    default:
+      return '/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh';
+  }
+}
+
+function defaultCommandArgs(commandName) {
+  switch (commandName) {
+    case 'pingora-health-patrol-direct-env-switch':
+      return ['--apply', 'pingora-direct'];
+    case 'pingora-health-patrol-nginx-env-switch':
+      return ['--apply', 'nginx'];
+    case 'pingora-direct-enable-apply':
+    case 'pingora-gateway-shadow-env-switch':
+    case 'pingora-direct-rollback-apply':
+    default:
+      return ['--apply'];
+  }
+}
+
+function metadataFor(filePath) {
+  const content = readFileSync(filePath);
+  return {
+    path: path.basename(filePath),
+    sizeBytes: content.length,
+    sha256: createHash('sha256').update(content).digest('hex'),
+  };
+}
+
+function runAudit(args, extraEnv = {}) {
+  return spawnSync('node', [AUDIT_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_ROOT: '',
+      GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_VERIFY_SCRIPT: '',
+      GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS: '',
+      ...extraEnv,
+    },
+  });
+}
+
+function runFullCutoverAudit(root, extraArgs = []) {
+  return runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'pre-cutover',
+    '--require-phase',
+    'post-enable',
+    '--require-phase',
+    'post-rollback',
+    '--require-phase-direct-live-access-log',
+    'post-enable',
+    '--require-phase-direct-live-static-headers',
+    'post-enable',
+    '--require-phase-pingora-env-shadow',
+    'post-rollback',
+    '--require-command',
+    'enable-apply:pingora-direct-enable-apply',
+    '--require-command',
+    'post-enable:pingora-health-patrol-direct-env-switch',
+    '--require-command',
+    'rollback-prep:pingora-gateway-shadow-env-switch',
+    '--require-command',
+    'rollback-prep:pingora-health-patrol-nginx-env-switch',
+    '--require-command',
+    'rollback-apply:pingora-direct-rollback-apply',
+    '--require-command-executable',
+    'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+    '--require-command-executable',
+    'post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    '--require-command-executable',
+    'rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    '--require-command-executable',
+    'rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    '--require-command-executable',
+    'rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+    '--require-command-arg',
+    'enable-apply:pingora-direct-enable-apply:--apply',
+    '--require-command-arg',
+    'post-enable:pingora-health-patrol-direct-env-switch:--apply',
+    '--require-command-arg',
+    'post-enable:pingora-health-patrol-direct-env-switch:pingora-direct',
+    '--require-command-arg',
+    'rollback-prep:pingora-gateway-shadow-env-switch:--apply',
+    '--require-command-arg',
+    'rollback-prep:pingora-health-patrol-nginx-env-switch:--apply',
+    '--require-command-arg',
+    'rollback-prep:pingora-health-patrol-nginx-env-switch:nginx',
+    '--require-command-arg',
+    'rollback-apply:pingora-direct-rollback-apply:--apply',
+    ...extraArgs,
+  ]);
+}
+
+function writeJson(filePath, value) {
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function parseJson(raw, label) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}\n${raw}`);
+    return {};
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  if ((result.status ?? 0) !== expected) {
+    failures.push(
+      `${reason} 期望退出码 ${expected}，实际 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(value, expected, reason) {
+  if (!value.includes(expected)) {
+    failures.push(`${reason} 缺少 ${expected}`);
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 期望 ${expected}，实际 ${actual}`);
+  }
+}
diff --git a/scripts/check-pingora-cutover-evidence-bundle.mjs b/scripts/check-pingora-cutover-evidence-bundle.mjs
new file mode 100644
index 000000000..8db9760a8
--- /dev/null
+++ b/scripts/check-pingora-cutover-evidence-bundle.mjs
@@ -0,0 +1,2012 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const BUNDLE_SCRIPT = 'scripts/ops/pingora-cutover-evidence-bundle.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-cutover-evidence-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-cutover-evidence-bundle] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-cutover-evidence-bundle] OK');
+
+function main() {
+  assertScriptShape();
+  assertBundleSucceedsAndWritesManifest();
+  assertBundleSummarizesPingoraEnvShadow();
+  assertBundleSummarizesDirectPingoraEnvAsNotShadow();
+  assertBundleWritesCutoverRunId();
+  assertBundleCanArchiveDirectLiveEvidence();
+  assertDirectLiveFailureStillWritesEvidenceAndFails();
+  assertDirectLiveMissingAccessLogSummaryFails();
+  assertDirectLiveMissingStaticHeadersSummaryFails();
+  assertDirectLiveStaticHeaderDiagnosticsFails();
+  assertDirectLiveParseFailureWritesParseErrorEvidence();
+  assertBundleRedactsProbeTokensFromArtifacts();
+  assertCriticalSnapshotStillWritesEvidenceAndFails();
+  assertSnapshotParseFailureWritesParseErrorEvidence();
+  assertRejectsUnsafePhase();
+  assertRejectsUnsafeCutoverRunId();
+  assertRejectsSnapshotArgsWithControlCharacters();
+  assertRejectsDirectLiveArgsWithControlCharacters();
+  assertRejectsRelativePaths();
+  assertRejectsFilesystemRootPaths();
+  assertRejectsSymlinkOutputRootBeforeSnapshot();
+  assertRejectsSymlinkOutputRootParentBeforeSnapshot();
+  assertRejectsFileOutputRootBeforeSnapshot();
+  assertRejectsInvalidTimeout();
+  assertRejectsInvalidBoolEnv();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(BUNDLE_SCRIPT, 'utf8');
+  assertIncludes(
+    content,
+    '只写 --output-root 下的新证据目录',
+    '证据包脚本 usage 必须说明只写证据目录。',
+  );
+  assertIncludes(
+    content,
+    'BUNDLE_DIR_MODE = 0o750',
+    '证据包脚本必须显式固定新证据目录权限。',
+  );
+  assertIncludes(
+    content,
+    'EVIDENCE_FILE_MODE = 0o640',
+    '证据包脚本必须显式固定证据文件权限。',
+  );
+  assertIncludes(
+    content,
+    "flag: 'wx'",
+    '证据包脚本写证据文件时必须避免覆盖既有文件。',
+  );
+  assertIncludes(
+    content,
+    'validatePhase(config.phase);',
+    '证据包脚本必须校验 phase，避免目录名和 manifest 阶段漂移。',
+  );
+  assertIncludes(
+    content,
+    'cutoverRunId',
+    '证据包脚本必须支持写入切换批次 ID。',
+  );
+  assertIncludes(
+    content,
+    '--cutover-run-id',
+    '证据包脚本 usage 必须公开切换批次 ID 参数。',
+  );
+  assertIncludes(
+    content,
+    'validateOutputRootForWriting(outputRoot);',
+    '证据包脚本写入前必须校验 output-root 路径安全。',
+  );
+  assertIncludes(
+    content,
+    '--output-root 不能是符号链接',
+    '证据包脚本必须拒绝符号链接 output-root。',
+  );
+  assertIncludes(
+    content,
+    '--output-root 已存在但不是目录',
+    '证据包脚本必须拒绝非目录 output-root。',
+  );
+  assertIncludes(
+    content,
+    'snapshot.stdout.txt',
+    '证据包必须保存快照 stdout。',
+  );
+  assertIncludes(
+    content,
+    'direct-live.stdout.txt',
+    '证据包必须能保存 direct live stdout。',
+  );
+  assertIncludes(
+    content,
+    'parseDirectLiveJson',
+    '证据包必须能从 direct live stdout 中提取 JSON 结果。',
+  );
+  assertIncludes(
+    content,
+    'pingoraEnvShadow',
+    '证据包 manifest 必须提升 Pingora env shadow 摘要。',
+  );
+  assertIncludes(
+    content,
+    '--run-direct-live',
+    '证据包必须暴露 direct live 归档开关。',
+  );
+  assertIncludes(
+    content,
+    'manifest.json',
+    '证据包必须写 manifest。',
+  );
+  assertIncludes(
+    content,
+    'SECRET_VALUE_FLAGS',
+    '证据包命令记录必须集中维护敏感参数脱敏列表。',
+  );
+  assertIncludes(
+    content,
+    'args: redactSecretArgs',
+    '证据包命令记录必须保存结构化脱敏参数数组。',
+  );
+  assertIncludes(
+    content,
+    '<redacted>',
+    '证据包命令记录必须用 <redacted> 隐藏敏感参数值。',
+  );
+  if (
+    content.includes("execFile('systemctl'") ||
+    content.includes('execFile("systemctl"') ||
+    content.includes('nginx -s reload')
+  ) {
+    failures.push('证据包脚本不应直接操作 systemd 或 Nginx。');
+  }
+}
+
+function assertBundleSucceedsAndWritesManifest() {
+  const fixture = prepareFixture('ok');
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--expected-public-base-url',
+      'https://127.0.0.1',
+      '--expected-public-host',
+      'example.com',
+      '--run-health-patrol',
+      '--require-pingora-gateway',
+      '--fail-on-critical',
+    ],
+  });
+
+  assertStatus(result, 0, 'OK 快照应生成证据包并成功退出。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'OK 证据包 stdout');
+  assertEqual(output.phase, 'post-enable', '证据包 stdout 必须记录阶段。');
+  assertEqual(output.status, 'OK', '证据包 stdout 必须记录 OK 状态。');
+  assertFileExists(output.bundleDir, '证据包目录必须存在。');
+
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(manifest.phase, 'post-enable', 'manifest 必须记录阶段。');
+  assertEqual(manifest.summary.status, 'OK', 'manifest 必须记录快照状态。');
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.ok,
+    true,
+    'manifest 必须记录 Pingora env 已处于 shadow 高端口。',
+  );
+  assertEqual(
+    manifest.commands?.[0]?.exitCode,
+    0,
+    'manifest 必须记录快照命令退出码。',
+  );
+  assertIncludes(
+    manifest.commands?.[0]?.command || '',
+    '--run-health-patrol',
+    'manifest 命令必须记录快照执行参数。',
+  );
+  assertIncludes(
+    manifest.commands?.[0]?.command || '',
+    '--require-pingora-gateway',
+    'manifest 命令必须记录 Pingora 发布物自审要求。',
+  );
+  assertEqual(
+    manifest.commands?.[0]?.executable,
+    'node',
+    'manifest 命令记录必须保存可执行文件。',
+  );
+  assertIncludes(
+    manifest.commands?.[0]?.args || [],
+    '--require-pingora-gateway',
+    'manifest 命令记录必须保存结构化参数数组。',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.snapshot,
+    'snapshot.json',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.snapshotStdout,
+    'snapshot.stdout.txt',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.snapshotStderr,
+    'snapshot.stderr.txt',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.snapshotCommand,
+    'snapshot-command.json',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'snapshot.json'),
+    '证据包必须保存解析后的 snapshot.json。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'snapshot.stdout.txt'),
+    '证据包必须保存 snapshot stdout。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'snapshot.stderr.txt'),
+    '证据包必须保存 snapshot stderr。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'snapshot-command.json'),
+    '证据包必须保存快照命令记录。',
+  );
+  assertMode(output.bundleDir, 0o750, '证据包目录权限必须是 0750。');
+  for (const fileName of [
+    'manifest.json',
+    'snapshot.json',
+    'snapshot.stdout.txt',
+    'snapshot.stderr.txt',
+    'snapshot-command.json',
+  ]) {
+    assertMode(
+      path.join(output.bundleDir, fileName),
+      0o640,
+      `${fileName} 权限必须是 0640。`,
+    );
+  }
+  const snapshot = readJson(path.join(output.bundleDir, 'snapshot.json'));
+  assertIncludes(
+    snapshot.args,
+    '--expected-gateway-mode',
+    '证据包必须把 expected gateway mode 透传给状态快照。',
+  );
+  assertIncludes(
+    snapshot.args,
+    '--require-pingora-gateway',
+    '证据包必须把 Pingora 发布物自审要求透传给状态快照。',
+  );
+  assertFileUnchanged(
+    fixture.healthEnvFile,
+    fixture.originalHealthEnvText,
+    '证据包不应改写 health patrol env。',
+  );
+  const commandRecord = readJson(path.join(output.bundleDir, 'snapshot-command.json'));
+  assertEqual(
+    commandRecord.executable,
+    'node',
+    'snapshot-command.json 必须保存可执行文件。',
+  );
+  assertIncludes(
+    commandRecord.args || [],
+    '--expected-gateway-mode',
+    'snapshot-command.json 必须保存结构化参数数组。',
+  );
+}
+
+function assertBundleSummarizesPingoraEnvShadow() {
+  const fixture = prepareFixture('pingora-env-shadow-summary');
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: ['--phase', 'post-rollback', '--fail-on-critical'],
+  });
+
+  assertStatus(result, 0, 'shadow env 快照应生成 OK 摘要。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'shadow env 证据包 stdout');
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.present,
+    true,
+    'manifest.summary.pingoraEnvShadow 必须标记 env 摘要存在。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.listen,
+    '127.0.0.1:18081',
+    'manifest.summary.pingoraEnvShadow 必须记录 shadow listen。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.tlsListen,
+    '',
+    'manifest.summary.pingoraEnvShadow 必须记录 TLS 低端口为空。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.httpRedirectListen,
+    '',
+    'manifest.summary.pingoraEnvShadow 必须记录 HTTP redirect 低端口为空。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.tlsCertFile,
+    '',
+    'manifest.summary.pingoraEnvShadow 必须记录 TLS cert 路径为空。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.tlsKeyFile,
+    '',
+    'manifest.summary.pingoraEnvShadow 必须记录 TLS key 路径为空。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.mode,
+    'shadow',
+    'manifest.summary.pingoraEnvShadow 必须记录 snapshot 判定的 shadow 姿态。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.shadowReady,
+    true,
+    'manifest.summary.pingoraEnvShadow 必须记录 shadowReady=true。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.ok,
+    true,
+    'manifest.summary.pingoraEnvShadow.ok 必须为 true。',
+  );
+}
+
+function assertBundleSummarizesDirectPingoraEnvAsNotShadow() {
+  const fixture = prepareFixture('pingora-env-direct-summary', {
+    snapshotPingoraEnvValues: {
+      listen: '127.0.0.1:18081',
+      tlsListen: '0.0.0.0:443',
+      httpRedirectListen: '0.0.0.0:80',
+      tlsCertFile: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+      tlsKeyFile: '/etc/genarrative/pingora-tls/example/privkey.pem',
+    },
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: ['--phase', 'post-enable', '--fail-on-critical'],
+  });
+
+  assertStatus(
+    result,
+    0,
+    'direct env 快照默认只生成摘要，不应让证据包本身失败。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'direct env 证据包 stdout');
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.ok,
+    false,
+    'direct 低端口 env 摘要必须标记 ok=false。',
+  );
+  assertIncludes(
+    manifest.summary.pingoraEnvShadow?.diagnostics || [],
+    'tlsListen 应为空，实际 0.0.0.0:443',
+    'direct 低端口 env 摘要必须记录 TLS 低端口诊断。',
+  );
+  assertIncludes(
+    manifest.summary.pingoraEnvShadow?.diagnostics || [],
+    'httpRedirectListen 应为空，实际 0.0.0.0:80',
+    'direct 低端口 env 摘要必须记录 HTTP redirect 低端口诊断。',
+  );
+  assertIncludes(
+    manifest.summary.pingoraEnvShadow?.diagnostics || [],
+    'tlsCertFile 应为空，实际 /etc/genarrative/pingora-tls/example/fullchain.pem',
+    'direct 低端口 env 摘要必须记录 TLS cert 残留诊断。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.mode,
+    'direct',
+    'direct 低端口 env 摘要必须记录 snapshot 判定的 direct 姿态。',
+  );
+}
+
+function assertBundleWritesCutoverRunId() {
+  const fixture = prepareFixture('cutover-run-id');
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: [
+      '--phase',
+      'pre-cutover',
+      '--cutover-run-id',
+      'cutover-20260617T010000Z',
+      '--fail-on-critical',
+    ],
+  });
+
+  assertStatus(result, 0, '提供 cutover run id 时证据包应成功退出。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'cutover run id 证据包 stdout');
+  assertEqual(
+    output.cutoverRunId,
+    'cutover-20260617T010000Z',
+    '证据包 stdout 必须返回 cutoverRunId。',
+  );
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.cutoverRunId,
+    'cutover-20260617T010000Z',
+    'manifest 必须记录 cutoverRunId。',
+  );
+}
+
+function assertBundleCanArchiveDirectLiveEvidence() {
+  const fixture = prepareFixture('direct-live-ok', {
+    directLiveStatus: 'OK',
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: directLiveArgs(fixture, [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--expected-public-base-url',
+      'https://127.0.0.1',
+      '--expected-public-host',
+      'example.com',
+      '--run-health-patrol',
+      '--require-pingora-gateway',
+      '--fail-on-critical',
+    ]),
+  });
+
+  assertStatus(result, 0, 'direct live 成功时证据包应成功退出。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'direct live 证据包 stdout');
+  assertFileExists(output.directLivePath, '证据包 stdout 必须返回 direct live JSON 路径。');
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.directLiveStatus,
+    'OK',
+    'manifest 必须记录 direct live 状态。',
+  );
+  assertEqual(
+    manifest.summary.directLiveAccessLog?.checked,
+    2,
+    'manifest 必须记录 direct live access log 检查请求数。',
+  );
+  assertEqual(
+    manifest.summary.directLiveAccessLog?.matchedCount,
+    2,
+    'manifest 必须记录 direct live access log 匹配数量。',
+  );
+  assertEqual(
+    manifest.summary.directLiveAccessLog?.missingCount,
+    0,
+    'manifest 必须记录 direct live access log 缺失数量。',
+  );
+  assertEqual(
+    manifest.summary.directLiveAccessLog?.mismatchCount,
+    0,
+    'manifest 必须记录 direct live access log 漂移数量。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.normal?.cacheControl,
+    'no-cache',
+    'manifest 必须提升普通静态资源 Cache-Control 证据。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.normal?.rangeContentRange,
+    'bytes 0-0/27',
+    'manifest 必须提升普通静态资源 Content-Range 证据。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.normal?.etag304StatusCode,
+    304,
+    'manifest 必须提升普通静态资源 ETag 304 证据。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.normal?.lastModified304StatusCode,
+    304,
+    'manifest 必须提升普通静态资源 Last-Modified 304 证据。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.fingerprinted?.cacheControl,
+    'public, max-age=31536000, immutable',
+    'manifest 必须提升指纹静态资源 Cache-Control 证据。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.fingerprinted?.rangeContentRange,
+    'bytes 0-0/41',
+    'manifest 必须提升指纹静态资源 Content-Range 证据。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.fingerprinted?.etag304StatusCode,
+    304,
+    'manifest 必须提升指纹静态资源 ETag 304 证据。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.fingerprinted
+      ?.lastModified304StatusCode,
+    304,
+    'manifest 必须提升指纹静态资源 Last-Modified 304 证据。',
+  );
+  assertEqual(
+    manifest.commands?.[1]?.name,
+    'pingora-direct-live',
+    'manifest 必须记录 direct live 命令。',
+  );
+  assertIncludes(
+    manifest.commands?.[1]?.args || [],
+    '--pingora-access-log',
+    'direct live 命令记录必须保留 access log 参数。',
+  );
+  assertIncludes(
+    manifest.commands?.[1]?.command || '',
+    '--require-wss-upgrade',
+    'direct live 命令必须强制 WSS 101。',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.directLive,
+    'direct-live.json',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.directLiveStdout,
+    'direct-live.stdout.txt',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.directLiveStderr,
+    'direct-live.stderr.txt',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.directLiveCommand,
+    'direct-live-command.json',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live.json'),
+    '证据包必须保存 direct-live.json。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live.stdout.txt'),
+    '证据包必须保存 direct live stdout。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live.stderr.txt'),
+    '证据包必须保存 direct live stderr。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live-command.json'),
+    '证据包必须保存 direct live 命令记录。',
+  );
+  const directLive = readJson(path.join(output.bundleDir, 'direct-live.json'));
+  assertEqual(directLive.ok, true, 'direct-live.json 必须记录 ok=true。');
+  const staticAssetCheck = directLive.results?.find(
+    (check) => check.name === 'https-static-asset',
+  );
+  if (!staticAssetCheck) {
+    failures.push('direct-live.json 必须保留静态资源检查结果。');
+  } else {
+    assertEqual(
+      staticAssetCheck.headers?.['cache-control'],
+      'no-cache',
+      'direct-live.json 必须保留普通静态资源 Cache-Control 证据。',
+    );
+    assertEqual(
+      staticAssetCheck.range?.headers?.['content-range'],
+      'bytes 0-0/27',
+      'direct-live.json 必须保留普通静态资源 Content-Range 证据。',
+    );
+    assertEqual(
+      staticAssetCheck.notModified?.etag?.statusCode,
+      304,
+      'direct-live.json 必须保留普通静态资源 ETag 304 证据。',
+    );
+    assertEqual(
+      staticAssetCheck.notModified?.lastModified?.statusCode,
+      304,
+      'direct-live.json 必须保留普通静态资源 Last-Modified 304 证据。',
+    );
+    assertEqual(
+      staticAssetCheck.fingerprinted?.headers?.['cache-control'],
+      'public, max-age=31536000, immutable',
+      'direct-live.json 必须保留指纹静态资源 Cache-Control 证据。',
+    );
+    assertEqual(
+      staticAssetCheck.fingerprinted?.range?.headers?.['content-range'],
+      'bytes 0-0/41',
+      'direct-live.json 必须保留指纹静态资源 Content-Range 证据。',
+    );
+    assertEqual(
+      staticAssetCheck.fingerprinted?.notModified?.etag?.statusCode,
+      304,
+      'direct-live.json 必须保留指纹静态资源 ETag 304 证据。',
+    );
+    assertEqual(
+      staticAssetCheck.fingerprinted?.notModified?.lastModified?.statusCode,
+      304,
+      'direct-live.json 必须保留指纹静态资源 Last-Modified 304 证据。',
+    );
+  }
+  const accessLogCheck = directLive.results?.find(
+    (check) => check.name === 'direct-access-log',
+  );
+  if (!accessLogCheck) {
+    failures.push('direct-live.json 必须保留 direct-access-log 检查结果。');
+  } else {
+    assertEqual(
+      accessLogCheck.scannedLineCount,
+      1,
+      'direct-access-log 检查必须记录扫描日志行数。',
+    );
+    assertEqual(
+      accessLogCheck.matchedCount,
+      2,
+      'direct-access-log 检查必须记录 matchedCount。',
+    );
+    assertEqual(
+      accessLogCheck.missingCount,
+      0,
+      'direct-access-log 检查必须记录 missingCount=0。',
+    );
+    assertEqual(
+      accessLogCheck.mismatchCount,
+      0,
+      'direct-access-log 检查必须记录 mismatchCount=0。',
+    );
+    assertEqual(
+      accessLogCheck.matched?.[0]?.expectedMethod,
+      'GET',
+      'direct-access-log 检查必须保留已匹配 request_id 的预期方法。',
+    );
+    assertEqual(
+      accessLogCheck.matched?.[0]?.actualMethod,
+      'GET',
+      'direct-access-log 检查必须保留已匹配 request_id 的实际方法。',
+    );
+    assertEqual(
+      accessLogCheck.matched?.[0]?.expectedStatusCode,
+      200,
+      'direct-access-log 检查必须保留已匹配 request_id 的预期状态码。',
+    );
+    assertEqual(
+      accessLogCheck.matched?.[0]?.actualStatusCode,
+      200,
+      'direct-access-log 检查必须保留已匹配 request_id 的实际状态码。',
+    );
+    assertEqual(
+      Array.isArray(accessLogCheck.missing),
+      true,
+      'direct-access-log 检查必须保留 missing 明细数组。',
+    );
+    assertEqual(
+      Array.isArray(accessLogCheck.mismatches),
+      true,
+      'direct-access-log 检查必须保留 mismatches 明细数组。',
+    );
+  }
+}
+
+function assertDirectLiveFailureStillWritesEvidenceAndFails() {
+  const fixture = prepareFixture('direct-live-critical', {
+    directLiveStatus: 'CRITICAL',
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: directLiveArgs(fixture, [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--expected-public-base-url',
+      'https://127.0.0.1',
+      '--expected-public-host',
+      'example.com',
+      '--fail-on-critical',
+    ]),
+  });
+
+  assertStatus(result, 1, 'direct live 失败时证据包应失败。');
+  const output = parseJson(result.stdout, 'direct live 失败证据包 stdout');
+  assertEqual(output.status, 'CRITICAL', 'direct live 失败时 stdout 必须记录 CRITICAL。');
+  assertFileExists(output.bundleDir, 'direct live 失败证据包目录必须存在。');
+  if (!output.bundleDir) {
+    return;
+  }
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.directLiveStatus,
+    'CRITICAL',
+    'direct live 失败时 manifest 必须记录 CRITICAL。',
+  );
+  assertEqual(
+    manifest.summary.directLiveExitCode,
+    1,
+    'direct live 失败时 manifest 必须记录退出码。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live.stdout.txt'),
+    'direct live 失败时仍必须保存 stdout。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live.stderr.txt'),
+    'direct live 失败时仍必须保存 stderr。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live-command.json'),
+    'direct live 失败时仍必须保存命令记录。',
+  );
+}
+
+function assertDirectLiveMissingAccessLogSummaryFails() {
+  const fixture = prepareFixture('direct-live-missing-access-log', {
+    directLiveOutputMode: 'without-access-log',
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: directLiveArgs(fixture, [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--expected-public-base-url',
+      'https://127.0.0.1',
+      '--expected-public-host',
+      'example.com',
+      '--fail-on-critical',
+    ]),
+  });
+
+  assertStatus(
+    result,
+    1,
+    'direct live JSON 缺少 direct-access-log 时证据包应失败。',
+  );
+  const output = parseJson(result.stdout, 'direct live 缺 access log 证据包 stdout');
+  assertEqual(
+    output.status,
+    'CRITICAL',
+    'direct live 缺 access log 时 stdout 必须记录 CRITICAL。',
+  );
+  assertFileExists(output.bundleDir, 'direct live 缺 access log 证据包目录必须存在。');
+  if (!output.bundleDir) {
+    return;
+  }
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.directLiveStatus,
+    'CRITICAL',
+    'direct live 缺 access log 时 manifest 必须记录 CRITICAL。',
+  );
+  assertEqual(
+    manifest.summary.directLiveAccessLog?.present,
+    false,
+    'direct live 缺 access log 时 manifest 必须记录缺失原因。',
+  );
+}
+
+function assertDirectLiveMissingStaticHeadersSummaryFails() {
+  const fixture = prepareFixture('direct-live-missing-static-headers', {
+    directLiveOutputMode: 'without-static-headers',
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: directLiveArgs(fixture, [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--expected-public-base-url',
+      'https://127.0.0.1',
+      '--expected-public-host',
+      'example.com',
+      '--fail-on-critical',
+    ]),
+  });
+
+  assertStatus(
+    result,
+    1,
+    'direct live JSON 缺少静态响应头证据时证据包应失败。',
+  );
+  const output = parseJson(result.stdout, 'direct live 缺静态头证据包 stdout');
+  assertEqual(
+    output.status,
+    'CRITICAL',
+    'direct live 缺静态头时 stdout 必须记录 CRITICAL。',
+  );
+  assertFileExists(output.bundleDir, 'direct live 缺静态头证据包目录必须存在。');
+  if (!output.bundleDir) {
+    return;
+  }
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.directLiveStatus,
+    'CRITICAL',
+    'direct live 缺静态头时 manifest 必须记录 CRITICAL。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.present,
+    false,
+    'direct live 缺静态头时 manifest 必须记录缺失原因。',
+  );
+}
+
+function assertDirectLiveStaticHeaderDiagnosticsFails() {
+  const fixture = prepareFixture('direct-live-bad-static-headers', {
+    directLiveOutputMode: 'bad-static-headers',
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: directLiveArgs(fixture, [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--expected-public-base-url',
+      'https://127.0.0.1',
+      '--expected-public-host',
+      'example.com',
+      '--fail-on-critical',
+    ]),
+  });
+
+  assertStatus(
+    result,
+    1,
+    'direct live 静态响应头摘要缺少 Range / 304 证据时证据包应失败。',
+  );
+  const output = parseJson(result.stdout, 'direct live 静态头漂移证据包 stdout');
+  assertEqual(
+    output.status,
+    'CRITICAL',
+    'direct live 静态头漂移时 stdout 必须记录 CRITICAL。',
+  );
+  if (!output.bundleDir) {
+    return;
+  }
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.directLiveStatus,
+    'CRITICAL',
+    'direct live 静态头漂移时 manifest 必须记录 CRITICAL。',
+  );
+  assertEqual(
+    manifest.summary.directLiveStaticHeaders?.normal?.ok,
+    false,
+    'direct live 静态头漂移时 manifest 必须标记普通静态资源摘要失败。',
+  );
+  assertIncludes(
+    manifest.summary.directLiveStaticHeaders?.diagnostics || [],
+    'normal: Range statusCode 应为 206，实际 -',
+    'direct live 静态头漂移时 manifest 必须记录 Range 诊断。',
+  );
+  assertIncludes(
+    manifest.summary.directLiveStaticHeaders?.diagnostics || [],
+    'normal: ETag 304 statusCode 应为 304，实际 -',
+    'direct live 静态头漂移时 manifest 必须记录 ETag 304 诊断。',
+  );
+}
+
+function assertDirectLiveParseFailureWritesParseErrorEvidence() {
+  const fixture = prepareFixture('direct-live-parse-error', {
+    directLiveOutputMode: 'log-only',
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: directLiveArgs(fixture, [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--expected-public-base-url',
+      'https://127.0.0.1',
+      '--expected-public-host',
+      'example.com',
+      '--fail-on-critical',
+    ]),
+  });
+
+  assertStatus(result, 1, 'direct live 未输出 JSON 时证据包应失败。');
+  const output = parseJson(result.stdout, 'direct live 解析失败证据包 stdout');
+  assertEqual(
+    output.status,
+    'CRITICAL',
+    'direct live 解析失败时 stdout 必须记录 CRITICAL。',
+  );
+  assertFileExists(
+    output.directLiveParseErrorPath,
+    '证据包 stdout 必须返回 direct live parse error 路径。',
+  );
+  assertFileExists(output.bundleDir, 'direct live 解析失败证据包目录必须存在。');
+  if (!output.bundleDir) {
+    return;
+  }
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.files?.directLive,
+    null,
+    'direct live 解析失败时 manifest 不应指向 direct-live.json。',
+  );
+  assertEqual(
+    manifest.files?.directLiveParseError?.path,
+    'direct-live-parse-error.txt',
+    'direct live 解析失败时 manifest 必须指向 parse error 文件。',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.directLiveParseError,
+    'direct-live-parse-error.txt',
+  );
+  assertEqual(
+    manifest.summary.directLiveStatus,
+    'CRITICAL',
+    'direct live 解析失败时 manifest 必须记录 CRITICAL。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live.stdout.txt'),
+    'direct live 解析失败时仍必须保存 stdout。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'direct-live.stderr.txt'),
+    'direct live 解析失败时仍必须保存 stderr。',
+  );
+}
+
+function assertCriticalSnapshotStillWritesEvidenceAndFails() {
+  const fixture = prepareFixture('critical');
+  const result = runBundle(fixture, {
+    status: 'CRITICAL',
+    extraArgs: [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--fail-on-critical',
+    ],
+  });
+
+  assertStatus(result, 1, 'CRITICAL 快照应保留证据并返回失败。');
+  const output = parseJson(result.stdout, 'CRITICAL 证据包 stdout');
+  assertEqual(output.status, 'CRITICAL', '失败证据包 stdout 必须记录 CRITICAL。');
+  assertFileExists(output.bundleDir, '失败证据包目录也必须存在。');
+  if (!output.bundleDir) {
+    return;
+  }
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.status,
+    'CRITICAL',
+    '失败证据包 manifest 必须记录 CRITICAL。',
+  );
+  assertEqual(
+    manifest.summary.snapshotExitCode,
+    1,
+    '失败证据包 manifest 必须记录快照退出码。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'snapshot.json'),
+    '失败证据包仍必须保存 snapshot.json。',
+  );
+  assertMode(output.bundleDir, 0o750, '失败证据包目录权限必须是 0750。');
+  assertMode(
+    path.join(output.bundleDir, 'manifest.json'),
+    0o640,
+    '失败证据包 manifest 权限必须是 0640。',
+  );
+  assertFileUnchanged(
+    fixture.healthEnvFile,
+    fixture.originalHealthEnvText,
+    '失败证据包不应改写 health patrol env。',
+  );
+}
+
+function assertSnapshotParseFailureWritesParseErrorEvidence() {
+  const fixture = prepareFixture('snapshot-parse-error', {
+    snapshotOutputMode: 'log-only',
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--fail-on-critical',
+    ],
+  });
+
+  assertStatus(result, 1, 'snapshot 未输出 JSON 时证据包应失败。');
+  const output = parseJson(result.stdout, 'snapshot 解析失败证据包 stdout');
+  assertEqual(
+    output.status,
+    'CRITICAL',
+    'snapshot 解析失败时 stdout 必须记录 CRITICAL。',
+  );
+  assertFileExists(
+    output.snapshotParseErrorPath,
+    '证据包 stdout 必须返回 snapshot parse error 路径。',
+  );
+  assertFileExists(output.bundleDir, 'snapshot 解析失败证据包目录必须存在。');
+  if (!output.bundleDir) {
+    return;
+  }
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.files?.snapshot,
+    null,
+    'snapshot 解析失败时 manifest 不应指向 snapshot.json。',
+  );
+  assertEqual(
+    manifest.files?.snapshotParseError?.path,
+    'snapshot-parse-error.txt',
+    'snapshot 解析失败时 manifest 必须指向 parse error 文件。',
+  );
+  assertManifestFileMetadata(
+    output.bundleDir,
+    manifest.files?.snapshotParseError,
+    'snapshot-parse-error.txt',
+  );
+  assertEqual(
+    manifest.summary.snapshotStatus,
+    'CRITICAL',
+    'snapshot 解析失败时 manifest 必须记录 snapshot CRITICAL。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'snapshot.stdout.txt'),
+    'snapshot 解析失败时仍必须保存 stdout。',
+  );
+  assertFileExists(
+    path.join(output.bundleDir, 'snapshot-parse-error.txt'),
+    'snapshot 解析失败时必须保存 parse error 文件。',
+  );
+}
+
+function assertBundleRedactsProbeTokensFromArtifacts() {
+  const fixture = prepareFixture('redact-probe-token', {
+    snapshotIncludesProbeFlags: true,
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: directLiveArgs(fixture, [
+      '--phase',
+      'post-enable',
+      '--expected-gateway-mode',
+      'pingora-direct',
+      '--run-health-patrol',
+      '--fail-on-critical',
+    ]),
+  });
+
+  assertStatus(result, 0, '带 probe token 的证据包应成功生成。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'probe token 证据包 stdout');
+  const filesToCheck = [
+    'manifest.json',
+    'snapshot.json',
+    'snapshot.stdout.txt',
+    'snapshot-command.json',
+    'direct-live-command.json',
+  ];
+  for (const fileName of filesToCheck) {
+    const content = readTextFile(
+      path.join(output.bundleDir, fileName),
+      `证据包 ${fileName}`,
+    );
+    assertNotIncludes(
+      content,
+      'health-patrol-secret-token',
+      `${fileName} 不能泄露 health patrol probe token 原文。`,
+    );
+    assertNotIncludes(
+      content,
+      'pingora-gateway-secret-token',
+      `${fileName} 不能泄露 Pingora probe token 原文。`,
+    );
+    assertNotIncludes(
+      content,
+      'direct-live-secret-token',
+      `${fileName} 不能泄露 direct live probe token 原文。`,
+    );
+  }
+  const commandRecord = readJson(path.join(output.bundleDir, 'snapshot-command.json'));
+  assertIncludes(
+    commandRecord.args || [],
+    '--health-patrol-env-file',
+    'snapshot-command.json 结构化参数数组必须保留快照参数。',
+  );
+
+  const snapshot = readJson(path.join(output.bundleDir, 'snapshot.json'));
+  assertEqual(
+    snapshot.healthPatrolEnv?.values?.hasPingoraProbeToken,
+    true,
+    '证据包 snapshot.json 可以记录 health patrol probe token 是否存在。',
+  );
+  assertEqual(
+    snapshot.pingoraEnv?.values?.hasProbeToken,
+    true,
+    '证据包 snapshot.json 可以记录 Pingora probe token 是否存在。',
+  );
+  const healthPatrolCheck = snapshot.checks?.find(
+    (check) => check.name === 'production-health-patrol',
+  );
+  if (!healthPatrolCheck) {
+    failures.push('证据包 snapshot.json 必须保留生产巡检子检查结果。');
+  } else {
+    assertIncludes(
+      `${healthPatrolCheck.stdout}\n${healthPatrolCheck.stderr}`,
+      '<redacted>',
+      '证据包 snapshot.json 中的子检查 stdout/stderr 必须保留脱敏占位符。',
+    );
+  }
+}
+
+function readTextFile(filePath, label) {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch (error) {
+    failures.push(`无法读取 ${label}: ${error.message}`);
+    return '';
+  }
+}
+
+function assertManifestFileMetadata(bundleDir, metadata, expectedPath) {
+  if (!metadata || typeof metadata !== 'object') {
+    failures.push(`${expectedPath} 必须在 manifest.files 中记录结构化元数据。`);
+    return;
+  }
+  assertEqual(
+    metadata.path,
+    expectedPath,
+    `${expectedPath} manifest 元数据必须记录文件名。`,
+  );
+  const filePath = path.join(bundleDir, expectedPath);
+  const content = readFileSync(filePath);
+  assertEqual(
+    metadata.sizeBytes,
+    content.length,
+    `${expectedPath} manifest 元数据必须记录文件大小。`,
+  );
+  assertEqual(
+    metadata.sha256,
+    createHash('sha256').update(content).digest('hex'),
+    `${expectedPath} manifest 元数据必须记录 sha256。`,
+  );
+}
+
+function directLiveArgs(fixture, prefixArgs = []) {
+  return [
+    ...prefixArgs,
+    '--direct-live-script',
+    fixture.directLiveScript,
+    '--run-direct-live',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-probe-token',
+    'direct-live-secret-token',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--direct-pingora-access-log',
+    fixture.directAccessLog,
+    '--direct-access-log-since-lines',
+    '99',
+  ];
+}
+
+function assertRejectsRelativePaths() {
+  const fixture = prepareFixture('relative-path');
+  for (const [flag, value, expected] of [
+    ['--output-root', 'pingora-evidence', '--output-root 必须是绝对路径'],
+    ['--release-root', 'current', '--release-root 必须是绝对路径'],
+    ['--snapshot-script', 'snapshot.mjs', '--snapshot-script 必须是绝对路径'],
+  ]) {
+    const result = spawnSync(
+      'node',
+      [
+        BUNDLE_SCRIPT,
+        '--release-root',
+        fixture.releaseRoot,
+        '--output-root',
+        fixture.outputRoot,
+        '--health-patrol-env-file',
+        fixture.healthEnvFile,
+        '--pingora-env-file',
+        fixture.pingoraEnvFile,
+        '--snapshot-script',
+        fixture.snapshotScript,
+        flag,
+        value,
+      ],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+      },
+    );
+    if ((result.status ?? 0) === 0) {
+      failures.push(`${flag} 使用相对路径时必须失败。`);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      expected,
+      `${flag} 相对路径必须给出明确错误。`,
+    );
+  }
+}
+
+function assertRejectsFilesystemRootPaths() {
+  const fixture = prepareFixture('filesystem-root-path');
+  for (const [flag, expected] of [
+    ['--release-root', '--release-root 不能是文件系统根目录'],
+    ['--output-root', '--output-root 不能是文件系统根目录'],
+    ['--health-patrol-env-file', '--health-patrol-env-file 不能是文件系统根目录'],
+    ['--pingora-env-file', '--pingora-env-file 不能是文件系统根目录'],
+    ['--snapshot-script', '--snapshot-script 不能是文件系统根目录'],
+  ]) {
+    const result = spawnSync(
+      'node',
+      [
+        BUNDLE_SCRIPT,
+        '--release-root',
+        fixture.releaseRoot,
+        '--output-root',
+        fixture.outputRoot,
+        '--health-patrol-env-file',
+        fixture.healthEnvFile,
+        '--pingora-env-file',
+        fixture.pingoraEnvFile,
+        '--snapshot-script',
+        fixture.snapshotScript,
+        flag,
+        '/',
+      ],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+      },
+    );
+    if ((result.status ?? 0) === 0) {
+      failures.push(`${flag} 使用文件系统根目录时必须失败。`);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      expected,
+      `${flag} 文件系统根目录必须给出明确错误。`,
+    );
+    assertNotIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      '[fake-snapshot]',
+      `${flag} 文件系统根目录被拒绝时不应继续执行状态快照。`,
+    );
+  }
+
+  const directLogResult = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: [
+      ...directLiveArgs(fixture, [
+        '--phase',
+        'post-enable',
+        '--expected-gateway-mode',
+        'pingora-direct',
+      ]),
+      '--direct-pingora-access-log',
+      '/',
+    ],
+  });
+  if ((directLogResult.status ?? 0) === 0) {
+    failures.push('--direct-pingora-access-log 使用文件系统根目录时必须失败。');
+  }
+  assertIncludes(
+    `${directLogResult.stdout}\n${directLogResult.stderr}`,
+    '--direct-pingora-access-log 不能是文件系统根目录',
+    'direct live access log 指向文件系统根目录必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${directLogResult.stdout}\n${directLogResult.stderr}`,
+    '[fake-snapshot]',
+    'direct live access log 根目录被拒绝时不应执行状态快照。',
+  );
+}
+
+function assertRejectsUnsafePhase() {
+  const fixture = prepareFixture('unsafe-phase');
+  for (const phase of ['post enable', '../post-enable', 'post/enable', '回退']) {
+    const result = runBundle(fixture, {
+      status: 'OK',
+      extraArgs: ['--phase', phase],
+    });
+    if ((result.status ?? 0) === 0) {
+      failures.push(`--phase=${phase} 包含不安全字符时必须失败。`);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      '--phase 只能包含 ASCII 字母、数字、点、下划线或短横线',
+      `--phase=${phase} 必须给出明确错误。`,
+    );
+  }
+}
+
+function assertRejectsUnsafeCutoverRunId() {
+  const fixture = prepareFixture('unsafe-cutover-run-id');
+  for (const runId of ['cutover 1', '../cutover', '切换']) {
+    const result = runBundle(fixture, {
+      status: 'OK',
+      extraArgs: ['--cutover-run-id', runId],
+    });
+    if ((result.status ?? 0) === 0) {
+      failures.push(`--cutover-run-id=${runId} 包含不安全字符时必须失败。`);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      '--cutover-run-id 只能包含 ASCII 字母、数字、点、下划线或短横线',
+      `--cutover-run-id=${runId} 必须给出明确错误。`,
+    );
+  }
+}
+
+function assertRejectsSnapshotArgsWithControlCharacters() {
+  const fixture = prepareFixture('snapshot-control-character-arg');
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: [
+      '--phase',
+      'pre-cutover',
+      '--release-root',
+      `${fixture.releaseRoot}\n--fake-flag`,
+    ],
+  });
+
+  if ((result.status ?? 0) === 0) {
+    failures.push('证据包必须拒绝带换行的状态快照命令参数。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '状态快照命令参数不能包含换行或 NUL 字符',
+    '状态快照命令参数控制字符负例必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-snapshot]',
+    '状态快照命令参数被拒绝时不应执行状态快照。',
+  );
+}
+
+function assertRejectsDirectLiveArgsWithControlCharacters() {
+  const fixture = prepareFixture('direct-live-control-character-arg', {
+    directLiveStatus: 'OK',
+  });
+  for (const [flag, value, expected] of [
+    [
+      '--direct-probe-token',
+      'direct-token\n--fake-flag',
+      '--direct-probe-token 不能包含换行或 NUL 字符',
+    ],
+    [
+      '--direct-spacetime-database',
+      'genarrative\nprod',
+      '--direct-spacetime-database 不能包含换行或 NUL 字符',
+    ],
+    [
+      '--direct-pingora-access-log',
+      `${fixture.directAccessLog}\n--fake-flag`,
+      '--direct-pingora-access-log 不能包含换行或 NUL 字符',
+    ],
+    [
+      '--direct-access-log-since-lines',
+      '99\n1',
+      '--direct-access-log-since-lines 不能包含换行或 NUL 字符',
+    ],
+  ]) {
+    const result = runBundle(fixture, {
+      status: 'OK',
+      extraArgs: [
+        ...directLiveArgs(fixture, [
+          '--phase',
+          'post-enable',
+          '--expected-gateway-mode',
+          'pingora-direct',
+          '--fail-on-critical',
+        ]),
+        flag,
+        value,
+      ],
+    });
+
+    if ((result.status ?? 0) === 0) {
+      failures.push(`${flag} 带换行时必须在执行 direct live 前失败。`);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      expected,
+      `${flag} 控制字符负例必须给出明确错误。`,
+    );
+    assertNotIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      '[fake-snapshot]',
+      `${flag} 被拒绝时不应执行状态快照。`,
+    );
+    assertNotIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      '[fake-direct-live]',
+      `${flag} 被拒绝时不应执行 direct live。`,
+    );
+  }
+}
+
+function assertRejectsSymlinkOutputRootBeforeSnapshot() {
+  const fixture = prepareFixture('symlink-output-root');
+  const realTarget = path.join(tmpRoot, 'symlink-output-root-real-target');
+  rmSync(fixture.outputRoot, { recursive: true, force: true });
+  mkdirSync(realTarget, { recursive: true });
+  symlinkSync(realTarget, fixture.outputRoot, 'dir');
+
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: ['--phase', 'pre-cutover'],
+  });
+
+  if ((result.status ?? 0) === 0) {
+    failures.push('证据包必须拒绝符号链接 --output-root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--output-root 不能是符号链接',
+    '符号链接 output-root 负例必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-snapshot]',
+    '符号链接 output-root 被拒绝时不应继续执行状态快照。',
+  );
+  assertDirectoryEmpty(
+    realTarget,
+    '符号链接 output-root 被拒绝时不应写入真实目标目录。',
+  );
+}
+
+function assertRejectsSymlinkOutputRootParentBeforeSnapshot() {
+  const fixture = prepareFixture('symlink-output-root-parent');
+  const realTarget = path.join(
+    tmpRoot,
+    'symlink-output-root-parent-real-target',
+  );
+  const linkPath = path.join(tmpRoot, 'symlink-output-root-parent-link');
+  mkdirSync(realTarget, { recursive: true });
+  symlinkSync(realTarget, linkPath, 'dir');
+
+  const result = runBundle(
+    {
+      ...fixture,
+      outputRoot: path.join(linkPath, 'evidence'),
+    },
+    {
+      status: 'OK',
+      extraArgs: ['--phase', 'pre-cutover'],
+    },
+  );
+
+  if ((result.status ?? 0) === 0) {
+    failures.push('证据包必须拒绝符号链接 --output-root 上级目录。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--output-root 上级目录不能是符号链接',
+    '符号链接 output-root 上级目录负例必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-snapshot]',
+    '符号链接 output-root 上级目录被拒绝时不应继续执行状态快照。',
+  );
+  assertDirectoryEmpty(
+    realTarget,
+    '符号链接 output-root 上级目录被拒绝时不应写入真实目标目录。',
+  );
+}
+
+function assertRejectsFileOutputRootBeforeSnapshot() {
+  const fixture = prepareFixture('file-output-root');
+  rmSync(fixture.outputRoot, { recursive: true, force: true });
+  writeFileSync(fixture.outputRoot, 'not a directory\n', 'utf8');
+
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: ['--phase', 'pre-cutover'],
+  });
+
+  if ((result.status ?? 0) === 0) {
+    failures.push('证据包必须拒绝已存在但不是目录的 --output-root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--output-root 已存在但不是目录',
+    '非目录 output-root 负例必须给出明确错误。',
+  );
+  assertNotIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '[fake-snapshot]',
+    '非目录 output-root 被拒绝时不应继续执行状态快照。',
+  );
+  assertEqual(
+    readFileSync(fixture.outputRoot, 'utf8'),
+    'not a directory\n',
+    '非目录 output-root 被拒绝时不应改写原文件。',
+  );
+}
+
+function assertRejectsInvalidTimeout() {
+  const fixture = prepareFixture('invalid-timeout');
+  const cliResult = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: ['--timeout-ms', '0'],
+  });
+  if ((cliResult.status ?? 0) === 0) {
+    failures.push('证据包必须拒绝非正数 --timeout-ms。');
+  }
+  assertIncludes(
+    `${cliResult.stdout}\n${cliResult.stderr}`,
+    '--timeout-ms 必须是正整数',
+    '非法 --timeout-ms 必须给出明确错误。',
+  );
+
+  const envResult = runBundle(
+    fixture,
+    {
+      status: 'OK',
+      extraArgs: [],
+    },
+    {
+      GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS: 'abc',
+    },
+  );
+  if ((envResult.status ?? 0) === 0) {
+    failures.push('证据包必须拒绝非法 timeout env。');
+  }
+  assertIncludes(
+    `${envResult.stdout}\n${envResult.stderr}`,
+    'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS 必须是正整数',
+    '非法 timeout env 必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidBoolEnv() {
+  const fixture = prepareFixture('invalid-bool-env');
+  const cases = [
+    {
+      env: { GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL: 'ture' },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL 必须是布尔值',
+      reason: '证据包必须拒绝拼写错误的 run health patrol env。',
+    },
+    {
+      env: { GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_REQUIRE_PINGORA_GATEWAY: 'maybe' },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_REQUIRE_PINGORA_GATEWAY 必须是布尔值',
+      reason: '证据包必须拒绝非法 require pingora gateway env。',
+    },
+    {
+      env: { GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL: 'enabled' },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL 必须是布尔值',
+      reason: '证据包必须拒绝非法 fail on critical env。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = runBundle(
+      fixture,
+      {
+        status: 'OK',
+        extraArgs: [],
+      },
+      testCase.env,
+    );
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function prepareFixture(name, options = {}) {
+  const root = path.join(tmpRoot, name);
+  const releaseRoot = path.join(root, 'current');
+  const outputRoot = path.join(root, 'evidence');
+  const healthEnvFile = path.join(root, 'etc', 'health-patrol.env');
+  const pingoraEnvFile = path.join(root, 'etc', 'pingora-gateway.env');
+  const snapshotScript = path.join(
+    releaseRoot,
+    'scripts/ops/pingora-cutover-status-snapshot.mjs',
+  );
+  const directLiveScript = path.join(
+    releaseRoot,
+    'scripts/check-pingora-direct-live.mjs',
+  );
+  const directAccessLog = path.join(root, 'var/log/pingora-gateway.access.log');
+
+  mkdirSync(path.dirname(snapshotScript), { recursive: true });
+  mkdirSync(path.dirname(directLiveScript), { recursive: true });
+  mkdirSync(path.dirname(directAccessLog), { recursive: true });
+  mkdirSync(path.dirname(healthEnvFile), { recursive: true });
+  mkdirSync(outputRoot, { recursive: true });
+  const healthEnvText = [
+    'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx',
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=http://127.0.0.1',
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=',
+    'GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN=health-patrol-secret-token',
+    '',
+  ].join('\n');
+  writeFileSync(healthEnvFile, healthEnvText, 'utf8');
+  writeFileSync(
+    pingoraEnvFile,
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+      'GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN=pingora-gateway-secret-token',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    snapshotScript,
+    [
+      '#!/usr/bin/env node',
+      'const args = process.argv.slice(2);',
+      'const status = process.env.FAKE_SNAPSHOT_STATUS || "OK";',
+      `const outputMode = ${JSON.stringify(options.snapshotOutputMode || 'json')};`,
+      `const pingoraEnvValues = ${JSON.stringify(
+        options.snapshotPingoraEnvValues || {
+          listen: '127.0.0.1:18081',
+          tlsListen: '',
+          httpRedirectListen: '',
+          tlsCertFile: '',
+          tlsKeyFile: '',
+        },
+      )};`,
+      'const shadowReady = pingoraEnvValues.listen === "127.0.0.1:18081" && !pingoraEnvValues.tlsListen && !pingoraEnvValues.httpRedirectListen && !pingoraEnvValues.tlsCertFile && !pingoraEnvValues.tlsKeyFile;',
+      'const directReady = Boolean(pingoraEnvValues.tlsListen && pingoraEnvValues.httpRedirectListen && pingoraEnvValues.tlsCertFile && pingoraEnvValues.tlsKeyFile);',
+      'const pingoraEnvPosture = { mode: directReady ? "direct" : shadowReady ? "shadow" : "mixed", shadowReady, directReady };',
+      'const phaseIndex = args.indexOf("--phase");',
+      'console.error(`[fake-snapshot] ${status}`);',
+      'if (outputMode === "log-only") {',
+      '  console.log("[fake-snapshot] finished without json");',
+      '  process.exit(0);',
+      '}',
+      ...(options.snapshotIncludesProbeFlags
+        ? [
+            'import { readFileSync } from "node:fs";',
+            'function readEnv(file) {',
+            '  return Object.fromEntries(readFileSync(file, "utf8").split(/\\r?\\n/).filter(Boolean).filter((line) => !line.startsWith("#")).map((line) => line.split("=")).map(([key, ...value]) => [key, value.join("=")]));',
+            '}',
+            'const healthEnv = readEnv(args[args.indexOf("--health-patrol-env-file") + 1]);',
+            'const pingoraEnv = readEnv(args[args.indexOf("--pingora-env-file") + 1]);',
+          ]
+        : []),
+      'console.log(JSON.stringify({',
+      '  schemaVersion: 1,',
+      '  phase: phaseIndex >= 0 ? args[phaseIndex + 1] : "manual",',
+      '  summary: {',
+      '    status,',
+      '    criticalCount: status === "CRITICAL" ? 1 : 0,',
+      '    warningCount: 0,',
+      '  },',
+      ...(options.snapshotIncludesProbeFlags
+        ? [
+            '  healthPatrolEnv: { values: { hasPingoraProbeToken: Boolean(healthEnv.GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN || healthEnv.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN) } },',
+            '  pingoraEnv: { values: { ...pingoraEnvValues, hasProbeToken: Boolean(pingoraEnv.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN) }, posture: pingoraEnvPosture },',
+            '  checks: [{ name: "production-health-patrol", stdout: "probe stdout <redacted>:<redacted>", stderr: "probe stderr <redacted>:<redacted>" }],',
+          ]
+        : ['  pingoraEnv: { values: pingoraEnvValues, posture: pingoraEnvPosture },']),
+      '  args,',
+      '}, null, 2));',
+      'if (status === "CRITICAL" && args.includes("--fail-on-critical")) process.exit(1);',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodSync(snapshotScript, 0o755);
+  writeFileSync(
+    directAccessLog,
+    'ts=2026-06-16T00:00:00Z\trequest_id=direct-test\tpath=/\n',
+    'utf8',
+  );
+  writeFileSync(
+    directLiveScript,
+    [
+      '#!/usr/bin/env node',
+      'const args = process.argv.slice(2);',
+      `const status = ${JSON.stringify(options.directLiveStatus || 'OK')};`,
+      `const outputMode = ${JSON.stringify(options.directLiveOutputMode || 'json')};`,
+      'const accessLogIndex = args.indexOf("--pingora-access-log");',
+      'const sinceLinesIndex = args.indexOf("--access-log-since-lines");',
+      'const databaseIndex = args.indexOf("--spacetime-database");',
+      'console.log(`[pingora-direct-live] fake ${status}`);',
+      'console.error(`[fake-direct-live] ${status}`);',
+      'if (outputMode === "log-only") {',
+      '  console.log("[pingora-direct-live] finished without json");',
+      '  process.exit(0);',
+      '}',
+      'const accessLogResults = outputMode === "without-access-log" ? [] : [',
+      '  {',
+      '    name: "direct-access-log",',
+      '    logFile: accessLogIndex >= 0 ? args[accessLogIndex + 1] : "",',
+      '    sinceLines: sinceLinesIndex >= 0 ? Number(args[sinceLinesIndex + 1]) : 0,',
+      '    scannedLineCount: 1,',
+      '    checked: 2,',
+      '    matchedCount: status === "OK" ? 2 : 1,',
+      '    missingCount: status === "OK" ? 0 : 1,',
+      '    mismatchCount: 0,',
+      '    matched: [{',
+      '      name: "https-root",',
+      '      requestId: "direct-live-root",',
+      '      expectedMethod: "GET",',
+      '      expectedPath: "/",',
+      '      expectedStatusCode: 200,',
+      '      actualMethod: "GET",',
+      '      actualPath: "/",',
+      '      actualStatusCode: 200,',
+      '    }],',
+      '    missing: status === "OK" ? [] : [{',
+      '      name: "https-api-config",',
+      '      requestId: "direct-live-api",',
+      '      expectedMethod: "GET",',
+      '      expectedPath: "/api/creation-entry/config",',
+      '      expectedStatusCode: 200,',
+      '    }],',
+      '    mismatches: [],',
+      '  },',
+      '];',
+      'const staticAssetResult = {',
+      '  name: "https-static-asset",',
+      '  statusCode: 200,',
+      '  requestId: "direct-live-static",',
+      '  headers: {',
+      '    "cache-control": "no-cache",',
+      '    etag: "W/\\"1b-18bcfe56800\\"",',
+      '    "last-modified": "Tue, 14 Nov 2023 22:13:20 GMT",',
+      '    "accept-ranges": "bytes",',
+      '    "content-length": "27",',
+      '  },',
+      '  range: {',
+      '    name: "https-static-asset-range",',
+      '    statusCode: 206,',
+      '    headers: {',
+      '      "content-range": "bytes 0-0/27",',
+      '      "content-length": "1",',
+      '    },',
+      '  },',
+      '  notModified: {',
+      '    etag: {',
+      '      name: "https-static-asset-etag-304",',
+      '      statusCode: 304,',
+      '      headers: {',
+      '        "cache-control": "no-cache",',
+      '        etag: "W/\\"1b-18bcfe56800\\"",',
+      '      },',
+      '    },',
+      '    lastModified: {',
+      '      name: "https-static-asset-last-modified-304",',
+      '      statusCode: 304,',
+      '      headers: {',
+      '        "cache-control": "no-cache",',
+      '        "last-modified": "Tue, 14 Nov 2023 22:13:20 GMT",',
+      '      },',
+      '    },',
+      '  },',
+      '  fingerprinted: {',
+      '    name: "https-static-fingerprinted-asset",',
+      '    statusCode: 200,',
+      '    headers: {',
+      '      "cache-control": "public, max-age=31536000, immutable",',
+      '      etag: "W/\\"29-18bcfe56800\\"",',
+      '      "last-modified": "Tue, 14 Nov 2023 22:13:20 GMT",',
+      '      "accept-ranges": "bytes",',
+      '      "content-length": "41",',
+      '    },',
+      '    range: {',
+      '      name: "https-static-fingerprinted-asset-range",',
+      '      statusCode: 206,',
+      '      headers: {',
+      '        "content-range": "bytes 0-0/41",',
+      '        "content-length": "1",',
+      '      },',
+      '    },',
+      '    notModified: {',
+      '      etag: {',
+      '        name: "https-static-fingerprinted-asset-etag-304",',
+      '        statusCode: 304,',
+      '        headers: {',
+      '          "cache-control": "public, max-age=31536000, immutable",',
+      '          etag: "W/\\"29-18bcfe56800\\"",',
+      '        },',
+      '      },',
+      '      lastModified: {',
+      '        name: "https-static-fingerprinted-asset-last-modified-304",',
+      '        statusCode: 304,',
+      '        headers: {',
+      '          "cache-control": "public, max-age=31536000, immutable",',
+      '          "last-modified": "Tue, 14 Nov 2023 22:13:20 GMT",',
+      '        },',
+      '      },',
+      '    },',
+      '  },',
+      '};',
+      'if (outputMode === "bad-static-headers") {',
+      '  delete staticAssetResult.range;',
+      '  delete staticAssetResult.notModified;',
+      '}',
+      'const staticAssetResults = outputMode === "without-static-headers" ? [] : [staticAssetResult];',
+      'console.log(JSON.stringify({',
+      '  ok: status === "OK",',
+      '  results: [',
+      '    { name: "https-root", statusCode: 200, requestId: "direct-live-root" },',
+      '    ...staticAssetResults,',
+      '    ...accessLogResults,',
+      '    { name: "wss-spacetime-subscribe", database: databaseIndex >= 0 ? args[databaseIndex + 1] : "" },',
+      '  ],',
+      '  args,',
+      '}, null, 2));',
+      'console.log(status === "OK" ? "[pingora-direct-live] OK" : "[pingora-direct-live] FAILED");',
+      'if (status !== "OK") process.exit(1);',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodSync(directLiveScript, 0o755);
+
+  return {
+    releaseRoot,
+    outputRoot,
+    healthEnvFile,
+    pingoraEnvFile,
+    snapshotScript,
+    directLiveScript,
+    directAccessLog,
+    originalHealthEnvText: healthEnvText,
+  };
+}
+
+function runBundle(fixture, { status, extraArgs }, extraEnv = {}) {
+  return spawnSync(
+    'node',
+    [
+      BUNDLE_SCRIPT,
+      '--release-root',
+      fixture.releaseRoot,
+      '--output-root',
+      fixture.outputRoot,
+      '--health-patrol-env-file',
+      fixture.healthEnvFile,
+      '--pingora-env-file',
+      fixture.pingoraEnvFile,
+      '--snapshot-script',
+      fixture.snapshotScript,
+      ...extraArgs,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        GENARRATIVE_PINGORA_CUTOVER_RUN_ID: '',
+        ...extraEnv,
+        FAKE_SNAPSHOT_STATUS: status,
+      },
+    },
+  );
+}
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    failures.push(`${filePath} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function assertFileExists(filePath, reason) {
+  if (!filePath || !existsSync(filePath)) {
+    failures.push(`${reason} 缺少: ${filePath}`);
+  }
+}
+
+function assertFileUnchanged(filePath, expected, reason) {
+  const actual = readFileSync(filePath, 'utf8');
+  if (actual !== expected) {
+    failures.push(reason);
+  }
+}
+
+function assertDirectoryEmpty(directoryPath, reason) {
+  try {
+    const entries = readdirSync(directoryPath);
+    if (entries.length > 0) {
+      failures.push(`${reason} 实际包含: ${entries.join(', ')}`);
+    }
+  } catch (error) {
+    failures.push(`无法读取 ${directoryPath} 目录内容: ${error.message}`);
+  }
+}
+
+function assertMode(filePath, expected, reason) {
+  try {
+    const actual = statSync(filePath).mode & 0o777;
+    if (actual !== expected) {
+      failures.push(
+        `${reason} 实际 ${actual.toString(8)}，预期 ${expected.toString(8)}。`,
+      );
+    }
+  } catch (error) {
+    failures.push(`无法读取 ${filePath} 权限: ${error.message}`);
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  if ((result.status ?? 0) !== expected) {
+    failures.push(
+      `${reason} 实际退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 实际 ${actual}，预期 ${expected}。`);
+  }
+}
+
+function assertIncludes(value, expected, reason) {
+  const haystack = Array.isArray(value) ? value.join('\n') : String(value);
+  if (!haystack.includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
+
+function assertNotIncludes(value, unexpected, reason) {
+  const haystack = Array.isArray(value) ? value.join('\n') : String(value);
+  if (haystack.includes(unexpected)) {
+    failures.push(`${reason} 不应包含: ${unexpected}`);
+  }
+}
diff --git a/scripts/check-pingora-cutover-evidence-verify.mjs b/scripts/check-pingora-cutover-evidence-verify.mjs
new file mode 100644
index 000000000..83cc9c7b6
--- /dev/null
+++ b/scripts/check-pingora-cutover-evidence-verify.mjs
@@ -0,0 +1,597 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const VERIFY_SCRIPT = 'scripts/ops/pingora-cutover-evidence-verify.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-cutover-evidence-verify-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-cutover-evidence-verify] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-cutover-evidence-verify] OK');
+
+function main() {
+  assertScriptShape();
+  assertValidEvidenceBundleManifest();
+  assertValidCommandEvidenceManifest();
+  assertRequireSummaryOkPassesForOkManifest();
+  assertRequireSummaryOkFailsForCriticalManifest();
+  assertRequireSummaryOkFailsWhenSummaryMissing();
+  assertMissingSchemaVersionFails();
+  assertUnsupportedSchemaVersionFails();
+  assertMissingFileFails();
+  assertSizeMismatchFails();
+  assertSha256MismatchFails();
+  assertUnsafePathFails();
+  assertStringMetadataFailsExceptManifest();
+  assertExtraFileFailsByDefault();
+  assertExtraDirectoryFailsByDefault();
+  assertExtraSymlinkFailsByDefault();
+  assertAllowExtraFilesOverrideSucceeds();
+  assertRejectsRootPath();
+  assertRejectsEntryPathControlCharacters();
+  assertRejectsSymlinkBundleDir();
+  assertRejectsNonDirectoryBundleDir();
+  assertRejectsInvalidJson();
+  assertRejectsBothEntryModes();
+  assertRejectsRelativeEntryPath();
+  assertRejectsManifestFilePathControlCharacters();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(VERIFY_SCRIPT, 'utf8');
+  assertIncludes(
+    content,
+    'createHash',
+    '证据校验脚本必须计算 sha256。',
+  );
+  assertIncludes(
+    content,
+    'sizeBytes',
+    '证据校验脚本必须校验 sizeBytes。',
+  );
+  assertIncludes(
+    content,
+    '证据目录不能是符号链接',
+    '证据校验脚本必须拒绝符号链接证据目录。',
+  );
+  assertIncludes(
+    content,
+    '不会修改证据目录',
+    '证据校验脚本 usage 必须说明只读边界。',
+  );
+  assertIncludes(
+    content,
+    '未登记',
+    '证据校验脚本必须说明默认拒绝未登记证据条目。',
+  );
+  assertIncludes(
+    content,
+    '--allow-extra-files',
+    '证据校验脚本必须把未登记条目的例外开关显式化。',
+  );
+  assertIncludes(
+    content,
+    '--require-summary-ok',
+    '证据校验脚本必须支持正式 runbook 要求 summary OK。',
+  );
+  assertIncludes(
+    content,
+    'manifest.summary.status is not OK',
+    '证据校验脚本必须在 summary 非 OK 时给出结构化失败原因。',
+  );
+  assertIncludes(
+    content,
+    'manifest.schemaVersion 必须是 1',
+    '证据校验脚本必须拒绝未知 manifest schemaVersion。',
+  );
+  assertIncludes(
+    content,
+    'manifest.files.${key}.path',
+    '证据校验脚本必须校验 manifest.files 路径安全。',
+  );
+  if (
+    content.includes('writeFile') ||
+    content.includes('chmod(') ||
+    content.includes("spawn(") ||
+    content.includes('execFile')
+  ) {
+    failures.push('证据校验脚本必须保持只读，不能写文件或执行外部命令。');
+  }
+}
+
+function assertValidEvidenceBundleManifest() {
+  const fixture = prepareEvidenceBundleFixture('valid-bundle');
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 0, '合法证据包 manifest 应校验通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '合法证据包校验 stdout');
+  assertEqual(output.ok, true, '合法证据包 stdout 必须 ok=true。');
+  assertEqual(output.checkedCount, 4, '合法证据包必须校验四个元数据文件。');
+  assertEqual(output.failedCount, 0, '合法证据包不能有失败项。');
+  assertEqual(
+    output.files?.every((item) => item.status === 'OK'),
+    true,
+    '合法证据包每个文件都应 OK。',
+  );
+}
+
+function assertValidCommandEvidenceManifest() {
+  const fixture = prepareCommandEvidenceFixture('valid-command');
+  const result = runVerify(['--manifest', path.join(fixture.dir, 'manifest.json')]);
+  assertStatus(result, 0, '合法命令证据 manifest 应校验通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '合法命令证据校验 stdout');
+  assertEqual(output.ok, true, '合法命令证据 stdout 必须 ok=true。');
+  assertEqual(output.checkedCount, 3, '合法命令证据必须校验三个元数据文件。');
+}
+
+function assertRequireSummaryOkPassesForOkManifest() {
+  const fixture = prepareEvidenceBundleFixture('summary-ok');
+  const result = runVerify(['--bundle-dir', fixture.dir, '--require-summary-ok']);
+  assertStatus(result, 0, '要求 summary OK 且 manifest.summary.status=OK 时应通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'summary OK 校验 stdout');
+  assertEqual(output.ok, true, 'summary OK 校验 stdout 必须 ok=true。');
+  assertEqual(
+    output.requireSummaryOk,
+    true,
+    'summary OK 校验 stdout 必须记录 requireSummaryOk=true。',
+  );
+  assertEqual(
+    output.summary?.status,
+    'OK',
+    'summary OK 校验 stdout 必须输出 summary.status=OK。',
+  );
+}
+
+function assertRequireSummaryOkFailsForCriticalManifest() {
+  const fixture = prepareEvidenceBundleFixture('summary-critical');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  manifest.summary.status = 'CRITICAL';
+  writeJson(manifestPath, manifest);
+  const result = runVerify(['--bundle-dir', fixture.dir, '--require-summary-ok']);
+  assertStatus(result, 1, '要求 summary OK 但 manifest.summary.status=CRITICAL 时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.status is not OK',
+    'summary 非 OK 失败必须写入 JSON reason。',
+  );
+}
+
+function assertRequireSummaryOkFailsWhenSummaryMissing() {
+  const fixture = prepareCommandEvidenceFixture('summary-missing');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  delete manifest.summary;
+  writeJson(manifestPath, manifest);
+  const result = runVerify(['--bundle-dir', fixture.dir, '--require-summary-ok']);
+  assertStatus(result, 1, '要求 summary OK 但 manifest 缺少 summary 时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.status is not OK',
+    '缺少 summary 失败必须写入 JSON reason。',
+  );
+}
+
+function assertMissingSchemaVersionFails() {
+  const fixture = prepareEvidenceBundleFixture('schema-version-missing');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  delete manifest.schemaVersion;
+  writeJson(manifestPath, manifest);
+
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, 'manifest 缺少 schemaVersion 时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'manifest.schemaVersion 必须是 1',
+    '缺少 manifest schemaVersion 必须给出明确错误。',
+  );
+}
+
+function assertUnsupportedSchemaVersionFails() {
+  const fixture = prepareCommandEvidenceFixture('schema-version-unsupported');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  manifest.schemaVersion = 2;
+  writeJson(manifestPath, manifest);
+
+  const result = runVerify(['--manifest', manifestPath]);
+  assertStatus(result, 1, 'manifest schemaVersion 非 1 时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'manifest.schemaVersion 必须是 1',
+    '未知 manifest schemaVersion 必须给出明确错误。',
+  );
+}
+
+function assertMissingFileFails() {
+  const fixture = prepareEvidenceBundleFixture('missing-file');
+  rmSync(path.join(fixture.dir, 'snapshot.stderr.txt'), { force: true });
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, 'manifest 指向缺失文件时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'missing file',
+    '缺失文件失败必须写入 JSON reason。',
+  );
+}
+
+function assertSizeMismatchFails() {
+  const fixture = prepareEvidenceBundleFixture('size-mismatch');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  manifest.files.snapshot.sizeBytes += 1;
+  writeJson(manifestPath, manifest);
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, 'sizeBytes 不一致时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'size mismatch',
+    'sizeBytes 不一致必须写入 JSON reason。',
+  );
+}
+
+function assertSha256MismatchFails() {
+  const fixture = prepareEvidenceBundleFixture('sha256-mismatch');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  manifest.files.snapshot.sha256 = '0'.repeat(64);
+  writeJson(manifestPath, manifest);
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, 'sha256 不一致时必须失败。');
+  assertIncludes(
+    result.stdout,
+    'sha256 mismatch',
+    'sha256 不一致必须写入 JSON reason。',
+  );
+}
+
+function assertUnsafePathFails() {
+  const fixture = prepareEvidenceBundleFixture('unsafe-path');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  manifest.files.snapshot.path = '../snapshot.json';
+  writeJson(manifestPath, manifest);
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, 'manifest 文件 path 逃逸证据目录时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '只能是证据目录内的安全文件名',
+    'unsafe path 失败必须给出明确错误。',
+  );
+}
+
+function assertStringMetadataFailsExceptManifest() {
+  const fixture = prepareEvidenceBundleFixture('string-metadata');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  manifest.files.snapshot = 'snapshot.json';
+  writeJson(manifestPath, manifest);
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, '非 manifest 文件仍用字符串登记时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '必须使用 { path, sizeBytes, sha256 } 元数据对象',
+    '字符串 metadata 失败必须给出明确错误。',
+  );
+}
+
+function assertExtraFileFailsByDefault() {
+  const fixture = prepareEvidenceBundleFixture('extra-file');
+  writeFileSync(path.join(fixture.dir, 'operator-note.txt'), 'manual note\n', 'utf8');
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, '证据目录混入未登记普通文件时默认必须失败。');
+  assertIncludes(
+    result.stdout,
+    'extra file not registered in manifest.files',
+    '未登记普通文件失败必须写入 JSON reason。',
+  );
+  assertIncludes(
+    result.stdout,
+    'operator-note.txt',
+    '未登记普通文件失败必须输出文件名。',
+  );
+}
+
+function assertExtraDirectoryFailsByDefault() {
+  const fixture = prepareEvidenceBundleFixture('extra-directory');
+  mkdirSync(path.join(fixture.dir, 'notes'), { recursive: true });
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, '证据目录混入未登记目录时默认必须失败。');
+  assertIncludes(
+    result.stdout,
+    'extra directory not registered in manifest.files',
+    '未登记目录失败必须写入 JSON reason。',
+  );
+}
+
+function assertExtraSymlinkFailsByDefault() {
+  const fixture = prepareEvidenceBundleFixture('extra-symlink');
+  writeFileSync(path.join(fixture.dir, 'target.txt'), 'target\n', 'utf8');
+  const manifest = readJson(path.join(fixture.dir, 'manifest.json'));
+  manifest.files.target = metadataFor(path.join(fixture.dir, 'target.txt'));
+  writeJson(path.join(fixture.dir, 'manifest.json'), manifest);
+  symlinkSync(path.join(fixture.dir, 'target.txt'), path.join(fixture.dir, 'target-link.txt'));
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, '证据目录混入未登记符号链接时默认必须失败。');
+  assertIncludes(
+    result.stdout,
+    'extra symlink not registered in manifest.files',
+    '未登记符号链接失败必须写入 JSON reason。',
+  );
+}
+
+function assertAllowExtraFilesOverrideSucceeds() {
+  const fixture = prepareEvidenceBundleFixture('allow-extra-file');
+  writeFileSync(path.join(fixture.dir, 'operator-note.txt'), 'manual note\n', 'utf8');
+  const result = runVerify(['--bundle-dir', fixture.dir, '--allow-extra-files']);
+  assertStatus(result, 0, '显式允许未登记文件时 verifier 应通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, '允许未登记文件校验 stdout');
+  assertEqual(output.ok, true, '允许未登记文件时 stdout 必须 ok=true。');
+  assertEqual(
+    output.allowExtraFiles,
+    true,
+    '允许未登记文件时 stdout 必须记录 allowExtraFiles=true。',
+  );
+  assertEqual(
+    output.extraFiles?.length,
+    0,
+    '允许未登记文件时 stdout 不应输出失败 extraFiles。',
+  );
+}
+
+function assertRejectsRootPath() {
+  const result = runVerify(['--bundle-dir', path.parse(process.cwd()).root]);
+  assertStatus(result, 1, '证据目录为文件系统根目录时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '不能是文件系统根目录',
+    '根目录失败必须给出明确错误。',
+  );
+}
+
+function assertRejectsEntryPathControlCharacters() {
+  const fixture = prepareEvidenceBundleFixture('entry-control-character');
+  const result = runVerify(['--bundle-dir', `${fixture.dir}\n--allow-extra-files`]);
+  assertStatus(result, 1, '入口路径带换行控制字符时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--bundle-dir 不能包含换行或 NUL 字符',
+    '入口路径控制字符失败必须给出明确错误。',
+  );
+}
+
+function assertRejectsSymlinkBundleDir() {
+  const fixture = prepareEvidenceBundleFixture('symlink-target');
+  const linkPath = path.join(tmpRoot, 'symlink-bundle');
+  symlinkSync(fixture.dir, linkPath);
+  const result = runVerify(['--bundle-dir', linkPath]);
+  assertStatus(result, 1, '证据目录是符号链接时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '证据目录不能是符号链接',
+    '符号链接证据目录失败必须给出明确错误。',
+  );
+}
+
+function assertRejectsNonDirectoryBundleDir() {
+  const filePath = path.join(tmpRoot, 'not-a-dir');
+  writeFileSync(filePath, 'not a dir\n', 'utf8');
+  const result = runVerify(['--bundle-dir', filePath]);
+  assertStatus(result, 1, '证据目录不是目录时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '证据目录必须是目录',
+    '非目录证据路径失败必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidJson() {
+  const dir = path.join(tmpRoot, 'invalid-json');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, 'manifest.json'), '{ not json\n', 'utf8');
+  const result = runVerify(['--bundle-dir', dir]);
+  assertStatus(result, 1, 'manifest JSON 非法时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'manifest 不是合法 JSON',
+    '非法 JSON 失败必须给出明确错误。',
+  );
+}
+
+function assertRejectsBothEntryModes() {
+  const fixture = prepareEvidenceBundleFixture('both-entry-modes');
+  const result = runVerify([
+    '--bundle-dir',
+    fixture.dir,
+    '--manifest',
+    path.join(fixture.dir, 'manifest.json'),
+  ]);
+  assertStatus(result, 1, '同时提供 manifest 和 bundle-dir 时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '只能二选一',
+    '入口参数互斥失败必须给出明确错误。',
+  );
+}
+
+function assertRejectsRelativeEntryPath() {
+  const result = runVerify(['--bundle-dir', 'relative-evidence']);
+  assertStatus(result, 1, '入口路径是相对路径时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '必须是绝对路径',
+    '相对路径失败必须给出明确错误。',
+  );
+}
+
+function assertRejectsManifestFilePathControlCharacters() {
+  const fixture = prepareEvidenceBundleFixture('metadata-control-character');
+  const manifestPath = path.join(fixture.dir, 'manifest.json');
+  const manifest = readJson(manifestPath);
+  manifest.files.snapshot.path = 'snapshot.json\noperator-note.txt';
+  writeJson(manifestPath, manifest);
+  const result = runVerify(['--bundle-dir', fixture.dir]);
+  assertStatus(result, 1, 'manifest 文件 path 带控制字符时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '只能是证据目录内的安全文件名',
+    'manifest 文件 path 控制字符失败必须给出明确错误。',
+  );
+}
+
+function prepareEvidenceBundleFixture(name) {
+  const dir = path.join(tmpRoot, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, 'snapshot.json'), '{"ok":true}\n', 'utf8');
+  writeFileSync(path.join(dir, 'snapshot.stdout.txt'), '{"ok":true}\n', 'utf8');
+  writeFileSync(path.join(dir, 'snapshot.stderr.txt'), '', 'utf8');
+  writeFileSync(
+    path.join(dir, 'snapshot-command.json'),
+    '{"executable":"node"}\n',
+    'utf8',
+  );
+  writeJson(path.join(dir, 'manifest.json'), {
+    schemaVersion: 1,
+    summary: {
+      status: 'OK',
+    },
+    files: {
+      manifest: 'manifest.json',
+      snapshot: metadataFor(path.join(dir, 'snapshot.json')),
+      snapshotParseError: null,
+      snapshotStdout: metadataFor(path.join(dir, 'snapshot.stdout.txt')),
+      snapshotStderr: metadataFor(path.join(dir, 'snapshot.stderr.txt')),
+      snapshotCommand: metadataFor(path.join(dir, 'snapshot-command.json')),
+      directLive: null,
+      directLiveParseError: null,
+      directLiveStdout: null,
+      directLiveStderr: null,
+      directLiveCommand: null,
+    },
+  });
+  return { dir };
+}
+
+function prepareCommandEvidenceFixture(name) {
+  const dir = path.join(tmpRoot, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, 'command.stdout.txt'), 'ok\n', 'utf8');
+  writeFileSync(path.join(dir, 'command.stderr.txt'), '', 'utf8');
+  writeFileSync(
+    path.join(dir, 'command-record.json'),
+    '{"exitCode":0}\n',
+    'utf8',
+  );
+  writeJson(path.join(dir, 'manifest.json'), {
+    schemaVersion: 1,
+    summary: {
+      status: 'OK',
+      exitCode: 0,
+    },
+    files: {
+      manifest: 'manifest.json',
+      stdout: metadataFor(path.join(dir, 'command.stdout.txt')),
+      stderr: metadataFor(path.join(dir, 'command.stderr.txt')),
+      commandRecord: metadataFor(path.join(dir, 'command-record.json')),
+    },
+  });
+  return { dir };
+}
+
+function metadataFor(filePath) {
+  const content = readFileSync(filePath);
+  return {
+    path: path.basename(filePath),
+    sizeBytes: content.length,
+    sha256: createHash('sha256').update(content).digest('hex'),
+  };
+}
+
+function runVerify(args) {
+  return spawnSync('node', [VERIFY_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    failures.push(`${filePath} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function writeJson(filePath, value) {
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function parseJson(raw, label) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}\n${raw}`);
+    return {};
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!String(content).includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 预期 ${JSON.stringify(expected)}，实际 ${JSON.stringify(actual)}`);
+  }
+}
diff --git a/scripts/check-pingora-cutover-status-snapshot.mjs b/scripts/check-pingora-cutover-status-snapshot.mjs
new file mode 100644
index 000000000..646ff49a0
--- /dev/null
+++ b/scripts/check-pingora-cutover-status-snapshot.mjs
@@ -0,0 +1,1116 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const SNAPSHOT_SCRIPT = 'scripts/ops/pingora-cutover-status-snapshot.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-cutover-snapshot-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-cutover-status-snapshot] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-cutover-status-snapshot] OK');
+
+function main() {
+  assertScriptShape();
+  assertSnapshotSucceedsWithFakeSystemctlAndReleaseRoot();
+  assertSnapshotAcceptsExpectedDirectPingoraEnvMode();
+  assertSnapshotRejectsDirectPingoraEnvModeDrift();
+  assertSnapshotRejectsShadowPingoraEnvModeDrift();
+  assertSnapshotRedactsEnvProbeTokens();
+  assertFailOnCriticalRejectsEnvDriftWithoutWritingEnv();
+  assertFailOnCriticalRejectsMissingDirectCapability();
+  assertFailOnCriticalRejectsSystemdPingoraEnvDrift();
+  assertFailOnCriticalRejectsReleaseAuditFailure();
+  assertRejectsRelativePaths();
+  assertRejectsPathArgsWithControlCharacters();
+  assertRejectsFilesystemRootReleaseRoot();
+  assertRejectsFilesystemRootEnvFiles();
+  assertRejectsInvalidTimeout();
+  assertRejectsInvalidBoolEnv();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(SNAPSHOT_SCRIPT, 'utf8');
+  assertIncludes(
+    content,
+    '该脚本只读采集状态',
+    '状态快照脚本必须在 usage 中说明只读边界。',
+  );
+  assertIncludes(
+    content,
+    'scripts/ops/pingora-current-release-audit.mjs',
+    '状态快照必须把 current release 自审脚本纳入 release artifact 采集。',
+  );
+  assertIncludes(
+    content,
+    'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    '状态快照必须把直连彩排状态脚本纳入 release artifact 采集。',
+  );
+  assertIncludes(
+    content,
+    'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    '状态快照必须把证据根目录审计脚本纳入 release artifact 采集。',
+  );
+  assertIncludes(
+    content,
+    'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    '状态快照必须把证据验真脚本纳入 release artifact 采集。',
+  );
+  assertIncludes(
+    content,
+    'current-release-audit',
+    '状态快照必须执行 current release 自审并把结果纳入 checks。',
+  );
+  assertIncludes(
+    content,
+    'releaseManifest',
+    '状态快照必须收录 current release manifest 自审结果。',
+  );
+  assertIncludes(
+    content,
+    'scripts/ops/production-health-patrol.mjs',
+    '状态快照必须能调用 current release 随包生产巡检脚本。',
+  );
+  assertIncludes(
+    content,
+    'scripts/check-production-health-patrol-env.mjs',
+    '状态快照必须复用 current release 随包 env 复核脚本。',
+  );
+  assertIncludes(
+    content,
+    'scripts/check-pingora-release-readiness.mjs',
+    '状态快照必须把 release readiness 聚合门禁脚本纳入 release artifact 采集。',
+  );
+  assertIncludes(
+    content,
+    'scripts/check-pingora-canary-live.mjs',
+    '状态快照必须把 canary live 脚本纳入 release artifact 采集。',
+  );
+  assertIncludes(
+    content,
+    'scripts/check-pingora-canary-access-log-parity.mjs',
+    '状态快照必须把 canary access log 对账脚本纳入 release artifact 采集。',
+  );
+  assertIncludes(
+    content,
+    'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    '状态快照必须记录 Pingora 低端口 capability 是否生效。',
+  );
+  assertIncludes(
+    content,
+    '--expected-pingora-env-mode',
+    '状态快照必须支持按阶段强制校验 active Pingora env 姿态。',
+  );
+  assertIncludes(
+    content,
+    'summarizePingoraEnvPosture',
+    '状态快照必须输出 Pingora env shadow/direct 姿态摘要。',
+  );
+  if (content.includes('writeFile') || content.includes('rmSync(')) {
+    failures.push('状态快照脚本不应写文件或删除文件。');
+  }
+}
+
+function assertSnapshotSucceedsWithFakeSystemctlAndReleaseRoot() {
+  const fixture = prepareFixture('direct-ok', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: true,
+    pingoraActive: true,
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--run-health-patrol',
+    '--require-pingora-gateway',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 0, 'fake systemctl/release root 下 direct 快照应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+  const payload = parseJson(result.stdout, 'direct 快照输出');
+  assertEqual(payload.phase, 'post-enable', '快照必须记录阶段标签。');
+  assertEqual(
+    payload.healthPatrolEnv.values.gatewayMode,
+    'pingora-direct',
+    '快照必须记录 health patrol gateway mode。',
+  );
+  assertEqual(
+    payload.systemd.pingoraUnit.hasAmbientCapability,
+    true,
+    'direct 快照必须看到 AmbientCapabilities。',
+  );
+  assertEqual(
+    payload.systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile,
+    true,
+    'direct 快照必须确认 systemd EnvironmentFile 指向本次 pingora env。',
+  );
+  assertEqual(
+    payload.summary.status,
+    'OK',
+    'direct 快照所有 fake 检查通过时 summary 应为 OK。',
+  );
+  assertEqual(
+    payload.pingoraEnv?.posture?.mode,
+    'direct',
+    '状态快照必须能把完整低端口 TLS env 识别为 direct 姿态。',
+  );
+  assertEqual(
+    payload.pingoraEnv?.posture?.directReady,
+    true,
+    '完整低端口 TLS env 必须标记 directReady=true。',
+  );
+  const healthPatrolCheck = payload.checks.find(
+    (check) => check.name === 'production-health-patrol',
+  );
+  if (!healthPatrolCheck) {
+    failures.push('启用 --run-health-patrol 时快照必须收录生产巡检结果。');
+  } else {
+    assertIncludes(
+      healthPatrolCheck.stdout,
+      '"gatewayMode":"pingora-direct"',
+      '生产巡检子进程必须读取 health patrol env。',
+    );
+  }
+  const releaseAuditCheck = payload.checks.find(
+    (check) => check.name === 'current-release-audit',
+  );
+  if (!releaseAuditCheck) {
+    failures.push('状态快照必须收录 current release 自审结果。');
+  } else {
+    assertEqual(
+      releaseAuditCheck.status,
+      'OK',
+      '完整 fake release 的 current release 自审应通过。',
+    );
+    assertEqual(
+      releaseAuditCheck.details?.summary?.status,
+      'OK',
+      '状态快照必须保留 current release 自审 summary。',
+    );
+    const pingoraChecksum = releaseAuditCheck.details?.checksums?.find(
+      (checksum) => checksum.path === 'pingora-gateway',
+    );
+    if (!pingoraChecksum || pingoraChecksum.matches !== true) {
+      failures.push(
+        '状态快照必须保留 pingora-gateway checksum 匹配结果。',
+      );
+    }
+    assertEqual(
+      releaseAuditCheck.details?.releaseManifest?.status,
+      'OK',
+      '状态快照必须保留 release manifest 自审状态。',
+    );
+  }
+  const canaryLogParityArtifact = payload.releaseArtifacts.artifacts.find(
+    (item) => item.path === 'scripts/check-pingora-canary-access-log-parity.mjs',
+  );
+  if (!canaryLogParityArtifact || canaryLogParityArtifact.status !== 'OK') {
+    failures.push('快照必须确认 current release 已包含 canary access log 对账脚本。');
+  }
+  const rehearsalStatusArtifact = payload.releaseArtifacts.artifacts.find(
+    (item) => item.path === 'scripts/ops/pingora-direct-rehearsal-status.mjs',
+  );
+  if (!rehearsalStatusArtifact || rehearsalStatusArtifact.status !== 'OK') {
+    failures.push('快照必须确认 current release 已包含直连彩排状态脚本。');
+  }
+  const evidenceAuditArtifact = payload.releaseArtifacts.artifacts.find(
+    (item) => item.path === 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+  );
+  if (!evidenceAuditArtifact || evidenceAuditArtifact.status !== 'OK') {
+    failures.push('快照必须确认 current release 已包含证据根目录审计脚本。');
+  }
+  const commandsLog = readTextFile(fixture.commandsLog, 'fake systemctl 日志');
+  assertIncludes(
+    commandsLog,
+    'systemctl is-active genarrative-pingora-gateway.service',
+    '快照必须通过 fake systemctl 检查 Pingora service。',
+  );
+  assertFileUnchanged(
+    fixture.healthEnvFile,
+    fixture.originalHealthEnvText,
+    '成功快照不应改写 health patrol env。',
+  );
+}
+
+function assertSnapshotAcceptsExpectedDirectPingoraEnvMode() {
+  const fixture = prepareFixture('direct-env-mode-ok', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: true,
+    pingoraActive: true,
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-pingora-env-mode',
+    'direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 0, 'direct env 姿态符合预期时快照应成功。');
+  const payload = parseJson(result.stdout, 'direct env 姿态快照输出');
+  assertEqual(
+    payload.pingoraEnv?.posture?.expectedMode,
+    'direct',
+    '快照必须记录 expected Pingora env mode。',
+  );
+  assertEqual(
+    payload.pingoraEnv?.posture?.directReady,
+    true,
+    'direct env 姿态正例必须 directReady=true。',
+  );
+}
+
+function assertSnapshotRejectsDirectPingoraEnvModeDrift() {
+  const fixture = prepareFixture('direct-env-mode-drift', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: true,
+    pingoraActive: true,
+    pingoraEnvMode: 'shadow',
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-pingora-env-mode',
+    'direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(
+    result,
+    1,
+    '启用后要求 direct env 但 active env 仍是 shadow 时必须失败。',
+  );
+  const payload = parseJson(result.stdout, 'direct env 漂移快照输出');
+  assertEqual(
+    payload.pingoraEnv?.status,
+    'CRITICAL',
+    'direct env 漂移必须标记 pingoraEnv 为 CRITICAL。',
+  );
+  assertIncludes(
+    payload.pingoraEnv?.diagnostics || [],
+    'Pingora direct env 要求 tlsListen 已配置',
+    'direct env 漂移必须给出缺少 tlsListen 的诊断。',
+  );
+}
+
+function assertSnapshotRejectsShadowPingoraEnvModeDrift() {
+  const fixture = prepareFixture('shadow-env-mode-drift', {
+    gatewayMode: 'nginx',
+    publicBaseUrl: 'https://example.com',
+    publicHost: '',
+    directCapability: false,
+    pingoraActive: true,
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-rollback',
+    '--expected-gateway-mode',
+    'nginx',
+    '--expected-pingora-env-mode',
+    'shadow',
+    '--expected-public-base-url',
+    'https://example.com',
+    '--require-empty-public-host',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(
+    result,
+    1,
+    '回退后要求 shadow env 但 active env 仍有 direct 配置时必须失败。',
+  );
+  const payload = parseJson(result.stdout, 'shadow env 漂移快照输出');
+  assertEqual(
+    payload.pingoraEnv?.posture?.shadowReady,
+    false,
+    'shadow env 漂移必须标记 shadowReady=false。',
+  );
+  assertIncludes(
+    payload.pingoraEnv?.diagnostics || [],
+    'tlsCertFile 为空',
+    'shadow env 漂移必须给出 TLS cert 残留诊断。',
+  );
+}
+
+function assertFailOnCriticalRejectsEnvDriftWithoutWritingEnv() {
+  const fixture = prepareFixture('env-drift', {
+    gatewayMode: 'nginx',
+    publicBaseUrl: 'http://127.0.0.1',
+    publicHost: '',
+    directCapability: false,
+    pingoraActive: false,
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 1, 'health patrol env 漂移时 fail-on-critical 必须失败。');
+  const payload = parseJson(result.stdout, 'env 漂移快照输出');
+  assertEqual(
+    payload.healthPatrolEnv.status,
+    'CRITICAL',
+    'env 漂移必须标记为 CRITICAL。',
+  );
+  assertFileUnchanged(
+    fixture.healthEnvFile,
+    fixture.originalHealthEnvText,
+    '失败快照不应改写 health patrol env。',
+  );
+}
+
+function assertSnapshotRedactsEnvProbeTokens() {
+  const fixture = prepareFixture('redact-probe-token', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: true,
+    pingoraActive: true,
+    healthProbeToken: 'health-patrol-secret-token',
+    pingoraProbeToken: 'pingora-gateway-secret-token',
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--run-health-patrol',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 0, '带 probe token 的状态快照应成功。');
+  assertNotIncludes(
+    result.stdout,
+    'health-patrol-secret-token',
+    '状态快照 stdout 不能泄露 health patrol probe token 原文。',
+  );
+  assertNotIncludes(
+    result.stdout,
+    'pingora-gateway-secret-token',
+    '状态快照 stdout 不能泄露 Pingora probe token 原文。',
+  );
+  const payload = parseJson(result.stdout, 'probe token 脱敏快照输出');
+  assertEqual(
+    payload.healthPatrolEnv?.values?.hasPingoraProbeToken,
+    true,
+    '状态快照可以记录 health patrol probe token 是否存在。',
+  );
+  assertEqual(
+    payload.pingoraEnv?.values?.hasProbeToken,
+    true,
+    '状态快照可以记录 Pingora probe token 是否存在。',
+  );
+  const healthPatrolCheck = payload.checks?.find(
+    (check) => check.name === 'production-health-patrol',
+  );
+  assertIncludes(
+    healthPatrolCheck?.stdout || '',
+    '<redacted>',
+    '生产巡检 stdout 里的 probe token 必须被脱敏后进入快照。',
+  );
+  assertIncludes(
+    healthPatrolCheck?.stderr || '',
+    '<redacted>',
+    '生产巡检 stderr 里的 probe token 必须被脱敏后进入快照。',
+  );
+  assertNotIncludes(
+    healthPatrolCheck?.stdout || '',
+    'health-patrol-secret-token',
+    '生产巡检 stdout 进入快照时不能泄露 health patrol probe token 原文。',
+  );
+  assertNotIncludes(
+    healthPatrolCheck?.stdout || '',
+    'pingora-gateway-secret-token',
+    '生产巡检 stdout 进入快照时不能泄露 Pingora probe token 原文。',
+  );
+  assertNotIncludes(
+    healthPatrolCheck?.stderr || '',
+    'health-patrol-secret-token',
+    '生产巡检 stderr 进入快照时不能泄露 health patrol probe token 原文。',
+  );
+  assertNotIncludes(
+    healthPatrolCheck?.stderr || '',
+    'pingora-gateway-secret-token',
+    '生产巡检 stderr 进入快照时不能泄露 Pingora probe token 原文。',
+  );
+}
+
+function assertFailOnCriticalRejectsMissingDirectCapability() {
+  const fixture = prepareFixture('missing-capability', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: false,
+    pingoraActive: true,
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(
+    result,
+    1,
+    'direct 模式缺少低端口 capability 时 fail-on-critical 必须失败。',
+  );
+  const payload = parseJson(result.stdout, '缺 capability 快照输出');
+  assertEqual(
+    payload.systemd.pingoraUnit.status,
+    'CRITICAL',
+    '缺少 direct capability 必须标记 Pingora unit 为 CRITICAL。',
+  );
+}
+
+function assertFailOnCriticalRejectsSystemdPingoraEnvDrift() {
+  const fixture = prepareFixture('systemd-pingora-env-drift', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: true,
+    pingoraActive: true,
+    systemdPingoraEnvFile: 'prefix',
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(
+    result,
+    1,
+    'systemd EnvironmentFile 与 --pingora-env-file 漂移时 fail-on-critical 必须失败。',
+  );
+  const payload = parseJson(result.stdout, 'systemd env 漂移快照输出');
+  assertEqual(
+    payload.systemd?.pingoraUnit?.environmentFileMatchesPingoraEnvFile,
+    false,
+    'systemd env 漂移时必须记录 EnvironmentFile 未匹配。',
+  );
+  assertIncludes(
+    payload.systemd?.pingoraUnit?.diagnostics || [],
+    'EnvironmentFile 未包含本次 --pingora-env-file',
+    'systemd env 漂移时必须给出明确诊断。',
+  );
+}
+
+function assertFailOnCriticalRejectsReleaseAuditFailure() {
+  const fixture = prepareFixture('bad-release-audit', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: true,
+    pingoraActive: true,
+  });
+  writeFileSync(
+    path.join(fixture.releaseRoot, 'pingora-gateway.sha256'),
+    `${'0'.repeat(64)}  pingora-gateway\n`,
+    'utf8',
+  );
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--require-pingora-gateway',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 1, 'current release 自审失败时 snapshot 必须失败。');
+  const payload = parseJson(result.stdout, '自审失败快照输出');
+  const releaseAuditCheck = payload.checks?.find(
+    (check) => check.name === 'current-release-audit',
+  );
+  if (!releaseAuditCheck || releaseAuditCheck.status !== 'CRITICAL') {
+    failures.push('自审失败时 current-release-audit check 必须标记 CRITICAL。');
+  }
+  const pingoraChecksum = releaseAuditCheck?.details?.checksums?.find(
+    (checksum) => checksum.path === 'pingora-gateway',
+  );
+  if (!pingoraChecksum || pingoraChecksum.status !== 'CRITICAL') {
+    failures.push('自审失败时 snapshot 必须保留 CRITICAL checksum 细节。');
+  }
+}
+
+function assertRejectsRelativePaths() {
+  const result = spawnSync(
+    'node',
+    [SNAPSHOT_SCRIPT, '--release-root', 'build/current'],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('状态快照必须拒绝相对 release root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--release-root 必须是绝对路径',
+    '相对 release root 必须给出明确错误。',
+  );
+}
+
+function assertRejectsPathArgsWithControlCharacters() {
+  const fixture = prepareFixture('control-character-path', {
+    gatewayMode: 'nginx',
+    publicBaseUrl: 'http://127.0.0.1',
+    publicHost: '',
+    directCapability: false,
+    pingoraActive: false,
+  });
+  const result = runSnapshot(fixture, [
+    '--release-root',
+    `${fixture.releaseRoot}\n--fake-flag`,
+  ]);
+  if ((result.status ?? 0) === 0) {
+    failures.push('状态快照必须拒绝带换行的路径参数。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--release-root 不能包含换行或 NUL 字符',
+    '路径参数控制字符负例必须给出明确错误。',
+  );
+  assertNotIncludes(
+    readTextFile(fixture.commandsLog, 'fake systemctl 日志'),
+    'systemctl ',
+    '路径参数被拒绝时不应执行 systemctl 子命令。',
+  );
+}
+
+function assertRejectsFilesystemRootReleaseRoot() {
+  const result = spawnSync(
+    'node',
+    [SNAPSHOT_SCRIPT, '--release-root', '/'],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('状态快照必须拒绝文件系统根目录 release root。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--release-root 不能是文件系统根目录',
+    '文件系统根目录 release root 必须给出明确错误。',
+  );
+}
+
+function assertRejectsFilesystemRootEnvFiles() {
+  for (const [flag, expected] of [
+    ['--health-patrol-env-file', '--health-patrol-env-file 不能是文件系统根目录'],
+    ['--pingora-env-file', '--pingora-env-file 不能是文件系统根目录'],
+  ]) {
+    const result = spawnSync('node', [SNAPSHOT_SCRIPT, flag, '/'], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    });
+    if ((result.status ?? 0) === 0) {
+      failures.push(`${flag} 使用文件系统根目录时必须失败。`);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      expected,
+      `${flag} 指向文件系统根目录必须给出明确错误。`,
+    );
+  }
+}
+
+function assertRejectsInvalidTimeout() {
+  const fixture = prepareFixture('invalid-timeout', {
+    gatewayMode: 'nginx',
+    publicBaseUrl: 'http://127.0.0.1',
+    publicHost: '',
+    directCapability: false,
+    pingoraActive: false,
+  });
+  const cliResult = runSnapshot(fixture, ['--timeout-ms', '0']);
+  if ((cliResult.status ?? 0) === 0) {
+    failures.push('状态快照必须拒绝非正数 --timeout-ms。');
+  }
+  assertIncludes(
+    `${cliResult.stdout}\n${cliResult.stderr}`,
+    '--timeout-ms 必须是正整数',
+    '非法 --timeout-ms 必须给出明确错误。',
+  );
+
+  const envResult = runSnapshot(fixture, [], {
+    GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS: 'abc',
+  });
+  if ((envResult.status ?? 0) === 0) {
+    failures.push('状态快照必须拒绝非法 timeout env。');
+  }
+  assertIncludes(
+    `${envResult.stdout}\n${envResult.stderr}`,
+    'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS 必须是正整数',
+    '非法 timeout env 必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidBoolEnv() {
+  const fixture = prepareFixture('invalid-bool-env', {
+    gatewayMode: 'nginx',
+    publicBaseUrl: 'http://127.0.0.1',
+    publicHost: '',
+    directCapability: false,
+    pingoraActive: false,
+  });
+  const cases = [
+    {
+      env: { GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL: 'ture' },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL 必须是布尔值',
+      reason: '状态快照必须拒绝拼写错误的 run health patrol env。',
+    },
+    {
+      env: { GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_REQUIRE_PINGORA_GATEWAY: 'maybe' },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_REQUIRE_PINGORA_GATEWAY 必须是布尔值',
+      reason: '状态快照必须拒绝非法 require pingora gateway env。',
+    },
+    {
+      env: { GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL: 'enabled' },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL 必须是布尔值',
+      reason: '状态快照必须拒绝非法 fail on critical env。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = runSnapshot(fixture, [], testCase.env);
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function prepareFixture(name, options) {
+  const root = path.join(tmpRoot, name);
+  const releaseRoot = path.join(root, 'current');
+  const fakeBin = path.join(root, 'bin');
+  const commandsLog = path.join(root, 'commands.log');
+  const healthEnvFile = path.join(root, 'etc', 'health-patrol.env');
+  const pingoraEnvFile = path.join(root, 'etc', 'pingora-gateway.env');
+
+  mkdirSync(fakeBin, { recursive: true });
+  mkdirSync(path.dirname(healthEnvFile), { recursive: true });
+  prepareReleaseRoot(releaseRoot);
+  writeFileSync(commandsLog, '', 'utf8');
+
+  const healthEnvText = [
+    `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=${options.gatewayMode}`,
+    `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=${options.publicBaseUrl}`,
+    `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=${options.publicHost}`,
+    'GENARRATIVE_HEALTH_PATROL_API_BASE_URL=http://127.0.0.1:8082',
+    'GENARRATIVE_HEALTH_PATROL_SPACETIME_BASE_URL=http://127.0.0.1:3101',
+    `GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN=${options.healthProbeToken || ''}`,
+    '',
+  ].join('\n');
+  writeFileSync(healthEnvFile, healthEnvText, 'utf8');
+  writeFileSync(
+    pingoraEnvFile,
+    pingoraEnvText(options),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(fakeBin, 'systemctl'),
+    fakeSystemctlScript(commandsLog, releaseRoot, pingoraEnvFile, options),
+    'utf8',
+  );
+  chmodExecutable(path.join(fakeBin, 'systemctl'));
+
+  return {
+    root,
+    releaseRoot,
+    fakeBin,
+    commandsLog,
+    healthEnvFile,
+    pingoraEnvFile,
+    originalHealthEnvText: healthEnvText,
+  };
+}
+
+function pingoraEnvText(options) {
+  const lines =
+    options.pingoraEnvMode === 'shadow'
+      ? [
+          'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=',
+          'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=',
+          'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=http',
+        ]
+      : [
+          'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=0.0.0.0:443',
+          'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=0.0.0.0:80',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/etc/letsencrypt/live/example/fullchain.pem',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/etc/letsencrypt/live/example/privkey.pem',
+          'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+        ];
+  return [
+    ...lines,
+    `GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN=${options.pingoraProbeToken || 'fake-token'}`,
+    '',
+  ].join('\n');
+}
+
+function prepareReleaseRoot(releaseRoot) {
+  for (const dir of [
+    'scripts',
+    'scripts/ops',
+    'scripts/deploy',
+    'deploy/systemd',
+    'deploy/nginx',
+    'deploy/env',
+    'deploy/pingora',
+  ]) {
+    mkdirSync(path.join(releaseRoot, dir), { recursive: true });
+  }
+  writeFileSync(
+    path.join(releaseRoot, 'api-server'),
+    '#!/usr/bin/env bash\n',
+    'utf8',
+  );
+  chmodExecutable(path.join(releaseRoot, 'api-server'));
+  writeChecksum(releaseRoot, 'api-server');
+  writeFileSync(
+    path.join(releaseRoot, 'pingora-gateway'),
+    '#!/usr/bin/env bash\n',
+    'utf8',
+  );
+  chmodExecutable(path.join(releaseRoot, 'pingora-gateway'));
+  writeChecksum(releaseRoot, 'pingora-gateway');
+  copyFileSync(
+    SNAPSHOT_SCRIPT,
+    path.join(releaseRoot, 'scripts/ops/pingora-cutover-status-snapshot.mjs'),
+  );
+  copyFileSync(
+    'scripts/check-production-health-patrol-env.mjs',
+    path.join(releaseRoot, 'scripts/check-production-health-patrol-env.mjs'),
+  );
+  writeFileSync(
+    path.join(releaseRoot, 'scripts/ops/production-health-patrol.mjs'),
+    [
+      '#!/usr/bin/env node',
+      'console.log(JSON.stringify({',
+      '  status: "OK",',
+      '  gatewayMode: process.env.GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE || "",',
+      '  hasPingoraProbeToken: Boolean(process.env.GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN || process.env.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN),',
+      '  probeEcho: `${process.env.GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN || ""}:${process.env.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN || ""}`,',
+      '}));',
+      'console.error(`probe stderr ${process.env.GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN || ""}:${process.env.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN || ""}`);',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  for (const file of [
+    'scripts/database-backup-to-oss.mjs',
+    'scripts/ops/pingora-current-release-audit.mjs',
+    'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    'scripts/ops/pingora-cutover-command-evidence.mjs',
+    'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    'scripts/check-pingora-release-readiness.mjs',
+    'scripts/check-pingora-direct-preflight.mjs',
+    'scripts/check-pingora-direct-live.mjs',
+    'scripts/check-pingora-canary-live.mjs',
+    'scripts/check-pingora-canary-access-log-parity.mjs',
+    'scripts/deploy/pingora-direct-enable.sh',
+    'scripts/deploy/pingora-direct-rollback.sh',
+    'scripts/deploy/pingora-realpath-canary-enable.sh',
+    'scripts/deploy/pingora-realpath-canary-disable.sh',
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    'scripts/deploy/pingora-tls-cert-sync.mjs',
+    'deploy/systemd/genarrative-pingora-gateway.service',
+    'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    'deploy/nginx/snippets/genarrative-pingora-canary.conf',
+    'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    'deploy/env/health-patrol.env.example',
+    'deploy/env/pingora-direct-live.env.example',
+    'deploy/env/pingora-canary-live.env.example',
+    'deploy/pingora/pingora-gateway.env.example',
+    'deploy/pingora/nginx-route-parity.matrix.json',
+  ]) {
+    const target = path.join(releaseRoot, file);
+    mkdirSync(path.dirname(target), { recursive: true });
+    if (existsSync(file)) {
+      copyFileSync(file, target);
+    } else {
+      writeFileSync(target, '', 'utf8');
+    }
+  }
+  for (const file of [
+    'scripts/deploy/pingora-direct-enable.sh',
+    'scripts/deploy/pingora-direct-rollback.sh',
+    'scripts/deploy/pingora-realpath-canary-enable.sh',
+    'scripts/deploy/pingora-realpath-canary-disable.sh',
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    'scripts/deploy/pingora-tls-cert-sync.mjs',
+  ]) {
+    chmodExecutable(path.join(releaseRoot, file));
+  }
+  writeReleaseManifest(releaseRoot);
+}
+
+function fakeSystemctlScript(commandsLog, releaseRoot, pingoraEnvFile, options) {
+  const capabilityLines = options.directCapability
+    ? [
+        'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+        'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      ]
+    : [];
+  const inactivePingora = options.pingoraActive ? 'active' : 'inactive';
+  const releaseBinaryPath = path.join(releaseRoot, 'pingora-gateway');
+  const systemdPingoraEnvFile =
+    options.systemdPingoraEnvFile === 'prefix'
+      ? `${pingoraEnvFile}.bak`
+      : options.systemdPingoraEnvFile || pingoraEnvFile;
+  return [
+    '#!/usr/bin/env bash',
+    `printf 'systemctl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+    'if [[ "$1" == "is-active" ]]; then',
+    '  if [[ "$2" == "genarrative-pingora-gateway.service" ]]; then',
+    `    echo ${shellQuote(inactivePingora)}`,
+    `    [[ ${shellQuote(inactivePingora)} == "active" ]] && exit 0 || exit 3`,
+    '  fi',
+    '  echo active',
+    '  exit 0',
+    'fi',
+    'if [[ "$1" == "cat" ]]; then',
+    '  cat <<UNIT',
+    '[Service]',
+    'User=genarrative',
+    `EnvironmentFile=-${systemdPingoraEnvFile}`,
+    ...capabilityLines,
+    'ExecStart=/opt/genarrative/current/pingora-gateway',
+    'UNIT',
+    '  exit 0',
+    'fi',
+    'if [[ "$1" == "show" ]]; then',
+    '  cat <<SHOW',
+    'FragmentPath=/etc/systemd/system/genarrative-pingora-gateway.service',
+    'DropInPaths=/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf',
+    'User=genarrative',
+    `ExecStart={ path=${releaseBinaryPath} ; argv[]=${releaseBinaryPath} ; }`,
+    'SHOW',
+    '  exit 0',
+    'fi',
+    'exit 1',
+    '',
+  ].join('\n');
+}
+
+function runSnapshot(fixture, args, extraEnv = {}) {
+  return spawnSync(
+    'node',
+    [
+      SNAPSHOT_SCRIPT,
+      '--release-root',
+      fixture.releaseRoot,
+      '--health-patrol-env-file',
+      fixture.healthEnvFile,
+      '--pingora-env-file',
+      fixture.pingoraEnvFile,
+      ...args,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        ...extraEnv,
+        PATH: `${fixture.fakeBin}:${process.env.PATH || ''}`,
+      },
+    },
+  );
+}
+
+function chmodExecutable(filePath) {
+  chmodSync(filePath, 0o755);
+}
+
+function writeChecksum(directory, fileName) {
+  const content = readFileSync(path.join(directory, fileName));
+  const checksum = createHash('sha256').update(content).digest('hex');
+  writeFileSync(
+    path.join(directory, `${fileName}.sha256`),
+    `${checksum}  ${fileName}\n`,
+    'utf8',
+  );
+}
+
+function writeReleaseManifest(releaseRoot) {
+  writeFileSync(
+    path.join(releaseRoot, 'release-manifest.api-server.json'),
+    `${JSON.stringify(
+      {
+        version: 'check-cutover-snapshot',
+        component_type: 'api-server',
+        artifacts: [
+          {
+            component: 'api-server',
+            path: 'api-server',
+            checksum_path: 'api-server.sha256',
+          },
+          {
+            component: 'pingora-gateway',
+            path: 'pingora-gateway',
+            checksum_path: 'pingora-gateway.sha256',
+          },
+        ],
+      },
+      null,
+      2,
+    )}\n`,
+    'utf8',
+  );
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function readTextFile(filePath, label) {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch (error) {
+    failures.push(`无法读取 ${label}: ${error.message}`);
+    return '';
+  }
+}
+
+function assertFileUnchanged(filePath, expected, reason) {
+  const actual = readTextFile(filePath, filePath);
+  if (actual !== expected) {
+    failures.push(reason);
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  if ((result.status ?? 0) !== expected) {
+    failures.push(
+      `${reason} 实际退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 实际 ${actual}，预期 ${expected}。`);
+  }
+}
+
+function assertIncludes(value, expected, reason) {
+  const haystack = Array.isArray(value) ? value.join('\n') : String(value);
+  if (!haystack.includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
+
+function assertNotIncludes(value, unexpected, reason) {
+  const haystack = Array.isArray(value) ? value.join('\n') : String(value);
+  if (haystack.includes(unexpected)) {
+    failures.push(`${reason} 不应包含: ${unexpected}`);
+  }
+}
diff --git a/scripts/check-pingora-direct-enable.mjs b/scripts/check-pingora-direct-enable.mjs
new file mode 100644
index 000000000..dcfe02110
--- /dev/null
+++ b/scripts/check-pingora-direct-enable.mjs
@@ -0,0 +1,2382 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import path from 'node:path';
+
+const ENABLE_SCRIPT = 'scripts/deploy/pingora-direct-enable.sh';
+const PREFLIGHT_SCRIPT = 'scripts/check-pingora-direct-preflight.mjs';
+const failures = [];
+const [DIRECT_TLS_PORT, DIRECT_HTTP_REDIRECT_PORT] = allocateLoopbackPorts(2);
+const DIRECT_TLS_LISTEN = `127.0.0.1:${DIRECT_TLS_PORT}`;
+const DIRECT_HTTP_REDIRECT_LISTEN = `127.0.0.1:${DIRECT_HTTP_REDIRECT_PORT}`;
+
+const tmpRoot = mkdtempSync(path.join(tmpdir(), 'genarrative-pingora-enable-'));
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-direct-enable] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-direct-enable] OK');
+
+function main() {
+  assertScriptShape();
+  assertDirectPreflightChecksServiceEnvironmentFile();
+  assertDirectPreflightRejectsPublicForwardedForTrust();
+  assertDryRunDoesNotInstallDropin();
+  assertDryRunRunsPreflightWhenRequested();
+  assertReleaseLayoutDryRunUsesBundledDirectChecks();
+  assertMissingTemplateDryRunWarns();
+  assertRelativePathsRejected();
+  assertFilesystemRootPathsRejected();
+  assertApplyRequiresPreflightEnvFile();
+  assertApplyRequiresCertReadablePreflight();
+  assertApplyRequiresServiceEnvFilePreflight();
+  assertApplyRequiresServiceUserCertReadablePreflight();
+  assertApplyRequiresServiceBinaryExecutablePreflight();
+  assertApplyRequiresPortsFreePreflight();
+  assertApplyRequiresDirectLiveArgs();
+  assertRejectsControlCharacterInputsBeforeApply();
+  assertApplyFailsWhenCurrentReleaseAuditFailsBeforeInstall();
+  assertApplyFailsWhenPreflightScriptMissingBeforeInstall();
+  assertApplyFailsWhenDirectLiveScriptMissingBeforeInstall();
+  assertApplyRejectsSymlinkDropinDirectoryBeforeInstall();
+  assertApplyRejectsSymlinkDropinFileBeforeInstall();
+  assertApplyFailsWhenSystemdEnvFileDiffers();
+  assertApplyFailsWhenSystemdEnvFileOnlySharesPrefix();
+  assertApplyFailsWhenSystemdExecStartDiffers();
+  assertApplyFailsWhenDirectLiveSmokeFails();
+  assertApplyFailsWhenDirectLiveAccessLogJsonMissing();
+}
+
+function assertDirectPreflightChecksServiceEnvironmentFile() {
+  const preflightRoot = path.join(tmpRoot, 'preflight-env-file');
+  const envPath = path.join(preflightRoot, 'pingora-gateway.env');
+  const servicePath = path.join(preflightRoot, 'genarrative-pingora-gateway.service');
+  const mismatchServicePath = path.join(
+    preflightRoot,
+    'genarrative-pingora-gateway-mismatch.service',
+  );
+  const dropinPath = path.join(
+    preflightRoot,
+    'genarrative-pingora-gateway-direct-entry.conf',
+  );
+  const envExamplePath = path.join(preflightRoot, 'pingora-gateway.env.example');
+  const systemctlBinary = path.join(preflightRoot, 'systemctl');
+
+  mkdirSync(preflightRoot, { recursive: true });
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    servicePath,
+    [
+      '[Unit]',
+      'Description=Pingora 影子网关只监听本机高端口',
+      '[Service]',
+      `EnvironmentFile=-${envPath}`,
+      'ExecStart=/opt/genarrative/current/pingora-gateway',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    mismatchServicePath,
+    [
+      '[Unit]',
+      'Description=Pingora 影子网关只监听本机高端口',
+      '[Service]',
+      'EnvironmentFile=/etc/genarrative/other-pingora.env',
+      'ExecStart=/opt/genarrative/current/pingora-gateway',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    dropinPath,
+    [
+      '# 人工复制到 /etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf 后生效',
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    envExamplePath,
+    '# CAP_NET_BIND_SERVICE 只由 direct-entry drop-in 授予\n',
+    'utf8',
+  );
+
+  const baseArgs = [
+    '--env-file',
+    envPath,
+    '--check-service-env-file',
+    '--service-unit',
+    servicePath,
+    '--dropin-template',
+    dropinPath,
+    '--env-example',
+    envExamplePath,
+  ];
+  const okResult = runPreflight(baseArgs);
+  assertStatus(
+    okResult,
+    0,
+    'direct preflight 应接受 optional EnvironmentFile=-<env> 指向本次 env。',
+  );
+
+  const serviceMismatchResult = runPreflight([
+    '--env-file',
+    envPath,
+    '--check-service-env-file',
+    '--service-unit',
+    mismatchServicePath,
+    '--dropin-template',
+    dropinPath,
+    '--env-example',
+    envExamplePath,
+  ]);
+  if (serviceMismatchResult.status === 0) {
+    failures.push('service 模板 EnvironmentFile 漂移时 direct preflight 必须失败。');
+  }
+  assertIncludes(
+    serviceMismatchResult.stderr,
+    `${mismatchServicePath} EnvironmentFile 未包含本次 --env-file`,
+    'service 模板 EnvironmentFile 漂移时必须给出明确错误。',
+  );
+
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  echo "EnvironmentFile=/etc/genarrative/other-pingora.env"',
+      '  echo "AmbientCapabilities=CAP_NET_BIND_SERVICE"',
+      '  echo "CapabilityBoundingSet=CAP_NET_BIND_SERVICE"',
+      '  exit 0',
+      'fi',
+      'exit 1',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(systemctlBinary);
+
+  const systemdMismatchResult = runPreflight([...baseArgs, '--systemd-cat'], {
+    PATH: `${preflightRoot}:${process.env.PATH || ''}`,
+  });
+  if (systemdMismatchResult.status === 0) {
+    failures.push('systemctl cat EnvironmentFile 漂移时 direct preflight 必须失败。');
+  }
+  assertIncludes(
+    systemdMismatchResult.stderr,
+    'systemctl cat genarrative-pingora-gateway.service EnvironmentFile 未包含本次 --env-file',
+    'systemd 最终配置 EnvironmentFile 漂移时必须给出明确错误。',
+  );
+}
+
+function assertDirectPreflightRejectsPublicForwardedForTrust() {
+  const preflightRoot = path.join(tmpRoot, 'preflight-forwarded-for');
+  const envPath = path.join(preflightRoot, 'pingora-gateway.env');
+  const servicePath = path.join(preflightRoot, 'genarrative-pingora-gateway.service');
+  const dropinPath = path.join(
+    preflightRoot,
+    'genarrative-pingora-gateway-direct-entry.conf',
+  );
+  const envExamplePath = path.join(preflightRoot, 'pingora-gateway.env.example');
+
+  mkdirSync(preflightRoot, { recursive: true });
+  writeFileSync(
+    servicePath,
+    [
+      '[Unit]',
+      'Description=Pingora 影子网关只监听本机高端口',
+      '[Service]',
+      `EnvironmentFile=${envPath}`,
+      'ExecStart=/opt/genarrative/current/pingora-gateway',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    dropinPath,
+    [
+      '# 人工复制到 /etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf 后生效',
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    envExamplePath,
+    '# CAP_NET_BIND_SERVICE 只由 direct-entry drop-in 授予\n',
+    'utf8',
+  );
+
+  const baseArgs = [
+    '--env-file',
+    envPath,
+    '--require-live-env',
+    '--service-unit',
+    servicePath,
+    '--dropin-template',
+    dropinPath,
+    '--env-example',
+    envExamplePath,
+  ];
+
+  writeFileSync(
+    envPath,
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=0.0.0.0:443',
+      'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=0.0.0.0:80',
+      'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/tmp/cert.pem',
+      'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/tmp/key.pem',
+      'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+      'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true',
+      'GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  const publicResult = runPreflight(baseArgs);
+  if (publicResult.status === 0) {
+    failures.push('公网直连开启 X-Forwarded-For 信任时 direct preflight 必须失败。');
+  }
+  assertIncludes(
+    publicResult.stderr,
+    '公网直连 Pingora 时 GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR 必须保持 false',
+    '公网直连误信任 X-Forwarded-For 时必须给出明确错误。',
+  );
+
+  writeFileSync(
+    envPath,
+    [
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
+      'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/tmp/cert.pem',
+      'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/tmp/key.pem',
+      'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+      'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true',
+      'GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  const loopbackResult = runPreflight(baseArgs);
+  assertStatus(
+    loopbackResult,
+    0,
+    'loopback 入口在显式确认前置代理清洗 X-Forwarded-For 后应允许 preflight 通过。',
+  );
+
+  writeFileSync(
+    envPath,
+    [
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
+      'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/tmp/cert.pem',
+      'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/tmp/key.pem',
+      'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+      'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true',
+      'GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=false',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  const missingConfirmationResult = runPreflight(baseArgs);
+  if (missingConfirmationResult.status === 0) {
+    failures.push('开启 X-Forwarded-For 信任但缺少确认开关时 direct preflight 必须失败。');
+  }
+  assertIncludes(
+    missingConfirmationResult.stderr,
+    'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true 时必须同时设置 GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true',
+    'X-Forwarded-For 信任缺少确认开关时必须给出明确错误。',
+  );
+}
+
+function assertReleaseLayoutDryRunUsesBundledDirectChecks() {
+  const currentUser = currentUsername();
+  const releaseRoot = path.join(tmpRoot, 'current-release');
+  const releaseScript = path.join(
+    releaseRoot,
+    'scripts',
+    'deploy',
+    'pingora-direct-enable.sh',
+  );
+  const templatePath = path.join(
+    releaseRoot,
+    'deploy',
+    'systemd',
+    'genarrative-pingora-gateway-direct-entry.conf',
+  );
+  const dropinPath = path.join(
+    tmpRoot,
+    'release-layout-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(tmpRoot, 'release-layout-pingora-gateway.env');
+  const certPath = path.join(tmpRoot, 'release-layout-cert.pem');
+  const keyPath = path.join(tmpRoot, 'release-layout-key.pem');
+  const pingoraGatewayPath = path.join(releaseRoot, 'pingora-gateway');
+
+  mkdirSync(path.join(releaseRoot, 'scripts', 'deploy'), { recursive: true });
+  mkdirSync(path.join(releaseRoot, 'deploy', 'systemd'), { recursive: true });
+  mkdirSync(path.join(releaseRoot, 'deploy', 'pingora'), { recursive: true });
+  writeFileSync(releaseScript, readFileSync(ENABLE_SCRIPT, 'utf8'), 'utf8');
+  writeFileSync(
+    path.join(releaseRoot, 'scripts', 'check-pingora-direct-preflight.mjs'),
+    readFileSync('scripts/check-pingora-direct-preflight.mjs', 'utf8'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(releaseRoot, 'scripts', 'check-pingora-direct-live.mjs'),
+    readFileSync('scripts/check-pingora-direct-live.mjs', 'utf8'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(
+      releaseRoot,
+      'deploy',
+      'systemd',
+      'genarrative-pingora-gateway.service',
+    ),
+    `[Unit]\nDescription=Pingora 影子网关只监听本机高端口\n[Service]\nUser=${currentUser}\nEnvironmentFile=${envPath}\nExecStart=${pingoraGatewayPath}\n`,
+    'utf8',
+  );
+  writeFileSync(
+    templatePath,
+    [
+      '# 人工复制到 /etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf 后生效',
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(releaseRoot, 'deploy', 'pingora', 'pingora-gateway.env.example'),
+    [
+      '# CAP_NET_BIND_SERVICE 只由 direct-entry drop-in 授予',
+      'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=0.0.0.0:443',
+      'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=0.0.0.0:80',
+      'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(certPath, 'fake-cert\n', 'utf8');
+  writeFileSync(keyPath, 'fake-key\n', 'utf8');
+  writeFileSync(
+    envPath,
+    [
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
+      'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=${certPath}`,
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=${keyPath}`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    pingoraGatewayPath,
+    '#!/usr/bin/env bash\nprintf "fake pingora gateway\\n"\n',
+    'utf8',
+  );
+  chmodExecutable(releaseScript);
+  chmodExecutable(pingoraGatewayPath);
+
+  const result = spawnSync(
+    'bash',
+    [
+      releaseScript,
+      '--dropin-path',
+      dropinPath,
+      '--preflight-env-file',
+      envPath,
+      '--preflight-check-cert-readable',
+      '--preflight-check-service-env-file',
+      '--preflight-check-service-user-cert-readable',
+      '--preflight-check-service-binary-executable',
+      '--preflight-check-ports-free',
+      '--no-status',
+    ],
+    {
+      cwd: tmpRoot,
+      encoding: 'utf8',
+      env: process.env,
+    },
+  );
+
+  assertStatus(
+    result,
+    0,
+    'release current 目录中的 enable dry-run 应能使用随包携带的 direct preflight。',
+  );
+  assertIncludes(
+    result.stdout,
+    `${releaseRoot}/scripts/check-pingora-direct-preflight.mjs`,
+    'release current 目录中的 enable dry-run 必须调用随包携带的 direct preflight。',
+  );
+  assertIncludes(
+    result.stdout,
+    `template=${templatePath}`,
+    'release current 目录中的 enable dry-run 必须默认读取随包携带的 direct-entry 模板。',
+  );
+  assertIncludes(
+    result.stdout,
+    `+ install -m 0644 ${templatePath} ${dropinPath}`,
+    'release current 目录中的 enable dry-run 必须展示安装随包 direct-entry 模板。',
+  );
+  assertIncludes(
+    result.stdout,
+    '[pingora-direct-preflight] OK',
+    'release current 目录中的 direct preflight 必须带服务用户证书可读和 service 二进制可执行检查并真实通过。',
+  );
+  if (existsSync(dropinPath)) {
+    failures.push('release current 目录 dry-run 不应安装临时 drop-in 文件。');
+  }
+}
+
+function currentUsername() {
+  if (process.env.USER || process.env.LOGNAME) {
+    return process.env.USER || process.env.LOGNAME;
+  }
+  try {
+    return userInfo().username;
+  } catch {
+    return 'root';
+  }
+}
+
+function assertScriptShape() {
+  const content = readFileSync(ENABLE_SCRIPT, 'utf8');
+  assertIncludes(content, 'APPLY="false"', '启用脚本必须默认 dry-run。');
+  assertIncludes(
+    content,
+    '--apply',
+    '启用脚本必须显式要求 --apply 才修改系统。',
+  );
+  assertIncludes(
+    content,
+    'systemctl daemon-reload',
+    '安装 drop-in 后必须 reload systemd。',
+  );
+  assertIncludes(
+    content,
+    'restart "${SERVICE_NAME}"',
+    '启用脚本必须重启 Pingora 服务。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_DIRECT_TEMPLATE_PATH',
+    '启用脚本必须支持覆盖 direct-entry 模板路径。',
+  );
+  assertIncludes(
+    content,
+    'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    '启用脚本默认模板必须来自 current release 随包 deploy/systemd。',
+  );
+  assertIncludes(
+    content,
+    'direct-entry.conf',
+    '启用脚本必须默认指向 direct-entry drop-in。',
+  );
+  assertIncludes(
+    content,
+    '该脚本不写入 TLS env',
+    '启用脚本必须声明不改 TLS/env/证书边界。',
+  );
+  assertIncludes(
+    content,
+    '--preflight-env-file',
+    '启用脚本必须支持直连 env 预检参数。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --preflight-env-file',
+    '启用脚本 apply 时必须强制预检 env 文件。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --preflight-check-cert-readable',
+    '启用脚本 apply 时必须强制证书可读预检。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --preflight-check-service-env-file',
+    '启用脚本 apply 时必须强制 service EnvironmentFile 一致性预检。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --preflight-check-service-user-cert-readable',
+    '启用脚本 apply 时必须强制 systemd 服务用户证书可读预检。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --preflight-check-service-binary-executable',
+    '启用脚本 apply 时必须强制 Pingora service 二进制可执行预检。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --preflight-check-ports-free',
+    '启用脚本 apply 时必须强制端口释放预检。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --direct-https-base-url',
+    '启用脚本 apply 时必须强制 direct HTTPS live smoke 参数。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --direct-http-base-url',
+    '启用脚本 apply 时必须强制 direct HTTP live smoke 参数。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --direct-host',
+    '启用脚本 apply 时必须强制正式域名 Host/SNI 参数。',
+  );
+  assertIncludes(
+    content,
+    '--direct-redirect-base-url',
+    '启用脚本必须支持 direct live redirect base URL 覆盖，用于高端口 rehearsal。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --direct-redirect-host',
+    '启用脚本 apply 时必须强制 redirect Location host 参数。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --direct-pingora-access-log',
+    '启用脚本 apply 时必须强制 direct access log 落盘校验参数。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --direct-spacetime-database',
+    '启用脚本 apply 时必须强制 WSS subscribe 数据库名参数。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_DIRECT_CURRENT_RELEASE_AUDIT_SCRIPT',
+    '启用脚本必须支持固定 current release 自审脚本路径。',
+  );
+  assertIncludes(
+    content,
+    '--current-release-root',
+    '启用脚本必须支持固定 current release 根目录。',
+  );
+  assertIncludes(
+    content,
+    '--require-pingora-gateway',
+    '启用脚本 apply 前 current release 自审必须要求 Pingora 网关产物存在。',
+  );
+  assertIncludes(
+    content,
+    '--systemd-show',
+    '启用脚本 apply 前 current release 自审必须核验 systemd ExecStart。',
+  );
+  assertIncludes(
+    content,
+    'systemctl cat ${SERVICE_NAME}',
+    '启用脚本必须在 apply 后核验 systemd 最终配置。',
+  );
+  assertIncludes(
+    content,
+    'systemctl is-active ${SERVICE_NAME}',
+    '启用脚本必须在 apply 后核验 Pingora service active。',
+  );
+  assertIncludes(
+    content,
+    'systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager',
+    '启用脚本必须在 apply 后核验 systemd ExecStart 指向 current release。',
+  );
+  assertIncludes(
+    content,
+    '主 service 模板中的',
+    '启用脚本 ExecStart 核验必须以随包主 service 模板为真相源。',
+  );
+  assertIncludes(
+    content,
+    'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    '启用脚本必须核验 AmbientCapabilities 已生效。',
+  );
+  assertIncludes(
+    content,
+    'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+    '启用脚本必须核验 CapabilityBoundingSet 已生效。',
+  );
+  assertIncludes(
+    content,
+    'systemctl cat 未显示 EnvironmentFile=',
+    '启用脚本必须在 apply 后核验 systemd 最终配置读取的 env 和 preflight env 一致。',
+  );
+  assertIncludes(
+    content,
+    '--require-wss-upgrade',
+    '启用脚本必须在 apply 后强制 direct live WSS 101。',
+  );
+  assertIncludes(
+    content,
+    '--json',
+    '启用脚本必须用 JSON 模式运行 direct live smoke，便于校验结构化接流证据。',
+  );
+  assertIncludes(
+    content,
+    'direct live JSON 缺少 direct-access-log 结构化结果',
+    '启用脚本必须拒绝缺少 direct-access-log 结构化结果的 direct live 输出。',
+  );
+  assertIncludes(
+    content,
+    'direct-access-log evidence checked=',
+    '启用脚本必须在 direct-access-log 结构化证据通过后输出确认摘要。',
+  );
+  assertIncludes(
+    content,
+    'print_redacted_command node "${direct_live_args[@]}"',
+    '启用脚本展示 direct live smoke 命令时必须隐藏 probe token。',
+  );
+  assertIncludes(
+    content,
+    'direct_live_args+=(--redirect-base-url "${DIRECT_REDIRECT_BASE_URL}")',
+    '启用脚本必须把 direct redirect base URL 透传给 direct live smoke。',
+  );
+  assertIncludes(
+    content,
+    'drop-in 目录不能是符号链接',
+    '启用脚本 apply 前必须拒绝符号链接 drop-in 目录。',
+  );
+  assertIncludes(
+    content,
+    'drop-in 目标不能是符号链接',
+    '启用脚本 apply 前必须拒绝符号链接 drop-in 目标。',
+  );
+  assertIncludes(
+    content,
+    'reject_control_characters',
+    '启用脚本必须统一拒绝换行或 NUL 参数。',
+  );
+  assertIncludes(
+    content,
+    '不能包含换行或 NUL 字符',
+    '启用脚本拒绝控制字符时必须给出明确错误。',
+  );
+  assertIncludes(
+    content,
+    'reject_filesystem_root_path',
+    '启用脚本必须统一拒绝文件系统根目录路径参数。',
+  );
+  assertIncludes(
+    content,
+    '不能是文件系统根目录',
+    '启用脚本拒绝文件系统根目录路径时必须给出明确错误。',
+  );
+}
+
+function assertDryRunDoesNotInstallDropin() {
+  const templatePath = path.join(tmpRoot, 'template.conf');
+  const dropinPath = path.join(tmpRoot, 'service.d', 'direct-entry.conf');
+  writeFileSync(
+    templatePath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+
+  const result = runEnable([
+    '--template-path',
+    templatePath,
+    '--dropin-path',
+    dropinPath,
+    '--service',
+    'genarrative-pingora-gateway.service',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-probe-token',
+    'direct-secret-token',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--no-status',
+  ]);
+
+  assertStatus(result, 0, 'dry-run 应成功退出。');
+  assertIncludes(
+    result.stdout,
+    'apply=false',
+    'dry-run 输出必须明确 apply=false。',
+  );
+  assertIncludes(
+    result.stdout,
+    `+ install -d -m 0755 ${path.dirname(dropinPath)}`,
+    'dry-run 必须展示创建 drop-in 目录。',
+  );
+  assertIncludes(
+    result.stdout,
+    `+ install -m 0644 ${templatePath} ${dropinPath}`,
+    'dry-run 必须展示安装 drop-in。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl daemon-reload',
+    'dry-run 必须展示 daemon-reload。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl restart genarrative-pingora-gateway.service',
+    'dry-run 必须展示重启 Pingora。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl cat genarrative-pingora-gateway.service',
+    'dry-run 必须展示启用后 systemd drop-in 生效核验。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl is-active genarrative-pingora-gateway.service',
+    'dry-run 必须展示启用后 service active 核验。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager',
+    'dry-run 必须展示启用后 ExecStart 指向核验。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ node ',
+    'dry-run 必须展示 current release 自审和启用后 direct live smoke。',
+  );
+  assertIncludes(
+    result.stdout,
+    'pingora-current-release-audit.mjs',
+    'dry-run 必须展示 apply 前 current release 自审。',
+  );
+  assertIncludes(
+    result.stdout,
+    '--require-pingora-gateway --systemd-show',
+    'dry-run current release 自审必须要求 Pingora 产物和 systemd ExecStart。',
+  );
+  assertIncludes(
+    result.stdout,
+    '--require-wss-upgrade',
+    'dry-run 必须展示 direct live smoke 强制 WSS 101。',
+  );
+  assertIncludes(
+    result.stdout,
+    '--json',
+    'dry-run 必须展示 direct live smoke 会输出 JSON 结构化证据。',
+  );
+  assertIncludes(
+    result.stdout,
+    '--pingora-access-log',
+    'dry-run 必须展示 direct live smoke 会校验 Pingora access log 落盘。',
+  );
+  assertIncludes(
+    result.stdout,
+    '--probe-token <redacted>',
+    'dry-run direct live smoke 命令必须隐藏 probe token。',
+  );
+  if (result.stdout.includes('direct-secret-token')) {
+    failures.push('dry-run direct live smoke 命令不能泄露 probe token 原文。');
+  }
+
+  if (existsSync(dropinPath)) {
+    failures.push('dry-run 不应安装临时 drop-in 文件。');
+  }
+}
+
+function assertDryRunRunsPreflightWhenRequested() {
+  const templatePath = path.join(tmpRoot, 'preflight-template.conf');
+  const dropinPath = path.join(
+    tmpRoot,
+    'preflight-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(tmpRoot, 'pingora-gateway.env');
+  const certPath = path.join(tmpRoot, 'cert.pem');
+  const keyPath = path.join(tmpRoot, 'key.pem');
+  writeFileSync(
+    templatePath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(certPath, 'fake-cert\n', 'utf8');
+  writeFileSync(keyPath, 'fake-key\n', 'utf8');
+  writeFileSync(
+    envPath,
+    [
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
+      'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=${certPath}`,
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=${keyPath}`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+
+  const result = runEnable([
+    '--template-path',
+    templatePath,
+    '--dropin-path',
+    dropinPath,
+    '--preflight-env-file',
+    envPath,
+    '--preflight-check-cert-readable',
+    '--preflight-check-ports-free',
+    '--no-status',
+  ]);
+
+  assertStatus(result, 0, '带 preflight 的 dry-run 应成功退出。');
+  assertIncludes(
+    result.stdout,
+    '+ node ',
+    'dry-run 必须展示并执行 direct preflight。',
+  );
+  assertIncludes(
+    result.stdout,
+    'check-pingora-direct-preflight.mjs',
+    'dry-run preflight 命令必须调用 direct preflight 脚本。',
+  );
+  assertIncludes(
+    result.stdout,
+    `--env-file ${envPath} --require-live-env --check-cert-readable --check-ports-free`,
+    'dry-run preflight 命令必须带 env、证书和端口释放检查参数。',
+  );
+  assertIncludes(
+    result.stdout,
+    '[pingora-direct-preflight] OK',
+    'dry-run preflight 必须真实通过。',
+  );
+  assertIncludes(
+    result.stdout,
+    '--https-base-url <direct-https-base-url>',
+    '带 preflight 的 dry-run 仍必须提示 apply 后会执行 direct live smoke。',
+  );
+  if (existsSync(dropinPath)) {
+    failures.push('带 preflight 的 dry-run 不应安装临时 drop-in 文件。');
+  }
+}
+
+function assertMissingTemplateDryRunWarns() {
+  const templatePath = path.join(tmpRoot, 'missing-template.conf');
+  const dropinPath = path.join(
+    tmpRoot,
+    'missing-service.d',
+    'direct-entry.conf',
+  );
+  const result = runEnable([
+    '--template-path',
+    templatePath,
+    '--dropin-path',
+    dropinPath,
+    '--no-status',
+  ]);
+
+  assertStatus(result, 0, '模板不存在时 dry-run 应只提示不失败。');
+  assertIncludes(
+    result.stderr,
+    'dry-run 提示：当前模板不存在',
+    '模板不存在的 dry-run 必须提示 --apply 会失败。',
+  );
+}
+
+function assertRelativePathsRejected() {
+  const templateResult = runEnable([
+    '--template-path',
+    'relative/template.conf',
+    '--dropin-path',
+    path.join(tmpRoot, 'service.d', 'direct-entry.conf'),
+    '--no-status',
+  ]);
+  if (templateResult.status === 0) {
+    failures.push('相对路径 template 必须被拒绝。');
+  }
+  assertIncludes(
+    templateResult.stderr,
+    '--template-path 必须是绝对路径',
+    '相对 template 路径负例必须说明需要绝对路径。',
+  );
+
+  const dropinResult = runEnable([
+    '--template-path',
+    path.join(tmpRoot, 'template.conf'),
+    '--dropin-path',
+    'relative/direct-entry.conf',
+    '--no-status',
+  ]);
+  if (dropinResult.status === 0) {
+    failures.push('相对路径 drop-in 必须被拒绝。');
+  }
+  assertIncludes(
+    dropinResult.stderr,
+    '--dropin-path 必须是绝对路径',
+    '相对 drop-in 路径负例必须说明需要绝对路径。',
+  );
+
+  const preflightResult = runEnable([
+    '--template-path',
+    path.join(tmpRoot, 'template.conf'),
+    '--dropin-path',
+    path.join(tmpRoot, 'service.d', 'direct-entry.conf'),
+    '--preflight-env-file',
+    'relative/pingora-gateway.env',
+    '--no-status',
+  ]);
+  if (preflightResult.status === 0) {
+    failures.push('相对路径 preflight env 必须被拒绝。');
+  }
+  assertIncludes(
+    preflightResult.stderr,
+    '--preflight-env-file 必须是绝对路径',
+    '相对 preflight env 路径负例必须说明需要绝对路径。',
+  );
+
+  const auditScriptResult = runEnable([
+    '--template-path',
+    path.join(tmpRoot, 'template.conf'),
+    '--dropin-path',
+    path.join(tmpRoot, 'service.d', 'direct-entry.conf'),
+    '--current-release-audit-script',
+    'relative/pingora-current-release-audit.mjs',
+    '--no-status',
+  ]);
+  if (auditScriptResult.status === 0) {
+    failures.push('相对路径 current release 自审脚本必须被拒绝。');
+  }
+  assertIncludes(
+    auditScriptResult.stderr,
+    '--current-release-audit-script 必须是绝对路径',
+    '相对 current release 自审脚本路径负例必须说明需要绝对路径。',
+  );
+
+  const preflightScriptResult = runEnable([
+    '--template-path',
+    path.join(tmpRoot, 'template.conf'),
+    '--dropin-path',
+    path.join(tmpRoot, 'service.d', 'direct-entry.conf'),
+    '--preflight-script',
+    'relative/check-pingora-direct-preflight.mjs',
+    '--no-status',
+  ]);
+  if (preflightScriptResult.status === 0) {
+    failures.push('相对路径 direct preflight 脚本必须被拒绝。');
+  }
+  assertIncludes(
+    preflightScriptResult.stderr,
+    '--preflight-script 必须是绝对路径',
+    '相对 direct preflight 脚本路径负例必须说明需要绝对路径。',
+  );
+
+  const auditRootResult = runEnable([
+    '--template-path',
+    path.join(tmpRoot, 'template.conf'),
+    '--dropin-path',
+    path.join(tmpRoot, 'service.d', 'direct-entry.conf'),
+    '--current-release-root',
+    'relative/current',
+    '--no-status',
+  ]);
+  if (auditRootResult.status === 0) {
+    failures.push('相对路径 current release 根目录必须被拒绝。');
+  }
+  assertIncludes(
+    auditRootResult.stderr,
+    '--current-release-root 必须是绝对路径',
+    '相对 current release 根目录负例必须说明需要绝对路径。',
+  );
+
+  const directLiveScriptResult = runEnable([
+    '--template-path',
+    path.join(tmpRoot, 'template.conf'),
+    '--dropin-path',
+    path.join(tmpRoot, 'service.d', 'direct-entry.conf'),
+    '--direct-live-script',
+    'relative/check-pingora-direct-live.mjs',
+    '--no-status',
+  ]);
+  if (directLiveScriptResult.status === 0) {
+    failures.push('相对路径 direct live smoke 脚本必须被拒绝。');
+  }
+  assertIncludes(
+    directLiveScriptResult.stderr,
+    '--direct-live-script 必须是绝对路径',
+    '相对 direct live smoke 脚本路径负例必须说明需要绝对路径。',
+  );
+}
+
+function assertFilesystemRootPathsRejected() {
+  const rootDropinResult = runEnable([
+    '--template-path',
+    path.join(tmpRoot, 'template.conf'),
+    '--dropin-path',
+    '/',
+    '--no-status',
+  ]);
+  if (rootDropinResult.status === 0) {
+    failures.push('文件系统根目录 --dropin-path 必须被拒绝。');
+  }
+  assertIncludes(
+    rootDropinResult.stderr,
+    '--dropin-path 不能是文件系统根目录',
+    '文件系统根目录 drop-in 路径负例必须给出明确错误。',
+  );
+
+  const rootReleaseResult = runEnable([
+    '--template-path',
+    path.join(tmpRoot, 'template.conf'),
+    '--dropin-path',
+    path.join(tmpRoot, 'service.d', 'direct-entry.conf'),
+    '--current-release-root',
+    '/',
+    '--no-status',
+  ]);
+  if (rootReleaseResult.status === 0) {
+    failures.push('文件系统根目录 --current-release-root 必须被拒绝。');
+  }
+  assertIncludes(
+    rootReleaseResult.stderr,
+    '--current-release-root 不能是文件系统根目录',
+    '文件系统根目录 current release 根目录负例必须给出明确错误。',
+  );
+}
+
+function assertApplyRequiresPreflightEnvFile() {
+  const result = runEnable(['--apply', '--no-status']);
+
+  if (result.status === 0) {
+    failures.push('--apply 缺少 --preflight-env-file 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--apply 必须同时提供 --preflight-env-file',
+    'apply 负例必须说明不能跳过 preflight env。',
+  );
+}
+
+function assertApplyRequiresCertReadablePreflight() {
+  const result = runEnable([
+    '--apply',
+    '--preflight-env-file',
+    path.join(tmpRoot, 'pingora-gateway.env'),
+    '--preflight-check-service-env-file',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-ports-free',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('--apply 缺少 --preflight-check-cert-readable 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--apply 必须同时提供 --preflight-check-cert-readable',
+    'apply 负例必须说明不能跳过证书可读 preflight。',
+  );
+}
+
+function assertApplyRequiresServiceEnvFilePreflight() {
+  const result = runEnable([
+    '--apply',
+    '--preflight-env-file',
+    path.join(tmpRoot, 'pingora-gateway.env'),
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-ports-free',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push(
+      '--apply 缺少 --preflight-check-service-env-file 必须被拒绝。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '--apply 必须同时提供 --preflight-check-service-env-file',
+    'apply 负例必须说明不能跳过 service EnvironmentFile 一致性 preflight。',
+  );
+}
+
+function assertApplyRequiresServiceUserCertReadablePreflight() {
+  const result = runEnable([
+    '--apply',
+    '--preflight-env-file',
+    path.join(tmpRoot, 'pingora-gateway.env'),
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-env-file',
+    '--preflight-check-ports-free',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push(
+      '--apply 缺少 --preflight-check-service-user-cert-readable 必须被拒绝。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '--apply 必须同时提供 --preflight-check-service-user-cert-readable',
+    'apply 负例必须说明不能跳过 systemd 服务用户证书可读 preflight。',
+  );
+}
+
+function assertApplyRequiresServiceBinaryExecutablePreflight() {
+  const result = runEnable([
+    '--apply',
+    '--preflight-env-file',
+    path.join(tmpRoot, 'pingora-gateway.env'),
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-env-file',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-ports-free',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push(
+      '--apply 缺少 --preflight-check-service-binary-executable 必须被拒绝。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '--apply 必须同时提供 --preflight-check-service-binary-executable',
+    'apply 负例必须说明不能跳过 service 二进制可执行 preflight。',
+  );
+}
+
+function assertApplyRequiresPortsFreePreflight() {
+  const result = runEnable([
+    '--apply',
+    '--preflight-env-file',
+    path.join(tmpRoot, 'pingora-gateway.env'),
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-env-file',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-service-binary-executable',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('--apply 缺少 --preflight-check-ports-free 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--apply 必须同时提供 --preflight-check-ports-free',
+    'apply 负例必须说明不能跳过端口释放 preflight。',
+  );
+}
+
+function assertApplyRequiresDirectLiveArgs() {
+  const auditArgs = createFakeCurrentReleaseAuditArgs('direct-live-args-audit-ok');
+  const baseArgs = [
+    '--apply',
+    '--preflight-env-file',
+    path.join(tmpRoot, 'pingora-gateway.env'),
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-env-file',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-service-binary-executable',
+    '--preflight-check-ports-free',
+    ...auditArgs,
+    '--no-status',
+  ];
+
+  const httpsResult = runEnable(baseArgs);
+  assertApplyFailure(
+    httpsResult,
+    '--apply 必须同时提供 --direct-https-base-url',
+    '--apply 缺少 --direct-https-base-url 必须被拒绝。',
+  );
+
+  const httpResult = runEnable([
+    ...baseArgs,
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+  ]);
+  assertApplyFailure(
+    httpResult,
+    '--apply 必须同时提供 --direct-http-base-url',
+    '--apply 缺少 --direct-http-base-url 必须被拒绝。',
+  );
+
+  const hostResult = runEnable([
+    ...baseArgs,
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+  ]);
+  assertApplyFailure(
+    hostResult,
+    '--apply 必须同时提供 --direct-host',
+    '--apply 缺少 --direct-host 必须被拒绝。',
+  );
+
+  const redirectHostResult = runEnable([
+    ...baseArgs,
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+  ]);
+  assertApplyFailure(
+    redirectHostResult,
+    '--apply 必须同时提供 --direct-redirect-host',
+    '--apply 缺少 --direct-redirect-host 必须被拒绝。',
+  );
+
+  const accessLogResult = runEnable([
+    ...baseArgs,
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+  ]);
+  assertApplyFailure(
+    accessLogResult,
+    '--apply 必须同时提供 --direct-pingora-access-log',
+    '--apply 缺少 --direct-pingora-access-log 必须被拒绝。',
+  );
+
+  const databaseResult = runEnable([
+    ...baseArgs,
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+  ]);
+  assertApplyFailure(
+    databaseResult,
+    '--apply 必须同时提供 --direct-spacetime-database',
+    '--apply 缺少 --direct-spacetime-database 必须被拒绝。',
+  );
+}
+
+function assertRejectsControlCharacterInputsBeforeApply() {
+  const fixture = createApplyPathSafetyFixture('control-character-input');
+  const dropinPath = path.join(fixture.root, 'service.d', 'direct-entry.conf');
+  const result = runEnable([
+    ...fixture.args,
+    '--dropin-path',
+    dropinPath,
+    '--direct-host',
+    'example.com\ninjected.example.com',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('带换行的 direct host 必须在 apply 修改系统前被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--direct-host 不能包含换行或 NUL 字符',
+    'direct host 控制字符负例必须给出明确错误。',
+  );
+  if (existsSync(dropinPath)) {
+    failures.push('带换行的 direct host 被拒绝后不应安装 direct-entry drop-in。');
+  }
+}
+
+function assertApplyFailsWhenCurrentReleaseAuditFailsBeforeInstall() {
+  const templatePath = path.join(tmpRoot, 'audit-fail-template.conf');
+  const dropinPath = path.join(tmpRoot, 'audit-fail-service.d', 'direct-entry.conf');
+  const envPath = path.join(tmpRoot, 'audit-fail-pingora-gateway.env');
+  const auditScript = path.join(tmpRoot, 'fake-current-release-audit-fail.mjs');
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    auditScript,
+    '#!/usr/bin/env node\nconsole.error("fake current release audit failed");\nprocess.exit(21);\n',
+    'utf8',
+  );
+  chmodExecutable(auditScript);
+
+  const result = runEnable([
+    '--apply',
+    '--template-path',
+    templatePath,
+    '--dropin-path',
+    dropinPath,
+    '--current-release-audit-script',
+    auditScript,
+    '--current-release-root',
+    tmpRoot,
+    '--preflight-env-file',
+    envPath,
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-env-file',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-service-binary-executable',
+    '--preflight-check-ports-free',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('current release 自审失败时 enable apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'fake current release audit failed',
+    'current release 自审失败时必须暴露自审错误。',
+  );
+  if (existsSync(dropinPath)) {
+    failures.push('current release 自审失败发生在安装前，不应留下 direct-entry drop-in。');
+  }
+}
+
+function assertApplyFailsWhenPreflightScriptMissingBeforeInstall() {
+  const templatePath = path.join(tmpRoot, 'preflight-missing-template.conf');
+  const dropinPath = path.join(
+    tmpRoot,
+    'preflight-missing-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(tmpRoot, 'preflight-missing-pingora-gateway.env');
+  const missingPreflightScript = path.join(
+    tmpRoot,
+    'missing-check-pingora-direct-preflight.mjs',
+  );
+  const directLiveScript = path.join(tmpRoot, 'fake-direct-live-preflight-missing.mjs');
+  const auditArgs = createFakeCurrentReleaseAuditArgs('preflight-missing-audit-ok');
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    directLiveScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-direct-live] OK");\n',
+    'utf8',
+  );
+  chmodExecutable(directLiveScript);
+
+  const result = runEnable([
+    '--apply',
+    '--template-path',
+    templatePath,
+    '--dropin-path',
+    dropinPath,
+    ...auditArgs,
+    '--preflight-script',
+    missingPreflightScript,
+    '--preflight-env-file',
+    envPath,
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-env-file',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-service-binary-executable',
+    '--preflight-check-ports-free',
+    '--direct-live-script',
+    directLiveScript,
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('direct preflight 脚本缺失时 enable apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'direct preflight 脚本不存在',
+    'direct preflight 脚本缺失时必须给出明确错误。',
+  );
+  if (existsSync(dropinPath)) {
+    failures.push('direct preflight 脚本缺失发生在安装前，不应留下 direct-entry drop-in。');
+  }
+}
+
+function assertApplyFailsWhenDirectLiveScriptMissingBeforeInstall() {
+  const templatePath = path.join(tmpRoot, 'direct-live-missing-template.conf');
+  const dropinPath = path.join(
+    tmpRoot,
+    'direct-live-missing-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(tmpRoot, 'direct-live-missing-pingora-gateway.env');
+  const preflightScript = path.join(tmpRoot, 'fake-preflight-direct-live-missing.mjs');
+  const missingDirectLiveScript = path.join(
+    tmpRoot,
+    'missing-check-pingora-direct-live.mjs',
+  );
+  const auditArgs = createFakeCurrentReleaseAuditArgs('direct-live-missing-audit-ok');
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    preflightScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-preflight] OK");\n',
+    'utf8',
+  );
+  chmodExecutable(preflightScript);
+
+  const result = runEnable([
+    '--apply',
+    '--template-path',
+    templatePath,
+    '--dropin-path',
+    dropinPath,
+    ...auditArgs,
+    '--preflight-script',
+    preflightScript,
+    '--preflight-env-file',
+    envPath,
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-env-file',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-service-binary-executable',
+    '--preflight-check-ports-free',
+    '--direct-live-script',
+    missingDirectLiveScript,
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('direct live smoke 脚本缺失时 enable apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'direct live smoke 脚本不存在',
+    'direct live smoke 脚本缺失时必须给出明确错误。',
+  );
+  if (existsSync(dropinPath)) {
+    failures.push('direct live smoke 脚本缺失发生在安装前，不应留下 direct-entry drop-in。');
+  }
+}
+
+function assertApplyRejectsSymlinkDropinDirectoryBeforeInstall() {
+  const fixture = createApplyPathSafetyFixture('symlink-dropin-dir');
+  const realDropinDir = path.join(fixture.root, 'real-service.d');
+  const symlinkDropinDir = path.join(fixture.root, 'linked-service.d');
+  mkdirSync(realDropinDir, { recursive: true });
+  symlinkSync(realDropinDir, symlinkDropinDir);
+  const dropinPath = path.join(symlinkDropinDir, 'direct-entry.conf');
+
+  const result = runEnable([...fixture.args, '--dropin-path', dropinPath]);
+
+  if (result.status === 0) {
+    failures.push('drop-in 目录是符号链接时 enable apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'drop-in 目录不能是符号链接',
+    'drop-in 符号链接目录负例必须给出明确错误。',
+  );
+  if (existsSync(path.join(realDropinDir, 'direct-entry.conf'))) {
+    failures.push('drop-in 目录是符号链接时不应写入真实目标目录。');
+  }
+}
+
+function assertApplyRejectsSymlinkDropinFileBeforeInstall() {
+  const fixture = createApplyPathSafetyFixture('symlink-dropin-file');
+  const dropinDir = path.join(fixture.root, 'service.d');
+  const realDropinFile = path.join(fixture.root, 'real-direct-entry.conf');
+  const symlinkDropinFile = path.join(dropinDir, 'direct-entry.conf');
+  mkdirSync(dropinDir, { recursive: true });
+  writeFileSync(realDropinFile, 'original dropin\n', 'utf8');
+  symlinkSync(realDropinFile, symlinkDropinFile);
+
+  const result = runEnable([...fixture.args, '--dropin-path', symlinkDropinFile]);
+
+  if (result.status === 0) {
+    failures.push('drop-in 目标是符号链接时 enable apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'drop-in 目标不能是符号链接',
+    'drop-in 符号链接目标负例必须给出明确错误。',
+  );
+  const realContent = readFileSync(realDropinFile, 'utf8');
+  if (realContent !== 'original dropin\n') {
+    failures.push('drop-in 目标是符号链接时不应改写真实目标文件。');
+  }
+}
+
+function assertApplyFailsWhenSystemdEnvFileDiffers() {
+  const templatePath = path.join(tmpRoot, 'systemd-env-mismatch-template.conf');
+  const dropinPath = path.join(
+    tmpRoot,
+    'systemd-env-mismatch-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(tmpRoot, 'systemd-env-mismatch-pingora-gateway.env');
+  const preflightScript = path.join(tmpRoot, 'fake-preflight-env-ok.mjs');
+  const directLiveScript = path.join(tmpRoot, 'fake-direct-live-env-ok.mjs');
+  const auditArgs = createFakeCurrentReleaseAuditArgs('systemd-env-mismatch-audit-ok');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    preflightScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-preflight] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    directLiveScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-direct-live] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  echo "EnvironmentFile=/etc/genarrative/other-pingora.env"',
+      '  echo "AmbientCapabilities=CAP_NET_BIND_SERVICE"',
+      '  echo "CapabilityBoundingSet=CAP_NET_BIND_SERVICE"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(preflightScript);
+  chmodExecutable(directLiveScript);
+  chmodExecutable(systemctlBinary);
+
+  const result = runEnable(
+    [
+      '--apply',
+      '--template-path',
+      templatePath,
+      '--dropin-path',
+      dropinPath,
+      ...auditArgs,
+      '--preflight-script',
+      preflightScript,
+      '--preflight-env-file',
+      envPath,
+      '--preflight-check-cert-readable',
+      '--preflight-check-service-env-file',
+      '--preflight-check-service-user-cert-readable',
+      '--preflight-check-service-binary-executable',
+      '--preflight-check-ports-free',
+      '--direct-live-script',
+      directLiveScript,
+      '--direct-https-base-url',
+      'https://127.0.0.1',
+      '--direct-http-base-url',
+      'http://127.0.0.1',
+      '--direct-host',
+      'example.com',
+      '--direct-redirect-host',
+      'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+      '--direct-spacetime-database',
+      'genarrative-prod',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push('systemctl cat 的 EnvironmentFile 漂移时 enable apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    `systemctl cat 未显示 EnvironmentFile=${envPath}`,
+    'systemd 最终配置读取的 env 和 preflight env 不一致时必须给出明确错误。',
+  );
+}
+
+function assertApplyFailsWhenSystemdEnvFileOnlySharesPrefix() {
+  const templatePath = path.join(tmpRoot, 'systemd-env-prefix-template.conf');
+  const dropinPath = path.join(
+    tmpRoot,
+    'systemd-env-prefix-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(tmpRoot, 'systemd-env-prefix-pingora-gateway.env');
+  const preflightScript = path.join(tmpRoot, 'fake-preflight-prefix-ok.mjs');
+  const directLiveScript = path.join(tmpRoot, 'fake-direct-live-prefix-ok.mjs');
+  const auditArgs = createFakeCurrentReleaseAuditArgs('systemd-env-prefix-audit-ok');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    preflightScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-preflight] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    directLiveScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-direct-live] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      `  echo "EnvironmentFile=${envPath}.bak"`,
+      '  echo "AmbientCapabilities=CAP_NET_BIND_SERVICE"',
+      '  echo "CapabilityBoundingSet=CAP_NET_BIND_SERVICE"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(preflightScript);
+  chmodExecutable(directLiveScript);
+  chmodExecutable(systemctlBinary);
+
+  const result = runEnable(
+    [
+      '--apply',
+      '--template-path',
+      templatePath,
+      '--dropin-path',
+      dropinPath,
+      ...auditArgs,
+      '--preflight-script',
+      preflightScript,
+      '--preflight-env-file',
+      envPath,
+      '--preflight-check-cert-readable',
+      '--preflight-check-service-env-file',
+      '--preflight-check-service-user-cert-readable',
+      '--preflight-check-service-binary-executable',
+      '--preflight-check-ports-free',
+      '--direct-live-script',
+      directLiveScript,
+      '--direct-https-base-url',
+      'https://127.0.0.1',
+      '--direct-http-base-url',
+      'http://127.0.0.1',
+      '--direct-host',
+      'example.com',
+      '--direct-redirect-host',
+      'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+      '--direct-spacetime-database',
+      'genarrative-prod',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push(
+      'systemctl cat 的 EnvironmentFile 只共享路径前缀时 enable apply 必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    `systemctl cat 未显示 EnvironmentFile=${envPath}`,
+    'systemd 最终配置 EnvironmentFile 不能用路径前缀误判为一致。',
+  );
+}
+
+function assertApplyFailsWhenDirectLiveSmokeFails() {
+  const templatePath = path.join(tmpRoot, 'direct-live-fail-template.conf');
+  const serviceUnitPath = path.join(tmpRoot, 'direct-live-fail-service.service');
+  const dropinPath = path.join(
+    tmpRoot,
+    'direct-live-fail-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(tmpRoot, 'direct-live-fail-pingora-gateway.env');
+  const certPath = path.join(tmpRoot, 'direct-live-fail-cert.pem');
+  const keyPath = path.join(tmpRoot, 'direct-live-fail-key.pem');
+  const preflightScript = path.join(tmpRoot, 'fake-preflight-ok.mjs');
+  const directLiveScript = path.join(tmpRoot, 'fake-direct-live-fail.mjs');
+  const auditArgs = createFakeCurrentReleaseAuditArgs('direct-live-fail-audit-ok');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    serviceUnitPath,
+    [
+      '[Unit]',
+      'Description=Pingora 影子网关只监听本机高端口',
+      '[Service]',
+      `EnvironmentFile=${envPath}`,
+      'ExecStart=/opt/genarrative/current/pingora-gateway',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(certPath, 'fake-cert\n', 'utf8');
+  writeFileSync(keyPath, 'fake-key\n', 'utf8');
+  writeFileSync(
+    envPath,
+    [
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
+      'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=${certPath}`,
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=${keyPath}`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    preflightScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-preflight] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    directLiveScript,
+    '#!/usr/bin/env node\nconsole.error("fake direct live failed");\nprocess.exit(12);\n',
+    'utf8',
+  );
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      `  echo "EnvironmentFile=${envPath}"`,
+      '  echo "AmbientCapabilities=CAP_NET_BIND_SERVICE"',
+      '  echo "CapabilityBoundingSet=CAP_NET_BIND_SERVICE"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/current/pingora-gateway ; argv[]=/opt/genarrative/current/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(preflightScript);
+  chmodExecutable(directLiveScript);
+  chmodExecutable(systemctlBinary);
+
+  const result = runEnable(
+    [
+      '--apply',
+      '--service-unit-path',
+      serviceUnitPath,
+      '--template-path',
+      templatePath,
+      '--dropin-path',
+      dropinPath,
+      ...auditArgs,
+      '--preflight-script',
+      preflightScript,
+      '--preflight-env-file',
+      envPath,
+      '--preflight-check-cert-readable',
+      '--preflight-check-service-env-file',
+      '--preflight-check-service-user-cert-readable',
+      '--preflight-check-service-binary-executable',
+      '--preflight-check-ports-free',
+      '--direct-live-script',
+      directLiveScript,
+      '--direct-https-base-url',
+      'https://127.0.0.1',
+      '--direct-http-base-url',
+      'http://127.0.0.1',
+      '--direct-host',
+      'example.com',
+      '--direct-redirect-host',
+      'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+      '--direct-spacetime-database',
+      'genarrative-prod',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push('direct live smoke 失败时 enable apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'fake direct live failed',
+    'direct live smoke 失败时必须暴露检查错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push(
+      'direct live smoke 失败发生在安装后，临时 drop-in 应已存在供后续回退脚本处理。',
+    );
+  }
+}
+
+function assertApplyFailsWhenDirectLiveAccessLogJsonMissing() {
+  const templatePath = path.join(tmpRoot, 'direct-live-json-missing-template.conf');
+  const serviceUnitPath = path.join(
+    tmpRoot,
+    'direct-live-json-missing-service.service',
+  );
+  const dropinPath = path.join(
+    tmpRoot,
+    'direct-live-json-missing-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(
+    tmpRoot,
+    'direct-live-json-missing-pingora-gateway.env',
+  );
+  const preflightScript = path.join(
+    tmpRoot,
+    'fake-preflight-json-missing-ok.mjs',
+  );
+  const directLiveScript = path.join(
+    tmpRoot,
+    'fake-direct-live-json-missing.mjs',
+  );
+  const auditArgs = createFakeCurrentReleaseAuditArgs(
+    'direct-live-json-missing-audit-ok',
+  );
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    serviceUnitPath,
+    [
+      '[Unit]',
+      'Description=Pingora 影子网关只监听本机高端口',
+      '[Service]',
+      `EnvironmentFile=${envPath}`,
+      'ExecStart=/opt/genarrative/current/pingora-gateway',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    preflightScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-preflight] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    directLiveScript,
+    [
+      '#!/usr/bin/env node',
+      'console.log("[fake-direct-live] OK");',
+      'console.log(JSON.stringify({ ok: true, results: [{ name: "https-root" }] }, null, 2));',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      `  echo "EnvironmentFile=${envPath}"`,
+      '  echo "AmbientCapabilities=CAP_NET_BIND_SERVICE"',
+      '  echo "CapabilityBoundingSet=CAP_NET_BIND_SERVICE"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/current/pingora-gateway ; argv[]=/opt/genarrative/current/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(preflightScript);
+  chmodExecutable(directLiveScript);
+  chmodExecutable(systemctlBinary);
+
+  const result = runEnable(
+    [
+      '--apply',
+      '--service-unit-path',
+      serviceUnitPath,
+      '--template-path',
+      templatePath,
+      '--dropin-path',
+      dropinPath,
+      ...auditArgs,
+      '--preflight-script',
+      preflightScript,
+      '--preflight-env-file',
+      envPath,
+      '--preflight-check-cert-readable',
+      '--preflight-check-service-env-file',
+      '--preflight-check-service-user-cert-readable',
+      '--preflight-check-service-binary-executable',
+      '--preflight-check-ports-free',
+      '--direct-live-script',
+      directLiveScript,
+      '--direct-https-base-url',
+      'https://127.0.0.1',
+      '--direct-http-base-url',
+      'http://127.0.0.1',
+      '--direct-host',
+      'example.com',
+      '--direct-redirect-host',
+      'example.com',
+      '--direct-pingora-access-log',
+      '/var/log/genarrative/pingora-gateway.access.log',
+      '--direct-spacetime-database',
+      'genarrative-prod',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push(
+      'direct live JSON 缺少 direct-access-log 时 enable apply 必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    'direct live JSON 缺少 direct-access-log 结构化结果',
+    'direct live JSON 缺少 access log 结构化结果时必须给出明确错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push(
+      'direct live JSON 结构化证据失败发生在安装后，临时 drop-in 应已存在供后续回退脚本处理。',
+    );
+  }
+}
+
+function assertApplyFailsWhenSystemdExecStartDiffers() {
+  const templatePath = path.join(tmpRoot, 'systemd-exec-mismatch-template.conf');
+  const serviceUnitPath = path.join(tmpRoot, 'systemd-exec-mismatch.service');
+  const dropinPath = path.join(
+    tmpRoot,
+    'systemd-exec-mismatch-service.d',
+    'direct-entry.conf',
+  );
+  const envPath = path.join(tmpRoot, 'systemd-exec-mismatch-pingora-gateway.env');
+  const preflightScript = path.join(tmpRoot, 'fake-preflight-exec-ok.mjs');
+  const directLiveScript = path.join(tmpRoot, 'fake-direct-live-exec-ok.mjs');
+  const auditArgs = createFakeCurrentReleaseAuditArgs('systemd-exec-mismatch-audit-ok');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    serviceUnitPath,
+    [
+      '[Unit]',
+      'Description=Pingora 影子网关只监听本机高端口',
+      '[Service]',
+      `EnvironmentFile=${envPath}`,
+      'ExecStart=/opt/genarrative/current/pingora-gateway',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    preflightScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-preflight] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    directLiveScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-direct-live] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      `  echo "EnvironmentFile=${envPath}"`,
+      '  echo "AmbientCapabilities=CAP_NET_BIND_SERVICE"',
+      '  echo "CapabilityBoundingSet=CAP_NET_BIND_SERVICE"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/old-release/pingora-gateway ; argv[]=/opt/genarrative/old-release/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(preflightScript);
+  chmodExecutable(directLiveScript);
+  chmodExecutable(systemctlBinary);
+
+  const result = runEnable(
+    [
+      '--apply',
+      '--service-unit-path',
+      serviceUnitPath,
+      '--template-path',
+      templatePath,
+      '--dropin-path',
+      dropinPath,
+      ...auditArgs,
+      '--preflight-script',
+      preflightScript,
+      '--preflight-env-file',
+      envPath,
+      '--preflight-check-cert-readable',
+      '--preflight-check-service-env-file',
+      '--preflight-check-service-user-cert-readable',
+      '--preflight-check-service-binary-executable',
+      '--preflight-check-ports-free',
+      '--direct-live-script',
+      directLiveScript,
+      '--direct-https-base-url',
+      'https://127.0.0.1',
+      '--direct-http-base-url',
+      'http://127.0.0.1',
+      '--direct-host',
+      'example.com',
+      '--direct-redirect-host',
+      'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+      '--direct-spacetime-database',
+      'genarrative-prod',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push('systemctl show ExecStart 指向旧 release 时 enable apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'systemctl show ExecStart 未指向主 service 模板中的 /opt/genarrative/current/pingora-gateway',
+    'systemd 最终 ExecStart 指向旧 release 时必须给出明确错误。',
+  );
+}
+
+function runEnable(args, env = {}) {
+  return spawnSync('bash', [ENABLE_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      ...env,
+    },
+  });
+}
+
+function runPreflight(args, env = {}) {
+  return spawnSync(process.execPath, ['--', PREFLIGHT_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      ...env,
+    },
+  });
+}
+
+function chmodExecutable(filePath) {
+  spawnSync('chmod', ['0755', filePath], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function createFakeCurrentReleaseAuditArgs(name) {
+  const auditScript = path.join(tmpRoot, `${name}.mjs`);
+  writeFileSync(
+    auditScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-current-release-audit] OK");\n',
+    'utf8',
+  );
+  chmodExecutable(auditScript);
+  return ['--current-release-audit-script', auditScript, '--current-release-root', tmpRoot];
+}
+
+function createApplyPathSafetyFixture(name) {
+  const root = path.join(tmpRoot, name);
+  mkdirSync(root, { recursive: true });
+  const templatePath = path.join(root, 'template.conf');
+  const envPath = path.join(root, 'pingora-gateway.env');
+  const preflightScript = path.join(root, 'fake-preflight.mjs');
+  const directLiveScript = path.join(root, 'fake-direct-live.mjs');
+  const auditArgs = createFakeCurrentReleaseAuditArgs(`${name}-audit-ok`);
+
+  writeFileSync(
+    templatePath,
+    [
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(envPath, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https\n', 'utf8');
+  writeFileSync(
+    preflightScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-preflight] OK");\n',
+    'utf8',
+  );
+  writeFileSync(
+    directLiveScript,
+    '#!/usr/bin/env node\nconsole.log("[fake-direct-live] OK");\n',
+    'utf8',
+  );
+  chmodExecutable(preflightScript);
+  chmodExecutable(directLiveScript);
+
+  return {
+    root,
+    args: [
+      '--apply',
+      '--template-path',
+      templatePath,
+      ...auditArgs,
+      '--preflight-script',
+      preflightScript,
+      '--preflight-env-file',
+      envPath,
+      '--preflight-check-cert-readable',
+      '--preflight-check-service-env-file',
+      '--preflight-check-service-user-cert-readable',
+      '--preflight-check-service-binary-executable',
+      '--preflight-check-ports-free',
+      '--direct-live-script',
+      directLiveScript,
+      '--direct-https-base-url',
+      'https://127.0.0.1',
+      '--direct-http-base-url',
+      'http://127.0.0.1',
+      '--direct-host',
+      'example.com',
+      '--direct-redirect-host',
+      'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+      '--direct-spacetime-database',
+      'genarrative-prod',
+      '--no-status',
+    ],
+  };
+}
+
+function assertApplyFailure(result, needle, reason) {
+  if (result.status === 0) {
+    failures.push(reason);
+    return;
+  }
+  assertIncludes(result.stderr, needle, `${reason} 错误信息应明确。`);
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!content.includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
+
+function allocateLoopbackPorts(count) {
+  const ports = [];
+  for (let offset = 0; ports.length < count && offset < 1000; offset += 1) {
+    const candidate = 28080 + offset;
+    const result = spawnSync(
+      process.execPath,
+      [
+        '-e',
+        [
+          "const net = require('node:net');",
+          `const server = net.createServer();`,
+          `server.once('error', () => process.exit(1));`,
+          `server.listen(${candidate}, '127.0.0.1', () => server.close(() => process.exit(0)));`,
+        ].join(''),
+      ],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+      },
+    );
+    if ((result.status ?? 1) === 0) {
+      ports.push(candidate);
+    }
+  }
+  if (ports.length !== count) {
+    throw new Error('无法为 Pingora direct enable 自测分配空闲 loopback 端口。');
+  }
+  return ports;
+}
diff --git a/scripts/check-pingora-direct-live-guard.mjs b/scripts/check-pingora-direct-live-guard.mjs
new file mode 100644
index 000000000..7984f2d38
--- /dev/null
+++ b/scripts/check-pingora-direct-live-guard.mjs
@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const DIRECT_LIVE_SCRIPT = 'scripts/check-pingora-direct-live.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-direct-live-guard-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-direct-live-guard] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-direct-live-guard] OK');
+
+function main() {
+  assertRejectsControlCharacter('--https-base-url', [
+    '--https-base-url',
+    'https://127.0.0.1\n--fake-flag',
+  ]);
+  assertRejectsControlCharacter('--http-base-url', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--http-base-url',
+    'http://127.0.0.1\r--fake-flag',
+  ]);
+  assertRejectsControlCharacter('--host', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--host',
+    'example.com\nX-Injected: yes',
+  ]);
+  assertRejectsControlCharacter('--redirect-host', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--redirect-host',
+    'example.com\nhidden',
+  ]);
+  assertRejectsControlCharacter('--redirect-base-url', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--redirect-base-url',
+    'https://example.com\nhidden',
+  ]);
+  assertRejectsInvalidRedirectBaseUrl();
+  assertRejectsControlCharacter('--probe-token', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--probe-token',
+    'probe\nX-Injected: yes',
+    '--skip-wss',
+  ]);
+  assertRejectsControlCharacter('--path', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--path',
+    '/api/health\nX-Injected: yes',
+    '--skip-wss',
+  ]);
+  assertRejectsControlCharacter('--pingora-access-log', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--pingora-access-log',
+    `${path.join(tmpRoot, 'pingora.access.log')}\n--fake-flag`,
+    '--skip-wss',
+  ]);
+  assertRejectsControlCharacter('--spacetime-database', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--spacetime-database',
+    'genarrative\nprod',
+    '--skip-wss',
+  ]);
+  assertRejectsControlCharacter('--timeout-ms', [
+    '--https-base-url',
+    'https://127.0.0.1',
+    '--timeout-ms',
+    '5000\n1',
+    '--skip-wss',
+  ]);
+}
+
+function assertRejectsInvalidRedirectBaseUrl() {
+  const result = spawnSync(
+    'node',
+    [
+      DIRECT_LIVE_SCRIPT,
+      '--https-base-url',
+      'https://127.0.0.1',
+      '--redirect-base-url',
+      'http://example.com',
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: process.env,
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('--redirect-base-url 必须拒绝非 HTTPS base URL。');
+    return;
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--redirect-base-url 必须使用 https://',
+    '--redirect-base-url 非 HTTPS 时必须给出明确错误。',
+  );
+}
+
+function assertRejectsControlCharacter(label, args) {
+  const result = spawnSync('node', [DIRECT_LIVE_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: process.env,
+  });
+  if ((result.status ?? 0) === 0) {
+    failures.push(`${label} 带控制字符时必须在发起 live 请求前失败。`);
+    return;
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    `${label} 不能包含换行或 NUL 字符`,
+    `${label} 带控制字符时必须给出明确错误。`,
+  );
+}
+
+function assertIncludes(value, expected, reason) {
+  if (!String(value).includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
diff --git a/scripts/check-pingora-direct-live.mjs b/scripts/check-pingora-direct-live.mjs
new file mode 100644
index 000000000..1fb3c48fe
--- /dev/null
+++ b/scripts/check-pingora-direct-live.mjs
@@ -0,0 +1,1387 @@
+#!/usr/bin/env node
+
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import tls from 'node:tls';
+import { createHash, randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import nodePath from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_SPACETIME_DATABASE = 'genarrative-prod';
+const SPACETIME_WEBSOCKET_PROTOCOL = 'v2.bsatn.spacetimedb';
+
+const failures = [];
+let config;
+
+try {
+  config = parseArgs(process.argv.slice(2));
+  await main();
+} catch (error) {
+  failures.push(error instanceof Error ? error.message : String(error));
+}
+
+if (failures.length > 0) {
+  console.error('[pingora-direct-live] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[pingora-direct-live] OK');
+
+function usage() {
+  console.log(`Usage:
+  node scripts/check-pingora-direct-live.mjs --https-base-url <url> [options]
+
+Options:
+  --https-base-url <url> HTTPS base URL served directly by pingora-gateway.
+  --http-base-url <url>  Optional HTTP base URL that should 301 to HTTPS.
+  --host <host>          Optional Host header for local --resolve style checks.
+  --redirect-host <host> Optional expected Location host for HTTP redirects.
+  --redirect-base-url <url>
+                         Optional expected HTTPS base URL for HTTP redirects.
+  --probe-token <token>  Optional Pingora shadow probe token.
+  --spacetime-database <name>
+                         SpacetimeDB database for WSS subscribe smoke, default genarrative-prod.
+  --require-wss-upgrade  Require WSS subscribe to return 101 Switching Protocols.
+  --skip-wss             Skip WSS subscribe handshake smoke.
+  --path <path>          Extra HTTPS path to probe; repeatable.
+  --pingora-access-log <path>
+                         Optional Pingora access log path. When set, direct live asserts its generated request ids were logged.
+  --access-log-since-lines <count>
+                         Tail lines to read from Pingora access log, default 2000.
+  --timeout-ms <ms>      Request timeout, default 5000.
+  --insecure-tls         Allow self-signed certificates for local smoke only.
+  --json                 Print JSON result.
+
+Environment aliases:
+  GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL
+  GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL
+  GENARRATIVE_PINGORA_DIRECT_HOST
+  GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST
+  GENARRATIVE_PINGORA_DIRECT_REDIRECT_BASE_URL
+  GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN
+  GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE
+  GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE
+  GENARRATIVE_PINGORA_DIRECT_SKIP_WSS
+  GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG
+  GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES
+  GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS
+  GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS
+`);
+}
+
+function parseArgs(argv) {
+  const result = {
+    httpsBaseUrl: process.env.GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL || '',
+    httpBaseUrl: process.env.GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL || '',
+    host: process.env.GENARRATIVE_PINGORA_DIRECT_HOST || '',
+    redirectHost: process.env.GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST || '',
+    redirectBaseUrl:
+      process.env.GENARRATIVE_PINGORA_DIRECT_REDIRECT_BASE_URL || '',
+    probeToken: process.env.GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN || '',
+    spacetimeDatabase:
+      process.env.GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE ||
+      process.env.GENARRATIVE_SPACETIME_DATABASE ||
+      DEFAULT_SPACETIME_DATABASE,
+    requireWssUpgrade: parseBoolEnv(
+      process.env.GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE',
+    ),
+    skipWss: parseBoolEnv(
+      process.env.GENARRATIVE_PINGORA_DIRECT_SKIP_WSS,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_SKIP_WSS',
+    ),
+    pingoraAccessLog:
+      process.env.GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG || '',
+    accessLogSinceLines: parseOptionalPositiveInt(
+      process.env.GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES,
+      2000,
+      'GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES',
+    ),
+    timeoutMs: parseOptionalPositiveInt(
+      process.env.GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS,
+      DEFAULT_TIMEOUT_MS,
+      'GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS',
+    ),
+    insecureTls: parseBoolEnv(
+      process.env.GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS',
+    ),
+    json: false,
+    extraPaths: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        usage();
+        process.exit(0);
+        break;
+      case '--https-base-url':
+        result.httpsBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--http-base-url':
+        result.httpBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--host':
+        result.host = requireValue(argv, ++index, arg);
+        break;
+      case '--redirect-host':
+        result.redirectHost = requireValue(argv, ++index, arg);
+        break;
+      case '--redirect-base-url':
+        result.redirectBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--probe-token':
+        result.probeToken = requireValue(argv, ++index, arg);
+        break;
+      case '--spacetime-database':
+        result.spacetimeDatabase = requireValue(argv, ++index, arg);
+        break;
+      case '--require-wss-upgrade':
+        result.requireWssUpgrade = true;
+        break;
+      case '--skip-wss':
+        result.skipWss = true;
+        break;
+      case '--path':
+        result.extraPaths.push(requireValue(argv, ++index, arg));
+        break;
+      case '--pingora-access-log':
+        result.pingoraAccessLog = requireValue(argv, ++index, arg);
+        break;
+      case '--access-log-since-lines':
+        result.accessLogSinceLines = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          '--access-log-since-lines',
+        );
+        break;
+      case '--timeout-ms':
+        result.timeoutMs = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          '--timeout-ms',
+        );
+        break;
+      case '--insecure-tls':
+        result.insecureTls = true;
+        break;
+      case '--json':
+        result.json = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (!result.httpsBaseUrl) {
+    throw new Error(
+      '缺少 --https-base-url 或 GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL',
+    );
+  }
+  validateNoControlCharacters(result.httpsBaseUrl, '--https-base-url');
+  const httpsUrl = new URL(result.httpsBaseUrl);
+  if (httpsUrl.protocol !== 'https:') {
+    throw new Error('--https-base-url 必须使用 https://');
+  }
+  if (result.httpBaseUrl) {
+    validateNoControlCharacters(result.httpBaseUrl, '--http-base-url');
+    const httpUrl = new URL(result.httpBaseUrl);
+    if (httpUrl.protocol !== 'http:') {
+      throw new Error('--http-base-url 必须使用 http://');
+    }
+  }
+  if (result.host) {
+    validateHostOption(result.host, '--host');
+  }
+  if (result.redirectHost) {
+    validateHostOption(result.redirectHost, '--redirect-host');
+  }
+  if (result.redirectBaseUrl) {
+    validateHttpsBaseUrl(result.redirectBaseUrl, '--redirect-base-url');
+  }
+  if (result.probeToken) {
+    validateNoControlCharacters(result.probeToken, '--probe-token');
+  }
+  for (const extraPath of result.extraPaths) {
+    validateNoControlCharacters(extraPath, '--path');
+  }
+  if (result.pingoraAccessLog) {
+    validateSafeAbsoluteFilePath(
+      result.pingoraAccessLog,
+      '--pingora-access-log',
+    );
+  }
+  validateNoControlCharacters(
+    result.spacetimeDatabase,
+    '--spacetime-database',
+  );
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(result.spacetimeDatabase)) {
+    throw new Error(
+      '--spacetime-database 必须匹配 SpacetimeDB 数据库名规则 ^[a-z0-9]+(-[a-z0-9]+)*$',
+    );
+  }
+
+  return result;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function validateHostOption(value, flag) {
+  const raw = String(value);
+  validateNoControlCharacters(raw, flag);
+  if (raw !== raw.trim() || raw.includes('://') || /[\s/?#@]/.test(raw)) {
+    throw new Error(
+      `${flag} 只能是 host 或 host:port，不能包含 scheme、路径、查询、片段或空白字符`,
+    );
+  }
+  try {
+    const parsed = new URL(`https://${raw}`);
+    if (
+      !parsed.hostname ||
+      parsed.pathname !== '/' ||
+      parsed.search ||
+      parsed.hash ||
+      parsed.username ||
+      parsed.password
+    ) {
+      throw new Error('invalid host');
+    }
+  } catch {
+    throw new Error(`${flag} 不是合法的 host 或 host:port`);
+  }
+}
+
+function validateHttpsBaseUrl(value, flag) {
+  validateNoControlCharacters(value, flag);
+  const parsed = new URL(value);
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`${flag} 必须使用 https://`);
+  }
+  if (
+    !parsed.hostname ||
+    parsed.pathname !== '/' ||
+    parsed.search ||
+    parsed.hash ||
+    parsed.username ||
+    parsed.password
+  ) {
+    throw new Error(
+      `${flag} 只能是 HTTPS base URL，不能包含路径、查询、片段或认证信息。`,
+    );
+  }
+}
+
+function validateSafeAbsoluteFilePath(filePath, label) {
+  validateNoControlCharacters(filePath, label);
+  if (!nodePath.isAbsolute(filePath)) {
+    throw new Error(`${label} 必须是绝对路径。`);
+  }
+  if (isFilesystemRootPath(filePath)) {
+    throw new Error(`${label} 不能是文件系统根目录。`);
+  }
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = nodePath.resolve(String(value));
+  return resolved === nodePath.parse(resolved).root;
+}
+
+function parseOptionalPositiveInt(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parseRequiredPositiveInt(raw, label);
+}
+
+function parseRequiredPositiveInt(raw, label) {
+  validateNoControlCharacters(raw, label);
+  const text = String(raw ?? '').trim();
+  if (!/^[1-9]\d*$/.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  return Number.parseInt(text, 10);
+}
+
+function parseBoolEnv(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  validateNoControlCharacters(raw, label);
+  const normalized = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${label} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function joinUrl(baseUrl, path) {
+  const base = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+  const suffix = path.startsWith('/') ? path : `/${path}`;
+  return `${base}${suffix}`;
+}
+
+async function main() {
+  const directRequestIds = [];
+  const checks = [
+    {
+      name: 'https-root',
+      url: joinUrl(config.httpsBaseUrl, '/'),
+      expectedStatuses: [200, 503],
+      assertHeader: assertPingoraGatewayHeader,
+    },
+    {
+      name: 'https-api-config',
+      url: joinUrl(config.httpsBaseUrl, '/api/creation-entry/config'),
+      expectedStatuses: [200, 401, 403, 503],
+      assertHeader: assertPingoraGatewayHeader,
+    },
+    {
+      name: 'https-spacetime-identity',
+      url: joinUrl(config.httpsBaseUrl, '/v1/identity'),
+      expectedStatuses: [200, 401, 403, 404, 405, 503],
+      assertHeader: assertPingoraGatewayHeader,
+    },
+    {
+      name: 'https-generated-forbidden',
+      url: joinUrl(config.httpsBaseUrl, '/generated-pingora-direct-smoke'),
+      expectedStatus: 404,
+      assertHeader: assertPingoraGatewayHeader,
+    },
+    {
+      name: 'https-public-healthz-forbidden',
+      url: joinUrl(config.httpsBaseUrl, '/healthz'),
+      expectedStatus: 404,
+      assertHeader: assertPingoraGatewayHeader,
+    },
+  ];
+
+  if (config.probeToken) {
+    checks.push({
+      name: 'https-shadow-probe',
+      url: joinUrl(config.httpsBaseUrl, '/__genarrative_pingora/healthz'),
+      expectedStatus: 200,
+      headers: {
+        'X-Genarrative-Pingora-Probe': config.probeToken,
+      },
+      assertBody: (body) => body.includes('"gateway":"pingora-shadow"'),
+      bodyReason: 'body 应包含 gateway=pingora-shadow',
+      assertHeader: assertPingoraGatewayHeader,
+    });
+  }
+
+  if (config.httpBaseUrl) {
+    checks.push(
+      {
+        name: 'http-root-redirect',
+        url: joinUrl(config.httpBaseUrl, '/'),
+        expectedStatus: 301,
+        assertHeader: assertPingoraGatewayHeader,
+        assertLocation: (location) =>
+          location === directHttpsLocation(config.httpsBaseUrl, '/'),
+      },
+      {
+        name: 'http-api-redirect',
+        url: joinUrl(config.httpBaseUrl, '/api/creation-entry/config?direct=1'),
+        expectedStatus: 301,
+        assertHeader: assertPingoraGatewayHeader,
+        assertLocation: (location) =>
+          location ===
+          directHttpsLocation(
+            config.httpsBaseUrl,
+            '/api/creation-entry/config?direct=1',
+          ),
+      },
+      {
+        name: 'http-acme-static',
+        url: joinUrl(config.httpBaseUrl, '/.well-known/acme-challenge/token'),
+        expectedStatuses: [200, 404],
+        assertHeader: assertPingoraGatewayHeader,
+      },
+    );
+  }
+
+  for (const path of config.extraPaths) {
+    checks.push({
+      name: `extra:${path}`,
+      url: joinUrl(config.httpsBaseUrl, path),
+      expectedStatuses: [200, 204, 301, 302, 304, 401, 403, 404, 503],
+      assertHeader: assertPingoraGatewayHeader,
+    });
+  }
+
+  const results = [];
+  let rootResult = null;
+  for (const check of checks) {
+    const result = await runCheck(check, directRequestIds);
+    if (check.name === 'https-root') {
+      rootResult = result;
+    }
+    results.push(result);
+  }
+  results.push(await runDiscoveredStaticAssetCheck(rootResult, directRequestIds));
+  results.push(await runHttp2AlpnCheck());
+  if (!config.skipWss) {
+    results.push(await runWssSubscribeCheck(directRequestIds));
+  }
+  if (config.pingoraAccessLog) {
+    results.push(await runDirectAccessLogCheck(directRequestIds));
+  }
+
+  if (config.json) {
+    console.log(
+      JSON.stringify({ ok: failures.length === 0, results }, null, 2),
+    );
+  }
+}
+
+async function runCheck(check, directRequestIds) {
+  const requestId = makeDirectRequestId(check.name);
+  const directRequest = {
+    requestId,
+    name: check.name,
+    method: check.method || 'GET',
+    path: new URL(check.url).pathname,
+    statusCode: null,
+  };
+  directRequestIds.push(directRequest);
+  const response = await requestUrl(check.url, {
+    method: check.method,
+    headers: {
+      'X-Request-Id': requestId,
+      ...(check.headers || {}),
+    },
+  });
+  directRequest.statusCode = response.statusCode;
+  const expectedStatuses =
+    check.expectedStatuses ?? [check.expectedStatus].filter(Boolean);
+
+  if (!expectedStatuses.includes(response.statusCode)) {
+    failures.push(
+      `${check.name}: ${check.url} 返回 ${response.statusCode}，预期 ${expectedStatuses.join('/')}`,
+    );
+  }
+  if (check.assertHeader) {
+    check.assertHeader(check, response);
+  }
+  if (check.assertBody && !check.assertBody(response.body)) {
+    failures.push(`${check.name}: ${check.bodyReason}`);
+  }
+  if (check.assertResponse) {
+    check.assertResponse(check, response);
+  }
+  if (
+    check.assertLocation &&
+    !check.assertLocation(String(response.headers.location || ''))
+  ) {
+    failures.push(
+      `${check.name}: Location 不符合预期，实际 ${response.headers.location || '-'}`,
+    );
+  }
+
+  console.log(
+    `[pingora-direct-live] ${check.name} ${response.statusCode} ${response.elapsedMs}ms`,
+  );
+  const result = {
+    name: check.name,
+    url: check.url,
+    statusCode: response.statusCode,
+    elapsedMs: response.elapsedMs,
+    gateway: response.headers['x-genarrative-gateway'] || '',
+    location: response.headers.location || '',
+    requestId,
+  };
+  if (check.evidenceHeaders) {
+    result.headers = pickEvidenceHeaders(response.headers);
+  }
+  Object.defineProperty(result, 'bodySample', {
+    value: response.body,
+    enumerable: false,
+  });
+  Object.defineProperty(result, 'rawHeaders', {
+    value: response.headers,
+    enumerable: false,
+  });
+  return result;
+}
+
+async function runDiscoveredStaticAssetCheck(rootResult, directRequestIds) {
+  const assetPaths = discoverStaticAssetPaths(rootResult);
+  const assetPath = findStaticAssetPath(assetPaths, { fingerprinted: false });
+  if (!assetPath) {
+    console.log('[pingora-direct-live] https-static-asset skipped');
+    return {
+      name: 'https-static-asset',
+      skipped: true,
+      reason:
+        rootResult?.statusCode === 200
+          ? 'root HTML 未发现 /assets 或 /admin/assets 引用'
+          : `root status=${rootResult?.statusCode ?? '-'}`,
+    };
+  }
+
+  const check = {
+    name: 'https-static-asset',
+    url: joinUrl(config.httpsBaseUrl, assetPath),
+    expectedStatus: 200,
+    assertHeader: assertPingoraGatewayHeader,
+    assertResponse: assertStaticAssetHeaders,
+    evidenceHeaders: true,
+  };
+  const result = await runCheck(check, directRequestIds);
+  const headResult = await runStaticAssetHeadCheck(assetPath, directRequestIds);
+  const rangeResult = await runStaticAssetRangeCheck(assetPath, directRequestIds);
+  const notModifiedResult = await runStaticAssetNotModifiedChecks(
+    assetPath,
+    result.rawHeaders,
+    directRequestIds,
+  );
+  const fingerprintedResult = await runFingerprintedStaticAssetCheck(
+    findStaticAssetPath(assetPaths, { fingerprinted: true }),
+    rootResult,
+    directRequestIds,
+  );
+  return {
+    ...result,
+    head: headResult,
+    range: rangeResult,
+    notModified: notModifiedResult,
+    fingerprinted: fingerprintedResult,
+  };
+}
+
+function discoverStaticAssetPaths(rootResult) {
+  if (!rootResult || rootResult.statusCode !== 200) {
+    return [];
+  }
+  const body = String(rootResult.bodySample || '');
+  const paths = [];
+  const pattern = /(?:src|href)=["']([^"']*\/(?:admin\/)?assets\/[^"']+)["']/giu;
+  for (const match of body.matchAll(pattern)) {
+    try {
+      const pathname = new URL(match[1], config.httpsBaseUrl).pathname;
+      if (!paths.includes(pathname)) {
+        paths.push(pathname);
+      }
+    } catch {
+      // 保留其他可解析的资产引用，避免单个异常 href 掩盖真实证据。
+    }
+  }
+  return paths;
+}
+
+function findStaticAssetPath(paths, options = {}) {
+  const except = options.except || '';
+  const candidates = paths.filter((item) => item && item !== except);
+  if (options.fingerprinted === true) {
+    return candidates.find(isFingerprintedStaticAssetPath) || '';
+  }
+  if (options.fingerprinted === false) {
+    return (
+      candidates.find((item) => !isFingerprintedStaticAssetPath(item)) ||
+      candidates[0] ||
+      ''
+    );
+  }
+  return candidates[0] || '';
+}
+
+function isFingerprintedStaticAssetPath(assetPath) {
+  const fileName = decodeURIComponent(assetPath.split('/').pop() || '');
+  return /-[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/u.test(fileName);
+}
+
+function assertStaticAssetHeaders(check, response) {
+  const cacheControl = String(response.headers['cache-control'] || '');
+  if (!cacheControl) {
+    failures.push(`${check.name}: 缺少 Cache-Control`);
+  }
+  if (response.headers['accept-ranges'] !== 'bytes') {
+    failures.push(
+      `${check.name}: 缺少 Accept-Ranges: bytes，实际 ${response.headers['accept-ranges'] || '-'}`,
+    );
+  }
+  if (!response.headers.etag) {
+    failures.push(`${check.name}: 缺少 ETag`);
+  }
+  if (!response.headers['last-modified']) {
+    failures.push(`${check.name}: 缺少 Last-Modified`);
+  }
+}
+
+function assertFingerprintedStaticAssetHeaders(check, response) {
+  assertStaticAssetHeaders(check, response);
+  const cacheControl = String(response.headers['cache-control'] || '');
+  if (cacheControl !== 'public, max-age=31536000, immutable') {
+    failures.push(
+      `${check.name}: Cache-Control 应为 public, max-age=31536000, immutable，实际 ${cacheControl || '-'}`,
+    );
+  }
+}
+
+async function runStaticAssetHeadCheck(assetPath, directRequestIds, options = {}) {
+  const check = {
+    name: options.name || 'https-static-asset-head',
+    method: 'HEAD',
+    url: joinUrl(config.httpsBaseUrl, assetPath),
+    expectedStatus: 200,
+    assertHeader: assertPingoraGatewayHeader,
+    assertResponse: options.assertResponse || assertStaticAssetHeadHeaders,
+    evidenceHeaders: true,
+  };
+  return runCheck(check, directRequestIds);
+}
+
+function assertStaticAssetHeadHeaders(check, response) {
+  assertStaticAssetHeaders(check, response);
+  if (response.body !== '') {
+    failures.push(`${check.name}: HEAD 响应不应包含 body`);
+  }
+  if (!response.headers['content-length']) {
+    failures.push(`${check.name}: 缺少 Content-Length`);
+  }
+}
+
+function assertFingerprintedStaticAssetHeadHeaders(check, response) {
+  assertFingerprintedStaticAssetHeaders(check, response);
+  if (response.body !== '') {
+    failures.push(`${check.name}: HEAD 响应不应包含 body`);
+  }
+  if (!response.headers['content-length']) {
+    failures.push(`${check.name}: 缺少 Content-Length`);
+  }
+}
+
+async function runFingerprintedStaticAssetCheck(
+  assetPath,
+  rootResult,
+  directRequestIds,
+) {
+  if (!assetPath) {
+    console.log('[pingora-direct-live] https-static-fingerprinted-asset skipped');
+    return {
+      name: 'https-static-fingerprinted-asset',
+      skipped: true,
+      reason:
+        rootResult?.statusCode === 200
+          ? 'root HTML 未发现 Vite 指纹 /assets 或 /admin/assets 引用'
+          : `root status=${rootResult?.statusCode ?? '-'}`,
+    };
+  }
+
+  const check = {
+    name: 'https-static-fingerprinted-asset',
+    url: joinUrl(config.httpsBaseUrl, assetPath),
+    expectedStatus: 200,
+    assertHeader: assertPingoraGatewayHeader,
+    assertResponse: assertFingerprintedStaticAssetHeaders,
+    evidenceHeaders: true,
+  };
+  const result = await runCheck(check, directRequestIds);
+  const headResult = await runStaticAssetHeadCheck(assetPath, directRequestIds, {
+    name: 'https-static-fingerprinted-asset-head',
+    assertResponse: assertFingerprintedStaticAssetHeadHeaders,
+  });
+  const rangeResult = await runStaticAssetRangeCheck(assetPath, directRequestIds, {
+    name: 'https-static-fingerprinted-asset-range',
+  });
+  const notModifiedResult = await runStaticAssetNotModifiedChecks(
+    assetPath,
+    result.rawHeaders,
+    directRequestIds,
+    {
+      etagName: 'https-static-fingerprinted-asset-etag-304',
+      lastModifiedName: 'https-static-fingerprinted-asset-last-modified-304',
+    },
+  );
+  return {
+    ...result,
+    head: headResult,
+    range: rangeResult,
+    notModified: notModifiedResult,
+  };
+}
+
+async function runStaticAssetRangeCheck(assetPath, directRequestIds, options = {}) {
+  const check = {
+    name: options.name || 'https-static-asset-range',
+    url: joinUrl(config.httpsBaseUrl, assetPath),
+    expectedStatus: 206,
+    headers: {
+      Range: 'bytes=0-0',
+      'Accept-Encoding': 'gzip',
+    },
+    assertHeader: assertPingoraGatewayHeader,
+    assertResponse: assertStaticAssetRangeHeaders,
+    evidenceHeaders: true,
+  };
+  return runCheck(check, directRequestIds);
+}
+
+async function runStaticAssetNotModifiedChecks(
+  assetPath,
+  sourceHeaders,
+  directRequestIds,
+  options = {},
+) {
+  const result = {};
+  if (sourceHeaders?.etag) {
+    result.etag = await runCheck(
+      {
+        name: options.etagName || 'https-static-asset-etag-304',
+        url: joinUrl(config.httpsBaseUrl, assetPath),
+        expectedStatus: 304,
+        headers: {
+          'If-None-Match': sourceHeaders.etag,
+          'Accept-Encoding': 'gzip',
+        },
+        sourceHeaders,
+        assertHeader: assertPingoraGatewayHeader,
+        assertResponse: assertStaticAssetNotModifiedHeaders,
+        evidenceHeaders: true,
+      },
+      directRequestIds,
+    );
+  }
+  if (sourceHeaders?.['last-modified']) {
+    result.lastModified = await runCheck(
+      {
+        name:
+          options.lastModifiedName ||
+          'https-static-asset-last-modified-304',
+        url: joinUrl(config.httpsBaseUrl, assetPath),
+        expectedStatus: 304,
+        headers: {
+          'If-Modified-Since': sourceHeaders['last-modified'],
+          'Accept-Encoding': 'gzip',
+        },
+        sourceHeaders,
+        assertHeader: assertPingoraGatewayHeader,
+        assertResponse: assertStaticAssetNotModifiedHeaders,
+        evidenceHeaders: true,
+      },
+      directRequestIds,
+    );
+  }
+  return result;
+}
+
+function assertStaticAssetNotModifiedHeaders(check, response) {
+  if (response.body !== '') {
+    failures.push(`${check.name}: 304 响应不应包含 body`);
+  }
+  if (response.headers['content-encoding']) {
+    failures.push(
+      `${check.name}: 304 响应不应压缩，实际 Content-Encoding=${response.headers['content-encoding']}`,
+    );
+  }
+  if (
+    check.sourceHeaders?.['cache-control'] &&
+    response.headers['cache-control'] !== check.sourceHeaders['cache-control']
+  ) {
+    failures.push(
+      `${check.name}: Cache-Control 与源响应不一致，实际 ${response.headers['cache-control'] || '-'}`,
+    );
+  }
+  if (
+    check.sourceHeaders?.etag &&
+    response.headers.etag &&
+    response.headers.etag !== check.sourceHeaders.etag
+  ) {
+    failures.push(`${check.name}: ETag 与源响应不一致`);
+  }
+  if (
+    check.sourceHeaders?.['last-modified'] &&
+    response.headers['last-modified'] &&
+    response.headers['last-modified'] !== check.sourceHeaders['last-modified']
+  ) {
+    failures.push(`${check.name}: Last-Modified 与源响应不一致`);
+  }
+}
+
+function pickEvidenceHeaders(headers) {
+  const allowlist = [
+    'cache-control',
+    'etag',
+    'last-modified',
+    'accept-ranges',
+    'content-range',
+    'content-length',
+    'content-encoding',
+  ];
+  const result = {};
+  for (const name of allowlist) {
+    if (headers[name] !== undefined) {
+      result[name] = String(headers[name]);
+    }
+  }
+  return result;
+}
+
+function assertStaticAssetRangeHeaders(check, response) {
+  if (response.headers['accept-ranges'] !== 'bytes') {
+    failures.push(
+      `${check.name}: 缺少 Accept-Ranges: bytes，实际 ${response.headers['accept-ranges'] || '-'}`,
+    );
+  }
+  if (!/^bytes 0-0\/\d+$/u.test(String(response.headers['content-range'] || ''))) {
+    failures.push(
+      `${check.name}: Content-Range 不符合 bytes 0-0/<len>，实际 ${response.headers['content-range'] || '-'}`,
+    );
+  }
+  if (String(response.headers['content-length'] || '') !== '1') {
+    failures.push(
+      `${check.name}: Content-Length 应为 1，实际 ${response.headers['content-length'] || '-'}`,
+    );
+  }
+  if (response.headers['content-encoding']) {
+    failures.push(
+      `${check.name}: Range 响应不应压缩，实际 Content-Encoding=${response.headers['content-encoding']}`,
+    );
+  }
+}
+
+function runHttp2AlpnCheck() {
+  const parsed = new URL(config.httpsBaseUrl);
+  const port = Number(parsed.port || 443);
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const socket = tls.connect({
+      host: parsed.hostname,
+      port,
+      servername: tlsServername(parsed),
+      ALPNProtocols: ['h2', 'http/1.1'],
+      rejectUnauthorized: !config.insecureTls,
+    });
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`HTTP/2 ALPN 握手超时: ${config.httpsBaseUrl}`));
+    }, config.timeoutMs);
+
+    socket.on('secureConnect', () => {
+      const elapsedMs = Date.now() - startedAt;
+      const protocol = socket.alpnProtocol || '';
+      clearTimeout(timeout);
+      socket.destroy();
+      if (protocol !== 'h2') {
+        failures.push(
+          `https-http2-alpn: ALPN 实际 ${protocol || '-'}，预期 h2`,
+        );
+      }
+      console.log(
+        `[pingora-direct-live] https-http2-alpn ${protocol || '-'} ${elapsedMs}ms`,
+      );
+      resolve({
+        name: 'https-http2-alpn',
+        url: config.httpsBaseUrl,
+        elapsedMs,
+        protocol,
+      });
+    });
+    socket.on('error', (error) => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+  });
+}
+
+async function runWssSubscribeCheck(directRequestIds) {
+  const path = `/v1/database/${config.spacetimeDatabase}/subscribe?compression=Brotli`;
+  const url = buildWebSocketUrl(config.httpsBaseUrl, path);
+  const requestId = makeDirectRequestId('wss-spacetime-subscribe');
+  const directRequest = {
+    requestId,
+    name: 'wss-spacetime-subscribe',
+    method: 'GET',
+    path: `/v1/database/${config.spacetimeDatabase}/subscribe`,
+    statusCode: null,
+  };
+  directRequestIds.push(directRequest);
+  const response = await websocketHandshake(url, {
+    expectedStatus: config.requireWssUpgrade
+      ? [101]
+      : [101, 401, 403, 404, 503],
+    requestId,
+  });
+  directRequest.statusCode = response.statusCode;
+
+  const gateway = response.headers['x-genarrative-gateway'] || '';
+  if (gateway !== 'pingora-shadow') {
+    failures.push(
+      `wss-spacetime-subscribe: 缺少 X-Genarrative-Gateway: pingora-shadow，实际 ${gateway || '-'}`,
+    );
+  }
+
+  console.log(
+    `[pingora-direct-live] wss-spacetime-subscribe ${response.statusCode} ${response.elapsedMs}ms`,
+  );
+  return {
+    name: 'wss-spacetime-subscribe',
+    url,
+    statusCode: response.statusCode,
+    elapsedMs: response.elapsedMs,
+    gateway: response.headers['x-genarrative-gateway'] || '',
+    requestId,
+  };
+}
+
+async function runDirectAccessLogCheck(directRequestIds) {
+  const deadline = Date.now() + config.timeoutMs;
+  let entries = [];
+  let matched = [];
+  let missing = directRequestIds;
+  let mismatched = [];
+
+  while (Date.now() <= deadline) {
+    const content = await readTailLines(
+      config.pingoraAccessLog,
+      config.accessLogSinceLines,
+    );
+    entries = content.split(/\r?\n/u).filter(Boolean).map(parseAccessLogLine);
+    ({ matched, missing, mismatched } = compareDirectAccessLogEntries(
+      directRequestIds,
+      entries,
+    ));
+    if (missing.length === 0 && mismatched.length === 0) {
+      break;
+    }
+    await sleep(100);
+  }
+
+  ({ matched, missing, mismatched } = compareDirectAccessLogEntries(
+    directRequestIds,
+    entries,
+  ));
+
+  if (missing.length > 0) {
+    failures.push(
+      `direct-access-log: 缺少 Pingora access log request_id=${missing
+        .map((item) => item.requestId)
+        .join(',')}`,
+    );
+  }
+  if (mismatched.length > 0) {
+    failures.push(
+      `direct-access-log: method/path/status 不一致 ${mismatched
+        .map(
+          (item) =>
+            `${item.requestId}: ${item.reasons.join(', ')}`,
+        )
+        .join('; ')}`,
+    );
+  }
+
+  console.log(
+    `[pingora-direct-live] direct-access-log checked=${directRequestIds.length} missing=${missing.length} mismatched=${mismatched.length}`,
+  );
+  return {
+    name: 'direct-access-log',
+    logFile: config.pingoraAccessLog,
+    sinceLines: config.accessLogSinceLines,
+    scannedLineCount: entries.length,
+    checked: directRequestIds.length,
+    matchedCount: matched.length,
+    missingCount: missing.length,
+    mismatchCount: mismatched.length,
+    matched,
+    missing,
+    mismatches: mismatched,
+  };
+}
+
+function compareDirectAccessLogEntries(directRequestIds, entries) {
+  const matched = [];
+  const missing = [];
+  const mismatched = [];
+
+  for (const expected of directRequestIds) {
+    const entry = entries.find((item) => item.request_id === expected.requestId);
+    if (!entry) {
+      missing.push(formatExpectedAccessLogEvidence(expected));
+      continue;
+    }
+    const actualStatus = parseAccessLogStatus(entry.status);
+    const actual = {
+      method: entry.method || '-',
+      path: entry.path || '-',
+      statusCode: actualStatus,
+      statusRaw: entry.status || '-',
+    };
+    const expectedEvidence = formatExpectedAccessLogEvidence(expected);
+    const reasons = [];
+    if (actual.method !== expected.method) {
+      reasons.push(`method expected=${expected.method} actual=${actual.method}`);
+    }
+    if (actual.path !== expected.path) {
+      reasons.push(`path expected=${expected.path} actual=${actual.path}`);
+    }
+    if (
+      expected.statusCode !== null &&
+      actual.statusCode !== expected.statusCode
+    ) {
+      reasons.push(
+        `status expected=${expected.statusCode} actual=${actual.statusRaw}`,
+      );
+    }
+    if (reasons.length > 0) {
+      mismatched.push({
+        ...expectedEvidence,
+        actualMethod: actual.method,
+        actualPath: actual.path,
+        actualStatusCode: actual.statusCode,
+        actualStatusRaw: actual.statusRaw,
+        reasons,
+      });
+      continue;
+    }
+    matched.push({
+      ...expectedEvidence,
+      actualMethod: actual.method,
+      actualPath: actual.path,
+      actualStatusCode: actual.statusCode,
+    });
+  }
+
+  return { matched, missing, mismatched };
+}
+
+function formatExpectedAccessLogEvidence(expected) {
+  return {
+    name: expected.name,
+    requestId: expected.requestId,
+    expectedMethod: expected.method,
+    expectedPath: expected.path,
+    expectedStatusCode: expected.statusCode,
+  };
+}
+
+function parseAccessLogStatus(value) {
+  const text = String(value ?? '').trim();
+  if (!/^\d{3}$/u.test(text)) {
+    return null;
+  }
+  return Number.parseInt(text, 10);
+}
+
+function assertPingoraGatewayHeader(check, response) {
+  const gateway = response.headers['x-genarrative-gateway'] || '';
+  if (gateway !== 'pingora-shadow') {
+    failures.push(
+      `${check.name}: 缺少 X-Genarrative-Gateway: pingora-shadow，实际 ${gateway || '-'}`,
+    );
+  }
+}
+
+function directHttpsLocation(httpsBaseUrl, path) {
+  if (config.redirectBaseUrl) {
+    return joinUrl(config.redirectBaseUrl, path);
+  }
+  if (!config.redirectHost) {
+    return joinUrl(httpsBaseUrl, path);
+  }
+  const parsed = new URL(httpsBaseUrl);
+  parsed.host = config.redirectHost;
+  return joinUrl(parsed.toString(), path);
+}
+
+function buildWebSocketUrl(baseUrl, path) {
+  const parsed = new URL(joinUrl(baseUrl, path));
+  parsed.protocol = parsed.protocol === 'https:' ? 'wss:' : 'ws:';
+  return parsed.toString();
+}
+
+function requestUrl(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const parsed = new URL(url);
+    const client = parsed.protocol === 'https:' ? https : http;
+    const method = options.method || 'GET';
+    const headers = {
+      'User-Agent': 'genarrative-pingora-direct-live/1.0',
+      Accept: 'application/json,text/plain,*/*',
+      Connection: 'close',
+      ...(options.headers || {}),
+    };
+    if (config.host) {
+      headers.Host = config.host;
+    }
+
+    const request = client.request(
+      parsed,
+      {
+        method,
+        timeout: config.timeoutMs,
+        headers,
+        servername: tlsServername(parsed),
+        rejectUnauthorized:
+          parsed.protocol === 'https:' && config.insecureTls
+            ? false
+            : undefined,
+      },
+      (response) => {
+        let body = '';
+        response.setEncoding('utf8');
+        response.on('data', (chunk) => {
+          if (body.length < 4096) {
+            body += chunk;
+          }
+        });
+        response.on('end', () => {
+          resolve({
+            elapsedMs: Date.now() - startedAt,
+            statusCode: response.statusCode || 0,
+            headers: response.headers,
+            body,
+          });
+        });
+      },
+    );
+
+    request.on('timeout', () => {
+      request.destroy(new Error(`请求超时: ${url}`));
+    });
+    request.on('error', reject);
+    request.end();
+  });
+}
+
+function websocketHandshake(url, options) {
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const parsed = new URL(url);
+    const secure = parsed.protocol === 'wss:';
+    const port = Number(parsed.port || (secure ? 443 : 80));
+    const key = randomBytes(16).toString('base64');
+    const headers = {
+      Host: config.host || parsed.host,
+      Upgrade: 'websocket',
+      Connection: 'Upgrade',
+      'Sec-WebSocket-Key': key,
+      'Sec-WebSocket-Version': '13',
+      'Sec-WebSocket-Protocol': SPACETIME_WEBSOCKET_PROTOCOL,
+      'User-Agent': 'genarrative-pingora-direct-live/1.0',
+      'X-Request-Id': options.requestId,
+    };
+
+    const socket = secure
+      ? tls.connect({
+          host: parsed.hostname,
+          port,
+          servername: tlsServername(parsed),
+          rejectUnauthorized: !config.insecureTls,
+        })
+      : net.connect({ host: parsed.hostname, port });
+
+    let raw = Buffer.alloc(0);
+    let settled = false;
+    const timeout = setTimeout(() => {
+      settled = true;
+      socket.destroy();
+      reject(new Error(`WebSocket 请求超时: ${url}`));
+    }, config.timeoutMs);
+
+    function settle(response) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      socket.destroy();
+      resolve(response);
+    }
+
+    socket.on(secure ? 'secureConnect' : 'connect', () => {
+      socket.write(buildWebSocketUpgradeRequest(parsed, headers));
+    });
+    socket.on('data', (chunk) => {
+      raw = Buffer.concat([raw, chunk]);
+      const parsedResponse = tryParseWebSocketHandshake(raw);
+      if (!parsedResponse) {
+        return;
+      }
+      parsedResponse.elapsedMs = Date.now() - startedAt;
+      if (!options.expectedStatus.includes(parsedResponse.statusCode)) {
+        failures.push(
+          `wss-spacetime-subscribe: ${url} 返回 ${parsedResponse.statusCode}，预期 ${options.expectedStatus.join('/')}`,
+        );
+      }
+      if (parsedResponse.statusCode === 101) {
+        assertWebSocketAccept(parsedResponse.headers, key, url);
+        assertSpacetimeWebSocketProtocol(parsedResponse.headers, url);
+      }
+      settle(parsedResponse);
+    });
+    socket.on('error', (error) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeout);
+        reject(error);
+      }
+    });
+    socket.on('close', () => {
+      if (!settled) {
+        const parsedResponse = tryParseWebSocketHandshake(raw);
+        if (parsedResponse) {
+          parsedResponse.elapsedMs = Date.now() - startedAt;
+          settle(parsedResponse);
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        reject(new Error(`WebSocket 响应提前关闭: ${url}`));
+      }
+    });
+  });
+}
+
+async function readTailLines(file, maxLines) {
+  const content = await readFile(file, 'utf8');
+  const lines = content.split(/\r?\n/u);
+  const tail = lines.slice(Math.max(0, lines.length - maxLines - 1));
+  return tail.join('\n');
+}
+
+function parseAccessLogLine(line) {
+  const fields = {};
+  for (const part of line.split('\t')) {
+    const separator = part.indexOf('=');
+    if (separator <= 0) {
+      continue;
+    }
+    fields[part.slice(0, separator)] = unescapeAccessLogValue(
+      part.slice(separator + 1),
+    );
+  }
+  return fields;
+}
+
+function unescapeAccessLogValue(value) {
+  return String(value)
+    .replaceAll('\\t', '\t')
+    .replaceAll('\\n', '\n')
+    .replaceAll('\\r', '\r')
+    .replaceAll('\\\\', '\\');
+}
+
+function makeDirectRequestId(name) {
+  const normalized = String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+    .slice(0, 48);
+  return `pingora-direct-${normalized}-${randomBytes(6).toString('hex')}`;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function tlsServername(parsedUrl) {
+  const servername = config.host
+    ? stripPort(config.host)
+    : stripPort(parsedUrl.hostname);
+  return net.isIP(servername) ? undefined : servername;
+}
+
+function stripPort(host) {
+  if (host.startsWith('[')) {
+    const end = host.indexOf(']');
+    return end > 0 ? host.slice(1, end) : host;
+  }
+  return host.split(':')[0] || host;
+}
+
+function buildWebSocketUpgradeRequest(parsed, headers) {
+  const path = `${parsed.pathname}${parsed.search}`;
+  const lines = [
+    `GET ${path} HTTP/1.1`,
+    ...Object.entries(headers).map(([name, value]) => `${name}: ${value}`),
+    '',
+    '',
+  ];
+  return lines.join('\r\n');
+}
+
+function tryParseWebSocketHandshake(raw) {
+  const headerEnd = raw.indexOf('\r\n\r\n');
+  if (headerEnd < 0) {
+    return null;
+  }
+  const headerText = raw.slice(0, headerEnd).toString('latin1');
+  const [statusLine, ...headerLines] = headerText.split('\r\n');
+  const statusCode = Number.parseInt(statusLine.split(' ')[1] || '0', 10);
+  const headers = {};
+  for (const line of headerLines) {
+    const separator = line.indexOf(':');
+    if (separator <= 0) {
+      continue;
+    }
+    headers[line.slice(0, separator).trim().toLowerCase()] = line
+      .slice(separator + 1)
+      .trim();
+  }
+  return {
+    elapsedMs: 0,
+    statusCode,
+    headers,
+    body: raw.slice(headerEnd + 4),
+  };
+}
+
+function assertWebSocketAccept(headers, key, url) {
+  const expectedAccept = createHash('sha1')
+    .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+    .digest('base64');
+  const actualAccept = headers['sec-websocket-accept'] || '';
+  if (actualAccept !== expectedAccept) {
+    failures.push(
+      `wss-spacetime-subscribe: ${url} Sec-WebSocket-Accept 不符合预期`,
+    );
+  }
+  if (!hasToken(headers.upgrade, 'websocket')) {
+    failures.push(`wss-spacetime-subscribe: ${url} 缺少 Upgrade: websocket`);
+  }
+}
+
+function assertSpacetimeWebSocketProtocol(headers, url) {
+  const actual = headers['sec-websocket-protocol'] || '';
+  if (actual !== SPACETIME_WEBSOCKET_PROTOCOL) {
+    failures.push(
+      `wss-spacetime-subscribe: ${url} Sec-WebSocket-Protocol 实际 ${actual || '-'}，预期 ${SPACETIME_WEBSOCKET_PROTOCOL}`,
+    );
+  }
+}
+
+function hasToken(value, expected) {
+  if (!value) {
+    return false;
+  }
+  const normalized = expected.toLowerCase();
+  return String(value)
+    .split(',')
+    .map((token) => token.trim().toLowerCase())
+    .includes(normalized);
+}
diff --git a/scripts/check-pingora-direct-preflight-guard.mjs b/scripts/check-pingora-direct-preflight-guard.mjs
new file mode 100644
index 000000000..d0e4f1014
--- /dev/null
+++ b/scripts/check-pingora-direct-preflight-guard.mjs
@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const PREFLIGHT_SCRIPT = 'scripts/check-pingora-direct-preflight.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-direct-preflight-guard-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-direct-preflight-guard] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-direct-preflight-guard] OK');
+
+function main() {
+  assertRejectsEnvFileWithControlCharacters();
+  assertRejectsSystemdServiceWithControlCharactersBeforeSystemctl();
+}
+
+function assertRejectsEnvFileWithControlCharacters() {
+  const fixture = prepareFixture('env-file-control-character');
+  const result = runPreflight(fixture, [
+    '--env-file',
+    `${path.join(fixture.root, 'pingora-gateway.env')}\n--fake-flag`,
+    '--require-live-env',
+  ]);
+
+  assertNonZero(result, 'direct preflight 必须拒绝带换行的 --env-file。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--env-file 不能包含换行或 NUL 字符',
+    '带换行的 --env-file 必须给出明确错误。',
+  );
+}
+
+function assertRejectsSystemdServiceWithControlCharactersBeforeSystemctl() {
+  const fixture = prepareFixture('systemd-service-control-character');
+  const result = runPreflight(fixture, [
+    '--systemd-cat',
+    '--systemd-service',
+    'genarrative-pingora-gateway.service\n--fake-flag',
+  ]);
+
+  assertNonZero(
+    result,
+    'direct preflight 必须拒绝带换行的 systemd service 参数。',
+  );
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '子命令参数 不能包含换行或 NUL 字符',
+    '带换行的 systemd service 参数必须在执行 systemctl 前失败。',
+  );
+
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  if (commandsLog.includes('systemctl')) {
+    failures.push('systemd service 含控制字符时必须在执行 systemctl 前失败。');
+  }
+}
+
+function prepareFixture(name) {
+  const root = path.join(tmpRoot, name);
+  const fakeBin = path.join(root, 'bin');
+  const commandsLog = path.join(root, 'commands.log');
+  mkdirSync(fakeBin, { recursive: true });
+  writeFileSync(commandsLog, '', 'utf8');
+  writeFileSync(
+    path.join(fakeBin, 'systemctl'),
+    [
+      '#!/usr/bin/env bash',
+      `printf 'systemctl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      'cat <<SYSTEMD',
+      '# /etc/systemd/system/genarrative-pingora-gateway.service',
+      '[Service]',
+      'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+      'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+      'SYSTEMD',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodSync(path.join(fakeBin, 'systemctl'), 0o755);
+  return { root, fakeBin, commandsLog };
+}
+
+function runPreflight(fixture, args) {
+  return spawnSync('node', ['--', PREFLIGHT_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PATH: `${fixture.fakeBin}:${process.env.PATH || ''}`,
+    },
+  });
+}
+
+function assertNonZero(result, reason) {
+  if ((result.status ?? 0) === 0) {
+    failures.push(
+      `${reason}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(value, expected, reason) {
+  if (!String(value).includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
diff --git a/scripts/check-pingora-direct-preflight.mjs b/scripts/check-pingora-direct-preflight.mjs
new file mode 100644
index 000000000..67ddf2747
--- /dev/null
+++ b/scripts/check-pingora-direct-preflight.mjs
@@ -0,0 +1,901 @@
+#!/usr/bin/env node
+
+import { accessSync, constants, readFileSync } from 'node:fs';
+import net from 'node:net';
+import { spawnSync } from 'node:child_process';
+import { userInfo } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(SCRIPT_DIR, '..');
+const DEFAULT_SERVICE_UNIT = path.join(
+  REPO_ROOT,
+  'deploy/systemd/genarrative-pingora-gateway.service',
+);
+const DEFAULT_DROPIN_TEMPLATE = path.join(
+  REPO_ROOT,
+  'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+);
+const DEFAULT_ENV_EXAMPLE = path.join(
+  REPO_ROOT,
+  'deploy/pingora/pingora-gateway.env.example',
+);
+const DEFAULT_SYSTEMD_SERVICE = 'genarrative-pingora-gateway.service';
+const DEFAULT_SERVICE_USER = 'genarrative';
+
+const config = parseArgs(process.argv.slice(2));
+const failures = [];
+const warnings = [];
+
+await main();
+
+if (warnings.length > 0) {
+  for (const warning of warnings) {
+    console.warn(`[pingora-direct-preflight] WARNING ${warning}`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error('[pingora-direct-preflight] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[pingora-direct-preflight] OK');
+
+function usage() {
+  console.log(`Usage:
+  node scripts/check-pingora-direct-preflight.mjs [options]
+
+默认只检查仓库内模板，适合本机提交前护栏。
+
+Options:
+  --env-file <path>       目标机 /etc/genarrative/pingora-gateway.env。
+  --require-live-env      强制 env 文件包含 TLS_LISTEN / HTTP_REDIRECT_LISTEN / cert / key。
+  --check-cert-readable   检查 env 中 cert/key 文件当前用户可读；目标机切换窗口建议启用。
+  --check-service-env-file
+                           检查 service EnvironmentFile 包含本次 --env-file。
+  --check-service-user-cert-readable
+                           检查 systemd 服务用户可读 env 中 cert/key；目标机切换窗口必须启用。
+  --check-service-binary-executable
+                           检查 service ExecStart 指向的 pingora-gateway 已存在且可执行。
+  --check-ports-free      检查 env 中 TLS_LISTEN / HTTP_REDIRECT_LISTEN 端口当前可绑定。
+  --allow-loopback-only   只允许直连入口监听 127.0.0.1 / ::1；本机高端口 smoke 可用。
+  --systemd-cat           调用 systemctl cat 检查已生效 service。
+  --systemd-service <name>
+                           systemd service 名，默认 genarrative-pingora-gateway.service。
+  --service-user <name>   检查 cert/key 可读性时使用的 systemd 服务用户；默认从 service 模板 User= 推导。
+  --service-unit <path>   仓库内主 service 模板路径。
+  --dropin-template <path>
+                           仓库内 direct-entry drop-in 模板路径。
+  --env-example <path>    仓库内 env 示例路径。
+  --json                  输出 JSON 结果。
+
+Environment aliases:
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_REQUIRE_LIVE_ENV
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SERVICE_USER
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE
+  GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT
+`);
+}
+
+function parseArgs(argv) {
+  const result = {
+    envFile: process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE || '',
+    requireLiveEnv: parseBoolEnv(
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_REQUIRE_LIVE_ENV,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_REQUIRE_LIVE_ENV',
+    ),
+    checkCertReadable: parseBoolEnv(
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE',
+    ),
+    checkServiceEnvFile: parseBoolEnv(
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE',
+    ),
+    checkServiceUserCertReadable: parseBoolEnv(
+      process.env
+        .GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE',
+    ),
+    checkServiceBinaryExecutable: parseBoolEnv(
+      process.env
+        .GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE',
+    ),
+    serviceUser:
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SERVICE_USER || '',
+    checkPortsFree: parseBoolEnv(
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE',
+    ),
+    systemdCat: parseBoolEnv(
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT,
+      false,
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT',
+    ),
+    allowLoopbackOnly: false,
+    systemdService: DEFAULT_SYSTEMD_SERVICE,
+    serviceUnit: DEFAULT_SERVICE_UNIT,
+    dropinTemplate: DEFAULT_DROPIN_TEMPLATE,
+    envExample: DEFAULT_ENV_EXAMPLE,
+    json: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        usage();
+        process.exit(0);
+        break;
+      case '--env-file':
+        result.envFile = requireValue(argv, ++index, arg);
+        break;
+      case '--require-live-env':
+        result.requireLiveEnv = true;
+        break;
+      case '--check-cert-readable':
+        result.checkCertReadable = true;
+        break;
+      case '--check-service-env-file':
+        result.checkServiceEnvFile = true;
+        break;
+      case '--check-service-user-cert-readable':
+        result.checkServiceUserCertReadable = true;
+        break;
+      case '--check-service-binary-executable':
+        result.checkServiceBinaryExecutable = true;
+        break;
+      case '--check-ports-free':
+        result.checkPortsFree = true;
+        break;
+      case '--allow-loopback-only':
+        result.allowLoopbackOnly = true;
+        break;
+      case '--systemd-cat':
+        result.systemdCat = true;
+        break;
+      case '--systemd-service':
+        result.systemdService = requireValue(argv, ++index, arg);
+        break;
+      case '--service-user':
+        result.serviceUser = requireValue(argv, ++index, arg);
+        break;
+      case '--service-unit':
+        result.serviceUnit = requireValue(argv, ++index, arg);
+        break;
+      case '--dropin-template':
+        result.dropinTemplate = requireValue(argv, ++index, arg);
+        break;
+      case '--env-example':
+        result.envExample = requireValue(argv, ++index, arg);
+        break;
+      case '--json':
+        result.json = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (
+    (result.requireLiveEnv ||
+      result.checkCertReadable ||
+      result.checkServiceEnvFile ||
+      result.checkServiceUserCertReadable ||
+      result.checkPortsFree) &&
+    !result.envFile
+  ) {
+    throw new Error(
+      '--require-live-env / --check-cert-readable / --check-service-env-file / --check-service-user-cert-readable / --check-ports-free 需要同时提供 --env-file',
+    );
+  }
+  if (result.envFile) {
+    validateSafeAbsoluteFilePath(result.envFile, '--env-file');
+  }
+
+  return result;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function parseBoolEnv(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  const normalized = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${label} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function validateSafeAbsoluteFilePath(value, flag) {
+  validateNoControlCharacters(value, flag);
+  if (!path.isAbsolute(value)) {
+    throw new Error(`${flag} 必须是绝对路径。`);
+  }
+  if (isFilesystemRootPath(value)) {
+    throw new Error(`${flag} 不能是文件系统根目录。`);
+  }
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+async function main() {
+  const serviceTemplate = readFile(config.serviceUnit);
+  const dropinTemplate = readFile(config.dropinTemplate);
+  const envExample = readFile(config.envExample);
+  if (!config.serviceUser) {
+    config.serviceUser = resolveServiceUser(serviceTemplate);
+  }
+
+  assertTemplateShape(serviceTemplate, dropinTemplate, envExample);
+  if (config.checkServiceEnvFile) {
+    assertServiceEnvFile(serviceTemplate, config.serviceUnit);
+  }
+  if (config.checkServiceBinaryExecutable) {
+    assertServiceBinaryExecutable(serviceTemplate);
+  }
+
+  let env = new Map();
+  if (config.envFile) {
+    env = parseEnvFile(config.envFile);
+    await assertLiveEnv(env);
+  } else if (config.requireLiveEnv) {
+    failures.push('缺少 --env-file，无法验证目标机直连 env。');
+  }
+
+  if (config.systemdCat) {
+    const systemdCatContent = assertSystemdCat();
+    if (config.checkServiceEnvFile && systemdCatContent) {
+      assertServiceEnvFile(
+        systemdCatContent,
+        `systemctl cat ${config.systemdService}`,
+      );
+    }
+  }
+
+  if (config.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: failures.length === 0,
+          warnings,
+          envFile: config.envFile,
+          tlsListen: env.get('GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN') || '',
+          httpRedirectListen:
+            env.get('GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN') || '',
+          systemdCat: config.systemdCat,
+          checkServiceEnvFile: config.checkServiceEnvFile,
+          checkServiceUserCertReadable: config.checkServiceUserCertReadable,
+          checkServiceBinaryExecutable: config.checkServiceBinaryExecutable,
+          serviceUser: config.serviceUser,
+        },
+        null,
+        2,
+      ),
+    );
+  }
+}
+
+function readFile(file) {
+  try {
+    return readFileSync(file, 'utf8');
+  } catch (error) {
+    failures.push(`无法读取 ${file}: ${error.message}`);
+    return '';
+  }
+}
+
+function assertTemplateShape(serviceTemplate, dropinTemplate, envExample) {
+  assertIncludes(
+    config.serviceUnit,
+    serviceTemplate,
+    '影子网关只监听本机高端口',
+    '主 service 必须保留 shadow 说明。',
+  );
+  assertExcludes(
+    config.serviceUnit,
+    serviceTemplate,
+    'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    '主 service 不能默认授予低端口 capability。',
+  );
+  assertIncludes(
+    config.dropinTemplate,
+    dropinTemplate,
+    'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    'direct-entry drop-in 必须授予低端口绑定 capability。',
+  );
+  assertIncludes(
+    config.dropinTemplate,
+    dropinTemplate,
+    'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+    'direct-entry drop-in 必须限制 capability 边界。',
+  );
+  assertIncludes(
+    config.dropinTemplate,
+    dropinTemplate,
+    '/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf',
+    'direct-entry drop-in 必须写明人工启用位置。',
+  );
+  assertIncludes(
+    config.envExample,
+    envExample,
+    'CAP_NET_BIND_SERVICE',
+    'env 示例必须提示低端口需要 systemd drop-in。',
+  );
+}
+
+function assertIncludes(file, content, needle, reason) {
+  if (!content.includes(needle)) {
+    failures.push(`${file} 缺少 ${needle}。${reason}`);
+  }
+}
+
+function assertExcludes(file, content, needle, reason) {
+  if (content.includes(needle)) {
+    failures.push(`${file} 不应包含 ${needle}。${reason}`);
+  }
+}
+
+function parseEnvFile(file) {
+  const content = readFile(file);
+  const env = new Map();
+  for (const rawLine of content.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    const separator = line.indexOf('=');
+    if (separator <= 0) {
+      continue;
+    }
+    const key = line.slice(0, separator).trim();
+    const value = unquoteEnvValue(line.slice(separator + 1).trim());
+    env.set(key, value);
+  }
+  return env;
+}
+
+function unquoteEnvValue(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+async function assertLiveEnv(env) {
+  const tlsListen = requireEnv(env, 'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN');
+  const httpListen = requireEnv(
+    env,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+  );
+  const certFile = requireEnv(env, 'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE');
+  const keyFile = requireEnv(env, 'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE');
+  const proto = requireEnv(env, 'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO');
+
+  validateEnvValueNoControlCharacters(
+    tlsListen,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN',
+  );
+  validateEnvValueNoControlCharacters(
+    httpListen,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+  );
+  validateEnvValueNoControlCharacters(
+    certFile,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE',
+  );
+  validateEnvValueNoControlCharacters(
+    keyFile,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE',
+  );
+  validateEnvValueNoControlCharacters(
+    proto,
+    'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO',
+  );
+
+  if (proto && proto !== 'https') {
+    failures.push(
+      `GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO 应为 https，实际 ${proto}`,
+    );
+  }
+
+  const tlsEndpoint = parseListenAddress(
+    tlsListen,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN',
+  );
+  const httpEndpoint = parseListenAddress(
+    httpListen,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+  );
+
+  if (
+    tlsEndpoint &&
+    httpEndpoint &&
+    endpointsEqual(tlsEndpoint, httpEndpoint)
+  ) {
+    failures.push('TLS_LISTEN 和 HTTP_REDIRECT_LISTEN 不能复用同一监听地址。');
+  }
+
+  assertForwardedForTrust(env, [tlsEndpoint, httpEndpoint].filter(Boolean));
+
+  if (config.allowLoopbackOnly) {
+    for (const endpoint of [tlsEndpoint, httpEndpoint].filter(Boolean)) {
+      if (!isLoopbackHost(endpoint.host)) {
+        failures.push(
+          `${endpoint.label}=${endpoint.raw} 不是 loopback 地址；--allow-loopback-only 下不允许。`,
+        );
+      }
+    }
+  }
+
+  if (config.checkCertReadable) {
+    assertReadableFile(certFile, 'TLS_CERT_FILE');
+    assertReadableFile(keyFile, 'TLS_KEY_FILE');
+  }
+
+  if (config.checkServiceUserCertReadable) {
+    assertReadableFileAsServiceUser(certFile, 'TLS_CERT_FILE');
+    assertReadableFileAsServiceUser(keyFile, 'TLS_KEY_FILE');
+  }
+
+  if (config.checkPortsFree) {
+    for (const endpoint of [tlsEndpoint, httpEndpoint].filter(Boolean)) {
+      await assertPortBindable(endpoint);
+    }
+  }
+
+  assertProtectionInstanceBoundary(env);
+}
+
+function requireEnv(env, key) {
+  const value = env.get(key) || '';
+  if (!value && config.requireLiveEnv) {
+    failures.push(`${config.envFile} 缺少 ${key}`);
+  }
+  return value;
+}
+
+function validateEnvValueNoControlCharacters(value, label) {
+  if (!value) {
+    return;
+  }
+  try {
+    validateNoControlCharacters(value, label);
+  } catch (error) {
+    failures.push(error.message);
+  }
+}
+
+function assertForwardedForTrust(env, endpoints) {
+  const trustForwardedFor = parseBoolValue(
+    env.get('GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR'),
+    'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR',
+  );
+  if (!trustForwardedFor) {
+    return;
+  }
+
+  const confirmed = parseBoolValue(
+    env.get('GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED'),
+    'GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED',
+  );
+  if (!confirmed) {
+    failures.push(
+      'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true 时必须同时设置 GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true。',
+    );
+  }
+
+  const publicEndpoints = endpoints.filter(
+    (endpoint) => !isLoopbackHost(endpoint.host),
+  );
+  if (publicEndpoints.length > 0) {
+    failures.push(
+      `公网直连 Pingora 时 GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR 必须保持 false，当前监听 ${publicEndpoints.map((endpoint) => `${endpoint.label}=${endpoint.raw}`).join(', ')}。`,
+    );
+  }
+}
+
+function assertProtectionInstanceBoundary(env) {
+  const protectionEnabled = parseBoolValue(
+    env.get('GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED'),
+    'GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED',
+    true,
+  );
+  const instanceCount = parseOptionalPositiveIntValue(
+    env.get('GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT'),
+    1,
+    'GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT',
+  );
+  const sharedProtectionConfirmed = parseBoolValue(
+    env.get('GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED'),
+    'GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED',
+  );
+
+  if (
+    protectionEnabled &&
+    instanceCount > 1 &&
+    !sharedProtectionConfirmed
+  ) {
+    failures.push(
+      'Pingora 接流保护当前默认是进程内状态；GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1 且 PROTECTION_ENABLED=true 时，必须设置 GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true，或关闭网关保护并由前置层承担。',
+    );
+  }
+}
+
+function parseBoolValue(raw, label, fallback = false) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  const normalized = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  failures.push(`${label} 必须是布尔值 true/false 或 1/0。`);
+  return fallback;
+}
+
+function parseOptionalPositiveIntValue(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  const text = String(raw).trim();
+  if (!/^[1-9]\d*$/u.test(text)) {
+    failures.push(`${label} 必须是正整数。`);
+    return fallback;
+  }
+  return Number.parseInt(text, 10);
+}
+
+function parseListenAddress(raw, label) {
+  if (!raw) {
+    return null;
+  }
+  const lastColon = raw.lastIndexOf(':');
+  if (lastColon <= 0 || lastColon === raw.length - 1) {
+    failures.push(`${label}=${raw} 不是 host:port 格式。`);
+    return null;
+  }
+
+  let host = raw.slice(0, lastColon);
+  const port = Number.parseInt(raw.slice(lastColon + 1), 10);
+  if (host.startsWith('[') && host.endsWith(']')) {
+    host = host.slice(1, -1);
+  }
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+    failures.push(`${label}=${raw} 端口无效。`);
+    return null;
+  }
+
+  return { label, raw, host, port };
+}
+
+function endpointsEqual(left, right) {
+  return left.host === right.host && left.port === right.port;
+}
+
+function isLoopbackHost(host) {
+  return ['127.0.0.1', '::1', 'localhost'].includes(host);
+}
+
+function assertReadableFile(file, label) {
+  if (!file) {
+    return;
+  }
+  try {
+    accessSync(file, constants.R_OK);
+  } catch (error) {
+    failures.push(`${label} 当前用户不可读: ${file} (${error.message})`);
+  }
+}
+
+function assertExecutableFile(file, label) {
+  if (!file) {
+    return;
+  }
+  try {
+    accessSync(file, constants.X_OK);
+  } catch (error) {
+    failures.push(`${label} 不存在或不可执行: ${file} (${error.message})`);
+  }
+}
+
+function assertReadableFileAsServiceUser(file, label) {
+  if (!file) {
+    return;
+  }
+  const user = config.serviceUser || DEFAULT_SERVICE_USER;
+  try {
+    validateNoControlCharacters(user, '--service-user');
+    validateNoControlCharacters(file, label);
+  } catch (error) {
+    failures.push(error.message);
+    return;
+  }
+  const currentUser = currentUsername();
+  if (currentUser === user) {
+    assertReadableFile(file, `${label} 服务用户 ${user}`);
+    return;
+  }
+  const result = runCommand('sudo', ['-n', '-u', user, 'test', '-r', file]);
+  if (result.controlCharacterError) {
+    failures.push(result.controlCharacterError);
+    return;
+  }
+  if (result.error) {
+    failures.push(
+      `${label} 无法以服务用户 ${user} 检查可读性: ${result.error.message}；请在目标机安装 sudo，或以 ${user} 用户运行 preflight。`,
+    );
+    return;
+  }
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || '').trim();
+    failures.push(
+      `${label} 服务用户 ${user} 不可读: ${file}${detail ? ` (${detail})` : ''}`,
+    );
+  }
+}
+
+function runCommand(command, args) {
+  try {
+    validateNoControlCharacters(command, '子命令可执行文件');
+    for (const arg of args) {
+      validateNoControlCharacters(arg, '子命令参数');
+    }
+  } catch (error) {
+    return {
+      status: 1,
+      stdout: '',
+      stderr: '',
+      error: null,
+      controlCharacterError: error.message,
+    };
+  }
+  return spawnSync(command, args, {
+    encoding: 'utf8',
+  });
+}
+
+function assertServiceEnvFile(serviceTemplate, sourceLabel) {
+  const envFiles = resolveServiceEnvFiles(serviceTemplate);
+  const expected = path.resolve(config.envFile);
+  if (envFiles.length === 0) {
+    failures.push(
+      `${sourceLabel} 缺少 EnvironmentFile，无法确认 service 会读取本次 preflight env。`,
+    );
+    return;
+  }
+  if (!envFiles.some((envFile) => path.resolve(envFile) === expected)) {
+    failures.push(
+      `${sourceLabel} EnvironmentFile 未包含本次 --env-file: ${config.envFile}；实际 ${envFiles.join(', ')}`,
+    );
+  }
+}
+
+function resolveServiceEnvFiles(serviceTemplate) {
+  const envFiles = [];
+  for (const rawLine of serviceTemplate.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (!line.startsWith('EnvironmentFile=')) {
+      continue;
+    }
+    const rawValue = line.slice('EnvironmentFile='.length).trim();
+    if (!rawValue) {
+      envFiles.length = 0;
+      continue;
+    }
+    for (const word of splitSystemdWords(rawValue)) {
+      const value = word.startsWith('-') ? word.slice(1).trim() : word;
+      if (value) {
+        envFiles.push(value);
+      }
+    }
+  }
+  return envFiles;
+}
+
+function splitSystemdWords(value) {
+  const words = [];
+  let current = '';
+  let quote = '';
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (quote) {
+      if (char === quote) {
+        quote = '';
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/u.test(char)) {
+      if (current) {
+        words.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (current) {
+    words.push(current);
+  }
+  return words;
+}
+
+function resolveServiceUser(serviceTemplate) {
+  const userLine = serviceTemplate
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .find((line) => line.startsWith('User='));
+  if (!userLine) {
+    return DEFAULT_SERVICE_USER;
+  }
+  const user = userLine.slice('User='.length).trim();
+  return user || DEFAULT_SERVICE_USER;
+}
+
+function assertServiceBinaryExecutable(serviceTemplate) {
+  const execStart = resolveServiceExecStart(serviceTemplate);
+  if (!execStart) {
+    failures.push(`${config.serviceUnit} 缺少 ExecStart，无法检查网关二进制。`);
+    return;
+  }
+  const binaryPath = firstExecWord(execStart);
+  if (!binaryPath || !path.isAbsolute(binaryPath)) {
+    failures.push(
+      `${config.serviceUnit} ExecStart 不是绝对可执行文件路径: ${execStart}`,
+    );
+    return;
+  }
+  assertExecutableFile(binaryPath, 'Pingora service ExecStart');
+}
+
+function resolveServiceExecStart(serviceTemplate) {
+  const execLine = serviceTemplate
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .find((line) => line.startsWith('ExecStart='));
+  if (!execLine) {
+    return '';
+  }
+  return execLine.slice('ExecStart='.length).trim();
+}
+
+function firstExecWord(execStart) {
+  const trimmed = execStart.trim();
+  if (!trimmed) {
+    return '';
+  }
+  if (trimmed.startsWith('"')) {
+    const closingQuote = trimmed.indexOf('"', 1);
+    return closingQuote > 1 ? trimmed.slice(1, closingQuote) : '';
+  }
+  return trimmed.split(/\s+/u)[0] || '';
+}
+
+function currentUsername() {
+  if (process.env.USER || process.env.LOGNAME) {
+    return process.env.USER || process.env.LOGNAME;
+  }
+  try {
+    return userInfo().username;
+  } catch {
+    return '';
+  }
+}
+
+function assertPortBindable(endpoint) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    let settled = false;
+
+    function finish(error) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (error) {
+        failures.push(
+          `${endpoint.label}=${endpoint.raw} 当前不可绑定: ${error.message}`,
+        );
+        resolve();
+      } else {
+        console.log(
+          `[pingora-direct-preflight] ${endpoint.label}=${endpoint.raw} 当前端口可绑定`,
+        );
+        server.close(() => resolve());
+      }
+    }
+
+    server.once('error', finish);
+    server.listen(
+      {
+        host: endpoint.host,
+        port: endpoint.port,
+        exclusive: true,
+      },
+      () => finish(null),
+    );
+  });
+}
+
+function assertSystemdCat() {
+  const result = runCommand('systemctl', ['cat', config.systemdService]);
+  if (result.controlCharacterError) {
+    failures.push(result.controlCharacterError);
+    return '';
+  }
+  if (result.error) {
+    failures.push(`systemctl cat 启动失败: ${result.error.message}`);
+    return '';
+  }
+  if (result.status !== 0) {
+    failures.push(
+      `systemctl cat ${config.systemdService} 失败: ${(result.stderr || result.stdout || '').trim()}`,
+    );
+    return '';
+  }
+
+  const content = result.stdout || '';
+  assertIncludes(
+    `systemctl cat ${config.systemdService}`,
+    content,
+    'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    '目标机直连低端口前必须启用 direct-entry drop-in。',
+  );
+  assertIncludes(
+    `systemctl cat ${config.systemdService}`,
+    content,
+    'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+    '目标机 direct-entry drop-in 必须限制 capability 边界。',
+  );
+  return content;
+}
diff --git a/scripts/check-pingora-direct-rehearsal-status.mjs b/scripts/check-pingora-direct-rehearsal-status.mjs
new file mode 100644
index 000000000..0df53ed12
--- /dev/null
+++ b/scripts/check-pingora-direct-rehearsal-status.mjs
@@ -0,0 +1,568 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  chmodSync,
+  copyFileSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const STATUS_SCRIPT = 'scripts/ops/pingora-direct-rehearsal-status.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-direct-rehearsal-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-direct-rehearsal-status] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-direct-rehearsal-status] OK');
+
+function main() {
+  assertScriptShape();
+  assertNginxPublicRealpathRehearsalPasses();
+  assertFailsWhenPublicPortsAlreadyOwnedByPingora();
+  assertFailsWhenRealpathCanaryMissing();
+  assertRejectsUnsafeArgs();
+  assertRejectsInvalidBoolEnv();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(STATUS_SCRIPT, 'utf8');
+  assertIncludes(
+    content,
+    '该脚本只读采集',
+    'rehearsal 状态脚本 usage 必须说明只读边界。',
+  );
+  assertIncludes(
+    content,
+    'systemctl',
+    'rehearsal 状态脚本必须读取 systemd 状态。',
+  );
+  assertIncludes(
+    content,
+    'ss',
+    'rehearsal 状态脚本必须读取端口监听状态。',
+  );
+  assertIncludes(
+    content,
+    'pingora-current-release-audit.mjs',
+    'rehearsal 状态脚本必须复用 current release 自审。',
+  );
+  if (
+    content.includes('writeFile') ||
+    content.includes('rmSync(') ||
+    content.includes('systemctl reload') ||
+    content.includes('daemon-reload')
+  ) {
+    failures.push('rehearsal 状态脚本不应写文件、删除文件或 reload systemd。');
+  }
+}
+
+function assertNginxPublicRealpathRehearsalPasses() {
+  const fixture = prepareFixture('nginx-public-realpath', {
+    ssMode: 'nginx-public-realpath',
+  });
+  const result = runStatus(fixture, [
+    '--expect-public-gateway',
+    'nginx',
+    '--require-realpath-canary',
+    '--require-pingora-shadow',
+    '--require-current-release-gateway',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 0, 'Nginx 接公网 + Pingora shadow + realpath canary 应通过。');
+  if (result.status !== 0) {
+    return;
+  }
+  const payload = parseJson(result.stdout, 'rehearsal 状态输出');
+  assertEqual(payload.summary.status, 'OK', 'rehearsal summary 应为 OK。');
+  assertEqual(
+    payload.publicBoundary.status,
+    'OK',
+    'Nginx 接公网时 public boundary 应通过。',
+  );
+  assertEqual(
+    payload.ports.byPort['80'].hasNginx,
+    true,
+    '80 端口必须识别为 Nginx。',
+  );
+  assertEqual(
+    payload.ports.byPort['443'].hasNginx,
+    true,
+    '443 端口必须识别为 Nginx。',
+  );
+  assertEqual(
+    payload.ports.byPort['18081'].hasPingora,
+    true,
+    '18081 必须识别为 Pingora shadow。',
+  );
+  assertEqual(
+    payload.ports.byPort['18083'].hasNginx,
+    true,
+    '18083 必须识别为 Nginx realpath canary。',
+  );
+  assertEqual(
+    payload.realpathCanary.templateLooksValid,
+    true,
+    'realpath canary 配置必须通过关键片段检查。',
+  );
+  assertEqual(
+    payload.systemd.hasAmbientCapability,
+    false,
+    'Nginx 接公网彩排阶段不得有 Pingora 低端口 capability。',
+  );
+  assertEqual(
+    payload.healthPatrolEnv.values.gatewayMode,
+    'nginx',
+    'Nginx 接公网彩排阶段 health patrol gateway mode 应为 nginx。',
+  );
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  assertIncludes(
+    commandsLog,
+    'systemctl is-active nginx.service',
+    'rehearsal 状态必须读取 Nginx service 状态。',
+  );
+  assertIncludes(
+    commandsLog,
+    'ss -H -ltnp',
+    'rehearsal 状态必须读取端口监听。',
+  );
+}
+
+function assertFailsWhenPublicPortsAlreadyOwnedByPingora() {
+  const fixture = prepareFixture('pingora-public', {
+    ssMode: 'pingora-public',
+  });
+  const result = runStatus(fixture, [
+    '--expect-public-gateway',
+    'nginx',
+    '--require-pingora-shadow',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 1, '期望 Nginx 接公网但 80/443 由 Pingora 监听时必须失败。');
+  const payload = parseJson(result.stdout, 'Pingora 抢占公网端口状态输出');
+  assertEqual(
+    payload.publicBoundary.status,
+    'CRITICAL',
+    '公网端口归属漂移时 public boundary 必须 CRITICAL。',
+  );
+  assertIncludes(
+    payload.publicBoundary.diagnostics.join('\n'),
+    '已被 Pingora 监听',
+    '公网端口归属漂移必须给出明确诊断。',
+  );
+}
+
+function assertFailsWhenRealpathCanaryMissing() {
+  const fixture = prepareFixture('missing-realpath', {
+    ssMode: 'nginx-public-shadow-only',
+    writeRealpathConfig: false,
+  });
+  const result = runStatus(fixture, [
+    '--expect-public-gateway',
+    'nginx',
+    '--require-realpath-canary',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 1, '要求 realpath canary 但配置或端口缺失时必须失败。');
+  const payload = parseJson(result.stdout, '缺少 realpath canary 状态输出');
+  assertEqual(
+    payload.realpathCanary.status,
+    'CRITICAL',
+    '缺少 realpath canary 时必须 CRITICAL。',
+  );
+  assertIncludes(
+    payload.realpathCanary.diagnostics.join('\n'),
+    'realpath canary 配置不存在',
+    '缺少 realpath canary 配置时必须给出明确诊断。',
+  );
+}
+
+function assertRejectsUnsafeArgs() {
+  const fixture = prepareFixture('unsafe');
+  const cases = [
+    {
+      args: ['--release-root', 'relative'],
+      expected: '--release-root 必须是绝对路径',
+      reason: 'release root 相对路径必须失败。',
+    },
+    {
+      args: ['--release-root', '/'],
+      expected: '--release-root 不能是文件系统根目录',
+      reason: 'release root 为文件系统根目录必须失败。',
+    },
+    {
+      args: ['--expect-public-gateway', 'apache'],
+      expected: '--expect-public-gateway 只支持 none / nginx / pingora-direct',
+      reason: '未知 public gateway 必须失败。',
+    },
+    {
+      args: ['--timeout-ms', '0'],
+      expected: '--timeout-ms 必须是正整数',
+      reason: 'timeout 非正整数必须失败。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = runStatus(fixture, testCase.args);
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      testCase.expected,
+      `${testCase.reason} 必须输出明确错误。`,
+    );
+  }
+}
+
+function assertRejectsInvalidBoolEnv() {
+  const fixture = prepareFixture('invalid-bool');
+  const result = runStatus(fixture, [], {
+    GENARRATIVE_PINGORA_REHEARSAL_REQUIRE_REALPATH_CANARY: 'maybe',
+  });
+  if ((result.status ?? 0) === 0) {
+    failures.push('非法布尔 env 必须失败。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'GENARRATIVE_PINGORA_REHEARSAL_REQUIRE_REALPATH_CANARY 必须是布尔值',
+    '非法布尔 env 必须输出明确错误。',
+  );
+}
+
+function prepareFixture(name, options = {}) {
+  const root = path.join(tmpRoot, name);
+  const releaseRoot = path.join(root, 'current');
+  const fakeBin = path.join(root, 'bin');
+  const commandsLog = path.join(root, 'commands.log');
+  const healthPatrolEnvFile = path.join(root, 'etc', 'health-patrol.env');
+  const pingoraEnvFile = path.join(root, 'etc', 'pingora-gateway.env');
+  const realpathConfigFile = path.join(
+    root,
+    'nginx',
+    'zz-genarrative-pingora-realpath-canary.conf',
+  );
+
+  mkdirSync(releaseRoot, { recursive: true });
+  mkdirSync(fakeBin, { recursive: true });
+  mkdirSync(path.dirname(healthPatrolEnvFile), { recursive: true });
+  mkdirSync(path.dirname(realpathConfigFile), { recursive: true });
+
+  prepareReleaseRoot(releaseRoot);
+  writeFileSync(
+    healthPatrolEnvFile,
+    [
+      'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx',
+      'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=http://127.0.0.1',
+      'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=',
+      'GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN=health-secret-token',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    pingoraEnvFile,
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+      'GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN=pingora-secret-token',
+      'GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE=/var/log/genarrative/pingora-gateway.access.log',
+      'GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip',
+      'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=false',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  if (options.writeRealpathConfig !== false) {
+    writeFileSync(
+      realpathConfigFile,
+      [
+        'server {',
+        '  listen 127.0.0.1:18083;',
+        '  access_log /var/log/nginx/genarrative-pingora-realpath-canary.access.log genarrative_upstream;',
+        '  add_header X-Genarrative-Nginx-Handoff pingora-realpath-canary always;',
+        '}',
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+  }
+
+  writeFileSync(
+    path.join(fakeBin, 'systemctl'),
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      `printf 'systemctl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      'if [[ "$1" == "is-active" ]]; then',
+      '  printf "active\\n"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "cat" && "${2:-}" == "genarrative-pingora-gateway.service" ]]; then',
+      '  cat <<UNIT',
+      '[Service]',
+      `EnvironmentFile=${pingoraEnvFile}`,
+      'ExecStart=/opt/genarrative/current/pingora-gateway',
+      'UNIT',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" && "${2:-}" == "genarrative-pingora-gateway.service" ]]; then',
+      '  cat <<SHOW',
+      'FragmentPath=/etc/systemd/system/genarrative-pingora-gateway.service',
+      'DropInPaths=',
+      'User=genarrative',
+      `ExecStart={ path=${releaseRoot}/pingora-gateway ; argv[]=${releaseRoot}/pingora-gateway ; }`,
+      'SHOW',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(fakeBin, 'ss'),
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      `printf 'ss %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      `mode="${options.ssMode || 'nginx-public-realpath'}"`,
+      'case "${mode}" in',
+      '  nginx-public-realpath)',
+      '    cat <<SS',
+      'LISTEN 0 511 0.0.0.0:80 0.0.0.0:* users:(("nginx",pid=11,fd=7))',
+      'LISTEN 0 511 0.0.0.0:443 0.0.0.0:* users:(("nginx",pid=11,fd=8))',
+      'LISTEN 0 128 127.0.0.1:18081 0.0.0.0:* users:(("pingora-gateway",pid=22,fd=9))',
+      'LISTEN 0 128 127.0.0.1:18083 0.0.0.0:* users:(("nginx",pid=11,fd=10))',
+      'SS',
+      '    ;;',
+      '  nginx-public-shadow-only)',
+      '    cat <<SS',
+      'LISTEN 0 511 0.0.0.0:80 0.0.0.0:* users:(("nginx",pid=11,fd=7))',
+      'LISTEN 0 511 0.0.0.0:443 0.0.0.0:* users:(("nginx",pid=11,fd=8))',
+      'LISTEN 0 128 127.0.0.1:18081 0.0.0.0:* users:(("pingora-gateway",pid=22,fd=9))',
+      'SS',
+      '    ;;',
+      '  pingora-public)',
+      '    cat <<SS',
+      'LISTEN 0 511 0.0.0.0:80 0.0.0.0:* users:(("pingora-gateway",pid=22,fd=7))',
+      'LISTEN 0 511 0.0.0.0:443 0.0.0.0:* users:(("pingora-gateway",pid=22,fd=8))',
+      'LISTEN 0 128 127.0.0.1:18081 0.0.0.0:* users:(("pingora-gateway",pid=22,fd=9))',
+      'SS',
+      '    ;;',
+      'esac',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodSync(path.join(fakeBin, 'systemctl'), 0o755);
+  chmodSync(path.join(fakeBin, 'ss'), 0o755);
+
+  return {
+    root,
+    releaseRoot,
+    fakeBin,
+    commandsLog,
+    healthPatrolEnvFile,
+    pingoraEnvFile,
+    realpathConfigFile,
+  };
+}
+
+function prepareReleaseRoot(releaseRoot) {
+  const dirs = [
+    'scripts/ops',
+    'scripts/deploy',
+    'scripts',
+    'deploy/systemd',
+    'deploy/nginx/snippets',
+    'deploy/env',
+    'deploy/pingora',
+  ];
+  for (const dir of dirs) {
+    mkdirSync(path.join(releaseRoot, dir), { recursive: true });
+  }
+  writeExecutable(path.join(releaseRoot, 'api-server'));
+  writeExecutable(path.join(releaseRoot, 'pingora-gateway'));
+  writeSha256(releaseRoot, 'api-server');
+  writeSha256(releaseRoot, 'pingora-gateway');
+  const files = [
+    ['scripts/database-backup-to-oss.mjs', 'console.log("backup");\n'],
+    ['scripts/ops/production-health-patrol.mjs', 'console.log("patrol");\n'],
+    ['scripts/check-production-health-patrol-env.mjs', 'console.log("env");\n'],
+    ['scripts/check-pingora-release-readiness.mjs', 'console.log("ready");\n'],
+    ['scripts/check-pingora-direct-preflight.mjs', 'console.log("preflight");\n'],
+    ['scripts/check-pingora-direct-live.mjs', 'console.log("live");\n'],
+    ['scripts/check-pingora-canary-live.mjs', 'console.log("canary");\n'],
+    [
+      'scripts/check-pingora-canary-access-log-parity.mjs',
+      'console.log("parity");\n',
+    ],
+    ['deploy/systemd/genarrative-pingora-gateway.service', '[Service]\n'],
+    ['deploy/systemd/genarrative-pingora-gateway-direct-entry.conf', '[Service]\n'],
+    [
+      'deploy/nginx/snippets/genarrative-pingora-canary.conf',
+      '# canary\n',
+    ],
+    [
+      'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+      '# realpath\n',
+    ],
+    ['deploy/env/health-patrol.env.example', '\n'],
+    ['deploy/env/pingora-direct-live.env.example', '\n'],
+    ['deploy/env/pingora-canary-live.env.example', '\n'],
+    ['deploy/pingora/pingora-gateway.env.example', '\n'],
+    ['deploy/pingora/nginx-route-parity.matrix.json', '[]\n'],
+  ];
+  for (const [relativePath, content] of files) {
+    writeFileSync(path.join(releaseRoot, relativePath), content, 'utf8');
+  }
+  const copyScripts = [
+    'scripts/ops/pingora-current-release-audit.mjs',
+    'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    'scripts/ops/pingora-cutover-command-evidence.mjs',
+    'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    'scripts/deploy/pingora-direct-enable.sh',
+    'scripts/deploy/pingora-direct-rollback.sh',
+    'scripts/deploy/pingora-realpath-canary-enable.sh',
+    'scripts/deploy/pingora-realpath-canary-disable.sh',
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    'scripts/deploy/pingora-tls-cert-sync.mjs',
+  ];
+  for (const relativePath of copyScripts) {
+    copyFileSync(relativePath, path.join(releaseRoot, relativePath));
+  }
+  for (const relativePath of [
+    'scripts/deploy/pingora-direct-enable.sh',
+    'scripts/deploy/pingora-direct-rollback.sh',
+    'scripts/deploy/pingora-realpath-canary-enable.sh',
+    'scripts/deploy/pingora-realpath-canary-disable.sh',
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    'scripts/deploy/pingora-tls-cert-sync.mjs',
+  ]) {
+    chmodSync(path.join(releaseRoot, relativePath), 0o755);
+  }
+  writeFileSync(
+    path.join(releaseRoot, 'release-manifest.json'),
+    `${JSON.stringify(
+      {
+        version: 'test',
+        component_type: 'api-server',
+        artifacts: [
+          {
+            component: 'api-server',
+            path: 'api-server',
+            checksum_path: 'api-server.sha256',
+          },
+          {
+            component: 'pingora-gateway',
+            path: 'pingora-gateway',
+            checksum_path: 'pingora-gateway.sha256',
+          },
+        ],
+      },
+      null,
+      2,
+    )}\n`,
+    'utf8',
+  );
+}
+
+function writeExecutable(filePath) {
+  writeFileSync(filePath, '#!/usr/bin/env bash\n', 'utf8');
+  chmodSync(filePath, 0o755);
+}
+
+function writeSha256(directory, fileName) {
+  const hash = createHash('sha256')
+    .update(readFileSync(path.join(directory, fileName)))
+    .digest('hex');
+  writeFileSync(path.join(directory, `${fileName}.sha256`), `${hash}  ${fileName}\n`);
+}
+
+function runStatus(fixture, args, extraEnv = {}) {
+  return spawnSync(
+    'node',
+    [
+      STATUS_SCRIPT,
+      '--release-root',
+      fixture.releaseRoot,
+      '--health-patrol-env-file',
+      fixture.healthPatrolEnvFile,
+      '--pingora-env-file',
+      fixture.pingoraEnvFile,
+      '--realpath-config-file',
+      fixture.realpathConfigFile,
+      ...args,
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        ...extraEnv,
+        PATH: `${fixture.fakeBin}:${process.env.PATH || ''}`,
+      },
+    },
+  );
+}
+
+function parseJson(value, label) {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  if (result.status !== expected) {
+    failures.push(
+      `${reason} 退出码 ${result.status}，预期 ${expected}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 实际 ${actual}，预期 ${expected}`);
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!String(content || '').includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
diff --git a/scripts/check-pingora-direct-rollback.mjs b/scripts/check-pingora-direct-rollback.mjs
new file mode 100644
index 000000000..6bd447821
--- /dev/null
+++ b/scripts/check-pingora-direct-rollback.mjs
@@ -0,0 +1,2062 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const ROLLBACK_SCRIPT = 'scripts/deploy/pingora-direct-rollback.sh';
+const failures = [];
+
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-rollback-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-direct-rollback] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-direct-rollback] OK');
+
+function main() {
+  assertScriptShape();
+  assertDryRunKeepsDropin();
+  assertDryRunMissingDropin();
+  assertRelativeDropinRejected();
+  assertRelativeServiceUnitPathRejected();
+  assertRejectsRelativeNginxBinaryPath();
+  assertRejectsRelativeCurlBinaryPath();
+  assertRejectsFilesystemRootPathsBeforeApply();
+  assertApplyRequiresReloadNginx();
+  assertApplyRequiresNginxSmokeUrl();
+  assertRejectsInvalidNginxSmokeUrl();
+  assertApplyRequiresHostForLoopbackSmokeUrl();
+  assertRejectsInvalidNginxSmokeHost();
+  assertRejectsRelativeHealthPatrolEnvFile();
+  assertRejectsRelativeHealthPatrolEnvCheckScript();
+  assertRejectsConflictingHealthPatrolPublicHostOptions();
+  assertRejectsInvalidHealthPatrolExpectedPublicBaseUrl();
+  assertRejectsInvalidHealthPatrolExpectedPublicHost();
+  assertRejectsIncompletePingoraShadowProbe();
+  assertRejectsInvalidPingoraShadowProbeUrl();
+  assertRejectsControlCharacterInputsBeforeApply();
+  assertApplyRejectsSymlinkDropinDirectoryBeforeNginxTest();
+  assertApplyRejectsSymlinkDropinFileBeforeRemoval();
+  assertApplyRejectsDirectoryDropinTargetBeforeNginxTest();
+  assertApplyStopsBeforeRemovingDropinWhenNginxTestFails();
+  assertApplyFailsWhenNginxSmokeFails();
+  assertApplyFailsWhenNginxSmokeBodyMismatches();
+  assertApplyFailsWhenHealthPatrolEnvStillDirect();
+  assertApplyFailsWhenHealthPatrolPublicBaseUrlDrifts();
+  assertApplySupportsExpectedHealthPatrolPublicHost();
+  assertApplyFailsWhenSystemdExecStartDiffers();
+  assertApplyFailsWhenPingoraShadowProbeBodyIsWrong();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(ROLLBACK_SCRIPT, 'utf8');
+  assertIncludes(content, 'APPLY="false"', '回退脚本必须默认 dry-run。');
+  assertIncludes(
+    content,
+    '--apply',
+    '回退脚本必须显式要求 --apply 才修改系统。',
+  );
+  assertIncludes(
+    content,
+    'systemctl daemon-reload',
+    '移除 drop-in 后必须 reload systemd。',
+  );
+  assertIncludes(
+    content,
+    'restart "${SERVICE_NAME}"',
+    '回退脚本必须重启 Pingora 服务。',
+  );
+  assertIncludes(
+    content,
+    '--reload-nginx',
+    '回退脚本必须保留显式 Nginx reload。',
+  );
+  assertIncludes(
+    content,
+    '--nginx-binary',
+    '回退脚本必须支持覆盖 Nginx 可执行文件，便于测试和特殊环境。',
+  );
+  assertIncludes(
+    content,
+    '--nginx-smoke-url',
+    '回退脚本必须支持 Nginx 入口 smoke URL。',
+  );
+  assertIncludes(
+    content,
+    '--nginx-smoke-host',
+    '回退脚本必须支持 Nginx 入口 smoke Host。',
+  );
+  assertIncludes(
+    content,
+    '--nginx-smoke-expect-body',
+    '回退脚本必须支持 Nginx smoke 响应体证据片段。',
+  );
+  assertIncludes(
+    content,
+    '--nginx-smoke-url 指向本机地址时必须同时提供 --nginx-smoke-host',
+    '回退脚本 apply 用本机 smoke URL 时必须强制正式 Host。',
+  );
+  assertIncludes(
+    content,
+    '只能是 host 或 host:port',
+    '回退脚本必须拒绝非法 Nginx smoke Host。',
+  );
+  assertIncludes(
+    content,
+    '--curl-binary',
+    '回退脚本必须支持覆盖 curl 可执行文件，便于测试和特殊环境。',
+  );
+  assertIncludes(
+    content,
+    '--health-patrol-env-file',
+    '回退脚本必须支持回退后 health patrol env 复核。',
+  );
+  assertIncludes(
+    content,
+    '--health-patrol-env-check-script',
+    '回退脚本必须支持覆盖 health patrol env 复核脚本，便于 release layout 与测试。',
+  );
+  assertIncludes(
+    content,
+    '--pingora-shadow-probe-url',
+    '回退脚本必须支持回退后 Pingora shadow probe URL。',
+  );
+  assertIncludes(
+    content,
+    '--pingora-shadow-probe-token',
+    '回退脚本必须支持回退后 Pingora shadow probe token。',
+  );
+  assertIncludes(
+    content,
+    '--expected-gateway-mode',
+    '回退脚本必须调用 health patrol env 复核脚本并要求 nginx 模式。',
+  );
+  assertIncludes(
+    content,
+    '--require-empty-public-host',
+    '回退脚本必须要求回退后 health patrol public Host 为空。',
+  );
+  assertIncludes(
+    content,
+    '--health-patrol-expected-public-base-url',
+    '回退脚本必须支持校验回退后 health patrol public base URL。',
+  );
+  assertIncludes(
+    content,
+    '--health-patrol-expected-public-host',
+    '回退脚本必须支持校验回退后 health patrol public Host。',
+  );
+  assertIncludes(
+    content,
+    '--health-patrol-require-empty-public-host',
+    '回退脚本必须支持显式要求回退后 health patrol public Host 为空。',
+  );
+  assertIncludes(
+    content,
+    'dry-run：--apply 后会复核 health patrol env 已切回 nginx，且 public base URL / Host 已恢复为预期值。',
+    '回退脚本 dry-run 必须说明 health patrol env 回退后复核。',
+  );
+  assertIncludes(
+    content,
+    'dry-run：--apply 后会验证 Pingora shadow 探针仍为 gateway=pingora-shadow。',
+    '回退脚本 dry-run 必须说明 Pingora shadow probe 回退后复核。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --reload-nginx',
+    '回退脚本 apply 时必须强制 reload Nginx。',
+  );
+  assertIncludes(
+    content,
+    '--apply 必须同时提供 --nginx-smoke-url',
+    '回退脚本 apply 时必须强制 Nginx 入口 smoke。',
+  );
+  assertIncludes(
+    content,
+    '${NGINX_BINARY} -t',
+    '回退脚本 reload Nginx 前必须先跑 nginx -t。',
+  );
+  assertIncludes(
+    content,
+    'drop-in 目录不能是符号链接',
+    '回退脚本 apply 前必须拒绝符号链接 drop-in 目录。',
+  );
+  assertIncludes(
+    content,
+    'drop-in 目标不能是符号链接',
+    '回退脚本 apply 前必须拒绝符号链接 drop-in 目标。',
+  );
+  assertIncludes(
+    content,
+    'drop-in 目标已存在但不是普通文件',
+    '回退脚本 apply 前必须拒绝非普通文件 drop-in 目标。',
+  );
+  assertIncludes(
+    content,
+    'direct-entry.conf',
+    '回退脚本必须默认指向 direct-entry drop-in。',
+  );
+  assertIncludes(
+    content,
+    '--no-postcheck',
+    '回退脚本必须支持少数异常场景跳过 post-check。',
+  );
+  assertIncludes(
+    content,
+    '--service-unit-path',
+    '回退脚本必须支持覆盖主 service 模板路径，便于 current release 随包执行。',
+  );
+  assertIncludes(
+    content,
+    'systemctl cat ${SERVICE_NAME}',
+    '回退脚本必须在 apply 后核验 systemd 最终配置。',
+  );
+  assertIncludes(
+    content,
+    'systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager',
+    '回退脚本必须在 apply 后核验 Pingora ExecStart 指向 current release。',
+  );
+  assertIncludes(
+    content,
+    '主 service 模板中的',
+    '回退脚本 ExecStart 核验必须以随包主 service 模板为真相源。',
+  );
+  assertIncludes(
+    content,
+    '仍显示 AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    '回退脚本必须拒绝 AmbientCapabilities 残留。',
+  );
+  assertIncludes(
+    content,
+    '仍显示 CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+    '回退脚本必须拒绝 CapabilityBoundingSet 残留。',
+  );
+  assertIncludes(
+    content,
+    'systemctl is-active ${NGINX_SERVICE}',
+    '回退脚本必须在 reload Nginx 后核验 Nginx 状态。',
+  );
+  assertIncludes(
+    content,
+    '${CURL_BINARY} --fail',
+    '回退脚本必须在 reload Nginx 后执行 Nginx smoke。',
+  );
+  assertIncludes(
+    content,
+    'nginx smoke evidence matched expected body fragment',
+    '回退脚本必须在 Nginx smoke 响应体匹配时打印证据摘要。',
+  );
+  assertIncludes(
+    content,
+    'Nginx smoke 响应缺少预期片段',
+    '回退脚本必须拒绝缺少预期响应体片段的 Nginx smoke。',
+  );
+  assertIncludes(
+    content,
+    'Nginx reload 后状态不是 active',
+    '回退脚本必须拒绝 Nginx reload 后非 active 状态。',
+  );
+  assertIncludes(
+    content,
+    'reject_control_characters',
+    '回退脚本必须统一拒绝换行或 NUL 参数。',
+  );
+  assertIncludes(
+    content,
+    '不能包含换行或 NUL 字符',
+    '回退脚本拒绝控制字符时必须给出明确错误。',
+  );
+  assertIncludes(
+    content,
+    'reject_filesystem_root_path',
+    '回退脚本必须统一拒绝文件系统根目录路径参数。',
+  );
+  assertIncludes(
+    content,
+    '不能是文件系统根目录',
+    '回退脚本拒绝文件系统根目录路径时必须给出明确错误。',
+  );
+}
+
+function assertDryRunKeepsDropin() {
+  const dropinPath = path.join(tmpRoot, 'direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+
+  const result = runRollback([
+    '--dropin-path',
+    dropinPath,
+    '--service',
+    'genarrative-pingora-gateway.service',
+    '--reload-nginx',
+    '--nginx-service',
+    'nginx.service',
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--nginx-smoke-expect-body',
+    '"ok":true',
+    '--no-status',
+  ]);
+
+  assertStatus(result, 0, 'dry-run 应成功退出。');
+  assertIncludes(
+    result.stdout,
+    'apply=false',
+    'dry-run 输出必须明确 apply=false。',
+  );
+  assertIncludes(
+    result.stdout,
+    `+ rm -f ${dropinPath}`,
+    'dry-run 必须展示将移除 drop-in。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl daemon-reload',
+    'dry-run 必须展示 daemon-reload。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl restart genarrative-pingora-gateway.service',
+    'dry-run 必须展示重启 Pingora。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ nginx -t',
+    'dry-run 必须展示 reload Nginx 前的 nginx -t。',
+  );
+  assertIncludes(
+    result.stdout,
+    'dry-run：--apply --reload-nginx 后会先执行 nginx -t，通过后再 reload。',
+    'dry-run 必须说明 apply reload 前会先跑 nginx -t。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl reload nginx.service',
+    'dry-run 必须展示可选 reload Nginx。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl is-active nginx.service',
+    'dry-run 必须展示 reload Nginx 后 active 核验。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ curl --fail --silent --show-error --max-time 5 -H Host: example.com http://127.0.0.1/healthz',
+    'dry-run 必须展示 Nginx 入口 smoke。',
+  );
+  assertIncludes(
+    result.stdout,
+    'dry-run：--apply --reload-nginx 后会验证 Nginx smoke URL 可访问，且响应体包含预期片段。',
+    'dry-run 带响应体片段时必须说明会校验 Nginx smoke body。',
+  );
+
+  const healthPatrolEnvFile = path.join(tmpRoot, 'health-patrol.env');
+  const healthPatrolEnvCheckScript = path.join(
+    process.cwd(),
+    'scripts/check-production-health-patrol-env.mjs',
+  );
+  const healthPatrolResult = runRollback([
+    '--dropin-path',
+    dropinPath,
+    '--service',
+    'genarrative-pingora-gateway.service',
+    '--reload-nginx',
+    '--nginx-service',
+    'nginx.service',
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--health-patrol-env-file',
+    healthPatrolEnvFile,
+    '--health-patrol-env-check-script',
+    healthPatrolEnvCheckScript,
+    '--health-patrol-expected-public-base-url',
+    'https://nginx.example.com',
+    '--no-status',
+  ]);
+  assertStatus(
+    healthPatrolResult,
+    0,
+    '带 health patrol env 的 dry-run 应成功退出。',
+  );
+  assertIncludes(
+    healthPatrolResult.stdout,
+    `+ node -- ${healthPatrolEnvCheckScript} --env-file ${healthPatrolEnvFile} --expected-gateway-mode nginx --expected-public-base-url https://nginx.example.com --require-empty-public-host`,
+    'dry-run 必须展示 health patrol env 回退后复核命令。',
+  );
+  assertIncludes(
+    healthPatrolResult.stdout,
+    'dry-run：--apply 后会复核 health patrol env 已切回 nginx，且 public base URL / Host 已恢复为预期值。',
+    'dry-run 必须说明 apply 后会复核 health patrol env。',
+  );
+
+  const healthPatrolHostResult = runRollback([
+    '--dropin-path',
+    dropinPath,
+    '--service',
+    'genarrative-pingora-gateway.service',
+    '--reload-nginx',
+    '--nginx-service',
+    'nginx.service',
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--health-patrol-env-file',
+    healthPatrolEnvFile,
+    '--health-patrol-env-check-script',
+    healthPatrolEnvCheckScript,
+    '--health-patrol-expected-public-base-url',
+    'https://nginx.example.com',
+    '--health-patrol-expected-public-host',
+    'nginx.example.com',
+    '--no-status',
+  ]);
+  assertStatus(
+    healthPatrolHostResult,
+    0,
+    '带显式 health patrol public Host 的 dry-run 应成功退出。',
+  );
+  assertIncludes(
+    healthPatrolHostResult.stdout,
+    `+ node -- ${healthPatrolEnvCheckScript} --env-file ${healthPatrolEnvFile} --expected-gateway-mode nginx --expected-public-base-url https://nginx.example.com --expected-public-host nginx.example.com`,
+    'dry-run 必须展示显式 public Host 的 health patrol env 回退后复核命令。',
+  );
+
+  const shadowProbeResult = runRollback([
+    '--dropin-path',
+    dropinPath,
+    '--service',
+    'genarrative-pingora-gateway.service',
+    '--reload-nginx',
+    '--nginx-service',
+    'nginx.service',
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--pingora-shadow-probe-url',
+    'http://127.0.0.1:18081/__genarrative_pingora/healthz',
+    '--pingora-shadow-probe-token',
+    'test-shadow-probe-token',
+    '--no-status',
+  ]);
+  assertStatus(
+    shadowProbeResult,
+    0,
+    '带 Pingora shadow probe 的 dry-run 应成功退出。',
+  );
+  assertIncludes(
+    shadowProbeResult.stdout,
+    '+ curl --fail --silent --show-error --max-time 5 -H X-Genarrative-Pingora-Probe: <redacted> http://127.0.0.1:18081/__genarrative_pingora/healthz',
+    'dry-run 必须展示 Pingora shadow probe 命令且隐藏 token。',
+  );
+  if (shadowProbeResult.stdout.includes('test-shadow-probe-token')) {
+    failures.push('dry-run Pingora shadow probe 命令不应输出 probe token 原文。');
+  }
+  assertIncludes(
+    shadowProbeResult.stdout,
+    'dry-run：--apply 后会验证 Pingora shadow 探针仍为 gateway=pingora-shadow。',
+    'dry-run 必须说明 apply 后会复核 Pingora shadow probe。',
+  );
+
+  assertIncludes(
+    result.stdout,
+    '+ systemctl cat genarrative-pingora-gateway.service',
+    'dry-run 必须展示回退后 systemd drop-in 移除核验。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager',
+    'dry-run 必须展示回退后 ExecStart 指向核验。',
+  );
+  assertIncludes(
+    result.stdout,
+    'dry-run：--apply 后会校验 systemd 最终配置不再包含 CAP_NET_BIND_SERVICE。',
+    'dry-run 必须说明 apply 后会核验 capability 已移除。',
+  );
+  assertIncludes(
+    result.stdout,
+    'dry-run：--apply 后会核验 systemd ExecStart 指向主 service 模板中的 /opt/genarrative/current/pingora-gateway。',
+    'dry-run 必须说明 apply 后会核验 Pingora ExecStart 指向 current release。',
+  );
+  assertIncludes(
+    result.stdout,
+    'dry-run：--apply --reload-nginx 后会 reload Nginx 并校验 service 仍为 active。',
+    'dry-run 必须说明 apply reload 后会核验 Nginx active。',
+  );
+
+  if (!existsSync(dropinPath)) {
+    failures.push('dry-run 不应删除临时 drop-in 文件。');
+  }
+}
+
+function assertDryRunMissingDropin() {
+  const dropinPath = path.join(tmpRoot, 'missing-direct-entry.conf');
+  const result = runRollback(['--dropin-path', dropinPath, '--no-status']);
+
+  assertStatus(result, 0, 'drop-in 不存在时 dry-run 应视为已回退。');
+  assertIncludes(
+    result.stdout,
+    'direct-entry drop-in 不存在，视为已移除',
+    'drop-in 不存在时必须给出清晰提示。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl daemon-reload',
+    'drop-in 不存在时仍应 reload systemd。',
+  );
+  assertIncludes(
+    result.stdout,
+    '+ systemctl restart genarrative-pingora-gateway.service',
+    'drop-in 不存在时仍应重启 Pingora 进入 shadow 口径。',
+  );
+}
+
+function assertRelativeDropinRejected() {
+  const result = runRollback([
+    '--dropin-path',
+    'relative/direct-entry.conf',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('相对路径 drop-in 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--dropin-path 必须是绝对路径',
+    '相对路径负例必须说明需要绝对路径。',
+  );
+}
+
+function assertRelativeServiceUnitPathRejected() {
+  const dropinPath = path.join(tmpRoot, 'relative-service-unit-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--service-unit-path',
+    'relative/genarrative-pingora-gateway.service',
+    '--dropin-path',
+    dropinPath,
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('相对路径 --service-unit-path 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--service-unit-path 必须是绝对路径',
+    'service unit 相对路径负例必须说明需要绝对路径。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('service unit 相对路径负例不应删除 drop-in。');
+  }
+}
+
+function assertRejectsRelativeNginxBinaryPath() {
+  const dropinPath = path.join(tmpRoot, 'relative-nginx-binary-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-binary',
+    './nginx',
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('相对路径 --nginx-binary 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--nginx-binary 包含路径分隔符时必须是绝对路径',
+    'Nginx 二进制相对路径负例必须说明需要绝对路径。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('Nginx 二进制相对路径负例不应删除 drop-in。');
+  }
+}
+
+function assertRejectsRelativeCurlBinaryPath() {
+  const dropinPath = path.join(tmpRoot, 'relative-curl-binary-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--curl-binary',
+    'tools/curl',
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('相对路径 --curl-binary 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--curl-binary 包含路径分隔符时必须是绝对路径',
+    'curl 二进制相对路径负例必须说明需要绝对路径。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('curl 二进制相对路径负例不应删除 drop-in。');
+  }
+}
+
+function assertRejectsFilesystemRootPathsBeforeApply() {
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-should-not-run-root.sh');
+  const dropinPath = path.join(tmpRoot, 'root-path-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(
+    nginxBinary,
+    '#!/usr/bin/env bash\necho "nginx should not run for root path" >&2\nexit 99\n',
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+
+  const rootDropinResult = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    '/',
+    '--nginx-binary',
+    nginxBinary,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--no-status',
+  ]);
+  if (rootDropinResult.status === 0) {
+    failures.push('文件系统根目录 --dropin-path 必须被拒绝。');
+  }
+  assertIncludes(
+    rootDropinResult.stderr,
+    '--dropin-path 不能是文件系统根目录',
+    '文件系统根目录 drop-in 路径负例必须给出明确错误。',
+  );
+  if (rootDropinResult.stderr.includes('nginx should not run for root path')) {
+    failures.push('文件系统根目录 drop-in 被拒绝后不应继续执行 nginx -t。');
+  }
+
+  const rootHealthPatrolEnvResult = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-binary',
+    nginxBinary,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--health-patrol-env-file',
+    '/',
+    '--no-status',
+  ]);
+  if (rootHealthPatrolEnvResult.status === 0) {
+    failures.push('文件系统根目录 --health-patrol-env-file 必须被拒绝。');
+  }
+  assertIncludes(
+    rootHealthPatrolEnvResult.stderr,
+    '--health-patrol-env-file 不能是文件系统根目录',
+    '文件系统根目录 health patrol env 路径负例必须给出明确错误。',
+  );
+  if (rootHealthPatrolEnvResult.stderr.includes('nginx should not run for root path')) {
+    failures.push('文件系统根目录 health patrol env 被拒绝后不应继续执行 nginx -t。');
+  }
+  if (!existsSync(dropinPath)) {
+    failures.push('文件系统根目录 health patrol env 被拒绝后不应删除 drop-in。');
+  }
+}
+
+function assertApplyRequiresReloadNginx() {
+  const dropinPath = path.join(tmpRoot, 'apply-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--dropin-path',
+    dropinPath,
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('--apply 缺少 --reload-nginx 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--apply 必须同时提供 --reload-nginx',
+    'apply 负例必须说明不能跳过 Nginx reload。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('--apply 缺少 --reload-nginx 时不应删除 drop-in。');
+  }
+}
+
+function assertApplyRequiresNginxSmokeUrl() {
+  const dropinPath = path.join(tmpRoot, 'apply-smoke-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('--apply 缺少 --nginx-smoke-url 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--apply 必须同时提供 --nginx-smoke-url',
+    'apply 负例必须说明不能跳过 Nginx smoke。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('--apply 缺少 --nginx-smoke-url 时不应删除 drop-in。');
+  }
+}
+
+function assertRejectsInvalidNginxSmokeUrl() {
+  const dropinPath = path.join(tmpRoot, 'invalid-smoke-url-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    '127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('非法 --nginx-smoke-url 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--nginx-smoke-url 必须是 http(s) URL',
+    '非法 Nginx smoke URL 负例必须给出明确错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('非法 Nginx smoke URL 时不应删除 drop-in。');
+  }
+}
+
+function assertApplyRequiresHostForLoopbackSmokeUrl() {
+  const dropinPath = path.join(tmpRoot, 'apply-smoke-host-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push(
+      '--apply 使用 loopback --nginx-smoke-url 时缺少 --nginx-smoke-host 必须被拒绝。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '--nginx-smoke-url 指向本机地址时必须同时提供 --nginx-smoke-host',
+    'loopback Nginx smoke 负例必须说明需要正式 Host。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('缺少 loopback smoke Host 时不应删除 drop-in。');
+  }
+}
+
+function assertRejectsInvalidNginxSmokeHost() {
+  const dropinPath = path.join(tmpRoot, 'invalid-smoke-host-direct-entry.conf');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'https://example.com/path',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('非法 --nginx-smoke-host 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--nginx-smoke-host 只能是 host 或 host:port',
+    '非法 Nginx smoke Host 负例必须给出明确错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('非法 smoke Host 时不应删除 drop-in。');
+  }
+}
+
+function assertRejectsRelativeHealthPatrolEnvFile() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'relative-health-patrol-env-direct-entry.conf',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--health-patrol-env-file',
+    'relative/health-patrol.env',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('相对路径 --health-patrol-env-file 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--health-patrol-env-file 必须是绝对路径',
+    'health patrol env 相对路径负例必须说明需要绝对路径。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('health patrol env 相对路径负例不应删除 drop-in。');
+  }
+}
+
+function assertRejectsRelativeHealthPatrolEnvCheckScript() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'relative-health-patrol-check-direct-entry.conf',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--health-patrol-env-file',
+    path.join(tmpRoot, 'health-patrol.env'),
+    '--health-patrol-env-check-script',
+    'relative/check-production-health-patrol-env.mjs',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('相对路径 --health-patrol-env-check-script 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--health-patrol-env-check-script 必须是绝对路径',
+    'health patrol env check script 相对路径负例必须说明需要绝对路径。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('health patrol check script 相对路径负例不应删除 drop-in。');
+  }
+}
+
+function assertRejectsConflictingHealthPatrolPublicHostOptions() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'conflicting-health-patrol-host-direct-entry.conf',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--health-patrol-env-file',
+    path.join(tmpRoot, 'health-patrol.env'),
+    '--health-patrol-expected-public-host',
+    'nginx.example.com',
+    '--health-patrol-require-empty-public-host',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push(
+      '显式 public Host 与 require empty public Host 同时提供时必须被拒绝。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '--health-patrol-expected-public-host 和 --health-patrol-require-empty-public-host 不能同时使用',
+    'health patrol public Host 冲突参数必须给出明确错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('health patrol public Host 冲突参数时不应删除 drop-in。');
+  }
+}
+
+function assertRejectsInvalidHealthPatrolExpectedPublicBaseUrl() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'invalid-health-patrol-public-base-url-direct-entry.conf',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--health-patrol-env-file',
+    path.join(tmpRoot, 'health-patrol.env'),
+    '--health-patrol-expected-public-base-url',
+    '127.0.0.1',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('非法 health patrol expected public base URL 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--health-patrol-expected-public-base-url 必须是 http(s) URL',
+    '非法 health patrol expected public base URL 负例必须给出明确错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push(
+      '非法 health patrol expected public base URL 时不应删除 drop-in。',
+    );
+  }
+}
+
+function assertRejectsInvalidHealthPatrolExpectedPublicHost() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'invalid-health-patrol-public-host-direct-entry.conf',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--health-patrol-env-file',
+    path.join(tmpRoot, 'health-patrol.env'),
+    '--health-patrol-expected-public-host',
+    'https://nginx.example.com/path',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('非法 health patrol expected public Host 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--health-patrol-expected-public-host 只能是 host 或 host:port',
+    '非法 health patrol expected public Host 负例必须给出明确错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push(
+      '非法 health patrol expected public Host 时不应删除 drop-in。',
+    );
+  }
+}
+
+function assertRejectsIncompletePingoraShadowProbe() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'incomplete-shadow-probe-direct-entry.conf',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const missingToken = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--pingora-shadow-probe-url',
+    'http://127.0.0.1:18081/__genarrative_pingora/healthz',
+    '--no-status',
+  ]);
+  if (missingToken.status === 0) {
+    failures.push('shadow probe URL 缺少 token 必须被拒绝。');
+  }
+  assertIncludes(
+    missingToken.stderr,
+    '--pingora-shadow-probe-url 必须同时提供 --pingora-shadow-probe-token',
+    'shadow probe URL 缺少 token 负例必须给出明确错误。',
+  );
+
+  const missingUrl = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--pingora-shadow-probe-token',
+    'test-shadow-probe-token',
+    '--no-status',
+  ]);
+  if (missingUrl.status === 0) {
+    failures.push('shadow probe token 缺少 URL 必须被拒绝。');
+  }
+  assertIncludes(
+    missingUrl.stderr,
+    '--pingora-shadow-probe-token 必须同时提供 --pingora-shadow-probe-url',
+    'shadow probe token 缺少 URL 负例必须给出明确错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('shadow probe 参数不完整时不应删除 drop-in。');
+  }
+}
+
+function assertRejectsInvalidPingoraShadowProbeUrl() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'invalid-shadow-probe-url-direct-entry.conf',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--pingora-shadow-probe-url',
+    '127.0.0.1:18081/__genarrative_pingora/healthz',
+    '--pingora-shadow-probe-token',
+    'test-shadow-probe-token',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('非法 --pingora-shadow-probe-url 必须被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--pingora-shadow-probe-url 必须是 http(s) URL',
+    '非法 shadow probe URL 负例必须给出明确错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('非法 shadow probe URL 时不应删除 drop-in。');
+  }
+}
+
+function assertRejectsControlCharacterInputsBeforeApply() {
+  const dropinPath = path.join(tmpRoot, 'control-character-direct-entry.conf');
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-should-not-run-control.sh');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(
+    nginxBinary,
+    '#!/usr/bin/env bash\necho "nginx should not run" >&2\nexit 99\n',
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-binary',
+    nginxBinary,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com\ninjected.example.com',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('带换行的 Nginx smoke Host 必须在 rollback apply 修改系统前被拒绝。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--nginx-smoke-host 不能包含换行或 NUL 字符',
+    'Nginx smoke Host 控制字符负例必须给出明确错误。',
+  );
+  if (result.stderr.includes('nginx should not run')) {
+    failures.push('带换行的 Nginx smoke Host 被拒绝后不应继续执行 nginx -t。');
+  }
+  if (!existsSync(dropinPath)) {
+    failures.push('带换行的 Nginx smoke Host 被拒绝后不应删除 drop-in。');
+  }
+}
+
+function assertApplyRejectsSymlinkDropinDirectoryBeforeNginxTest() {
+  const realDropinDir = path.join(tmpRoot, 'rollback-real-service.d');
+  const symlinkDropinDir = path.join(tmpRoot, 'rollback-linked-service.d');
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-should-not-run-dir.sh');
+  mkdirSync(realDropinDir, { recursive: true });
+  symlinkSync(realDropinDir, symlinkDropinDir);
+  writeFileSync(
+    nginxBinary,
+    '#!/usr/bin/env bash\necho "nginx should not run" >&2\nexit 99\n',
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    path.join(symlinkDropinDir, 'direct-entry.conf'),
+    '--nginx-binary',
+    nginxBinary,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('drop-in 目录是符号链接时 rollback apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'drop-in 目录不能是符号链接',
+    'rollback drop-in 符号链接目录负例必须给出明确错误。',
+  );
+  if (result.stderr.includes('nginx should not run')) {
+    failures.push('drop-in 目录是符号链接时不应继续执行 nginx -t。');
+  }
+  if (existsSync(path.join(realDropinDir, 'direct-entry.conf'))) {
+    failures.push('drop-in 目录是符号链接时不应删除或写入真实目标目录。');
+  }
+}
+
+function assertApplyRejectsSymlinkDropinFileBeforeRemoval() {
+  const dropinDir = path.join(tmpRoot, 'rollback-symlink-file-service.d');
+  const realDropinFile = path.join(tmpRoot, 'rollback-real-direct-entry.conf');
+  const symlinkDropinFile = path.join(dropinDir, 'direct-entry.conf');
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-should-not-run-file.sh');
+  mkdirSync(dropinDir, { recursive: true });
+  writeFileSync(realDropinFile, 'original rollback dropin\n', 'utf8');
+  symlinkSync(realDropinFile, symlinkDropinFile);
+  writeFileSync(
+    nginxBinary,
+    '#!/usr/bin/env bash\necho "nginx should not run" >&2\nexit 99\n',
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    symlinkDropinFile,
+    '--nginx-binary',
+    nginxBinary,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('drop-in 目标是符号链接时 rollback apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'drop-in 目标不能是符号链接',
+    'rollback drop-in 符号链接目标负例必须给出明确错误。',
+  );
+  if (result.stderr.includes('nginx should not run')) {
+    failures.push('drop-in 目标是符号链接时不应继续执行 nginx -t。');
+  }
+  const realContent = readFileSync(realDropinFile, 'utf8');
+  if (realContent !== 'original rollback dropin\n') {
+    failures.push('drop-in 目标是符号链接时不应改写真实目标文件。');
+  }
+}
+
+function assertApplyRejectsDirectoryDropinTargetBeforeNginxTest() {
+  const dropinDir = path.join(tmpRoot, 'rollback-directory-target-service.d');
+  const dropinPath = path.join(dropinDir, 'direct-entry.conf');
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-should-not-run-target.sh');
+  mkdirSync(dropinPath, { recursive: true });
+  writeFileSync(
+    nginxBinary,
+    '#!/usr/bin/env bash\necho "nginx should not run" >&2\nexit 99\n',
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-binary',
+    nginxBinary,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('drop-in 目标是目录时 rollback apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'drop-in 目标已存在但不是普通文件',
+    'rollback drop-in 目录目标负例必须给出明确错误。',
+  );
+  if (result.stderr.includes('nginx should not run')) {
+    failures.push('drop-in 目标是目录时不应继续执行 nginx -t。');
+  }
+  if (!existsSync(dropinPath)) {
+    failures.push('drop-in 目标是目录时不应删除该目录。');
+  }
+}
+
+function assertApplyStopsBeforeRemovingDropinWhenNginxTestFails() {
+  const dropinPath = path.join(tmpRoot, 'nginx-test-fail-direct-entry.conf');
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-fail.sh');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(
+    nginxBinary,
+    '#!/usr/bin/env bash\necho "fake nginx -t failed" >&2\nexit 1\n',
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+
+  const result = runRollback([
+    '--apply',
+    '--reload-nginx',
+    '--dropin-path',
+    dropinPath,
+    '--nginx-binary',
+    nginxBinary,
+    '--nginx-smoke-url',
+    'http://127.0.0.1/healthz',
+    '--nginx-smoke-host',
+    'example.com',
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('nginx -t 失败时 rollback apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'fake nginx -t failed',
+    'nginx -t 失败时必须暴露 Nginx 检查错误。',
+  );
+  if (!existsSync(dropinPath)) {
+    failures.push('nginx -t 失败时不应删除 drop-in。');
+  }
+}
+
+function assertApplyFailsWhenNginxSmokeFails() {
+  const dropinPath = path.join(tmpRoot, 'nginx-smoke-fail-direct-entry.conf');
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-ok.sh');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+  const curlBinary = path.join(tmpRoot, 'fake-curl-fail.sh');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(nginxBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/current/pingora-gateway ; argv[]=/opt/genarrative/current/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    curlBinary,
+    '#!/usr/bin/env bash\necho "fake nginx smoke failed" >&2\nexit 22\n',
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+  chmodExecutable(systemctlBinary);
+  chmodExecutable(curlBinary);
+
+  const result = runRollback(
+    [
+      '--apply',
+      '--reload-nginx',
+      '--dropin-path',
+      dropinPath,
+      '--nginx-binary',
+      nginxBinary,
+      '--curl-binary',
+      curlBinary,
+      '--nginx-smoke-url',
+      'http://127.0.0.1/healthz',
+      '--nginx-smoke-host',
+      'example.com',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push('Nginx smoke 失败时 rollback apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'fake nginx smoke failed',
+    'Nginx smoke 失败时必须暴露 curl 错误。',
+  );
+}
+
+function assertApplyFailsWhenNginxSmokeBodyMismatches() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'nginx-smoke-body-mismatch-direct-entry.conf',
+  );
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-body-ok.sh');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+  const curlBinary = path.join(tmpRoot, 'fake-curl-body-mismatch.sh');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(nginxBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/current/pingora-gateway ; argv[]=/opt/genarrative/current/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    curlBinary,
+    '#!/usr/bin/env bash\necho \'{"ok":false,"service":"unexpected"}\'\n',
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+  chmodExecutable(systemctlBinary);
+  chmodExecutable(curlBinary);
+
+  const result = runRollback(
+    [
+      '--apply',
+      '--reload-nginx',
+      '--dropin-path',
+      dropinPath,
+      '--nginx-binary',
+      nginxBinary,
+      '--curl-binary',
+      curlBinary,
+      '--nginx-smoke-url',
+      'http://127.0.0.1/healthz',
+      '--nginx-smoke-host',
+      'example.com',
+      '--nginx-smoke-expect-body',
+      '"ok":true',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push('Nginx smoke 响应体不匹配时 rollback apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'Nginx smoke 响应缺少预期片段: "ok":true',
+    'Nginx smoke 响应体不匹配时必须暴露明确错误。',
+  );
+  assertIncludes(
+    result.stderr,
+    'Nginx smoke 响应前 500 字符',
+    'Nginx smoke 响应体不匹配时必须输出截断响应便于排障。',
+  );
+}
+
+function assertApplyFailsWhenHealthPatrolEnvStillDirect() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'health-patrol-direct-leftover-direct-entry.conf',
+  );
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-health-ok.sh');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+  const curlBinary = path.join(tmpRoot, 'fake-curl-health-ok.sh');
+  const healthPatrolEnvFile = path.join(
+    tmpRoot,
+    'health-patrol-direct-leftover.env',
+  );
+  const healthPatrolEnvCheckScript = path.join(
+    process.cwd(),
+    'scripts/check-production-health-patrol-env.mjs',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(nginxBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/current/pingora-gateway ; argv[]=/opt/genarrative/current/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    curlBinary,
+    '#!/usr/bin/env bash\necho \'{"ok":true,"service":"genarrative-api-server"}\'\n',
+    'utf8',
+  );
+  writeFileSync(
+    healthPatrolEnvFile,
+    [
+      'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct',
+      'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://127.0.0.1',
+      'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=example.com',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+  chmodExecutable(systemctlBinary);
+  chmodExecutable(curlBinary);
+
+  const result = runRollback(
+    [
+      '--apply',
+      '--reload-nginx',
+      '--dropin-path',
+      dropinPath,
+      '--nginx-binary',
+      nginxBinary,
+      '--curl-binary',
+      curlBinary,
+      '--nginx-smoke-url',
+      'http://127.0.0.1/healthz',
+      '--nginx-smoke-host',
+      'example.com',
+      '--health-patrol-env-file',
+      healthPatrolEnvFile,
+      '--health-patrol-env-check-script',
+      healthPatrolEnvCheckScript,
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push(
+      'health patrol env 仍停留在 pingora-direct 时 rollback apply 必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE 应为 nginx，实际 pingora-direct',
+    'health patrol env 模式错误时必须暴露明确错误。',
+  );
+  assertIncludes(
+    result.stderr,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 应为空，实际 example.com',
+    'health patrol env Host 残留时必须暴露明确错误。',
+  );
+}
+
+function assertApplyFailsWhenHealthPatrolPublicBaseUrlDrifts() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'health-patrol-base-url-drift-direct-entry.conf',
+  );
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-base-url-ok.sh');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+  const curlBinary = path.join(tmpRoot, 'fake-curl-base-url-ok.sh');
+  const healthPatrolEnvFile = path.join(
+    tmpRoot,
+    'health-patrol-base-url-drift.env',
+  );
+  const healthPatrolEnvCheckScript = path.join(
+    process.cwd(),
+    'scripts/check-production-health-patrol-env.mjs',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(nginxBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/current/pingora-gateway ; argv[]=/opt/genarrative/current/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    curlBinary,
+    '#!/usr/bin/env bash\necho \'{"ok":true,"service":"genarrative-api-server"}\'\n',
+    'utf8',
+  );
+  writeFileSync(
+    healthPatrolEnvFile,
+    [
+      'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx',
+      'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://wrong.example.com',
+      'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+  chmodExecutable(systemctlBinary);
+  chmodExecutable(curlBinary);
+
+  const result = runRollback(
+    [
+      '--apply',
+      '--reload-nginx',
+      '--dropin-path',
+      dropinPath,
+      '--nginx-binary',
+      nginxBinary,
+      '--curl-binary',
+      curlBinary,
+      '--nginx-smoke-url',
+      'http://127.0.0.1/healthz',
+      '--nginx-smoke-host',
+      'example.com',
+      '--health-patrol-env-file',
+      healthPatrolEnvFile,
+      '--health-patrol-env-check-script',
+      healthPatrolEnvCheckScript,
+      '--health-patrol-expected-public-base-url',
+      'https://nginx.example.com',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push(
+      'health patrol public base URL 漂移时 rollback apply 必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL 应为 https://nginx.example.com，实际 https://wrong.example.com',
+    'health patrol public base URL 漂移时必须暴露明确错误。',
+  );
+}
+
+function assertApplySupportsExpectedHealthPatrolPublicHost() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'health-patrol-expected-host-direct-entry.conf',
+  );
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-expected-host-ok.sh');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+  const curlBinary = path.join(tmpRoot, 'fake-curl-expected-host-ok.sh');
+  const healthPatrolEnvFile = path.join(
+    tmpRoot,
+    'health-patrol-expected-host.env',
+  );
+  const healthPatrolEnvCheckScript = path.join(
+    process.cwd(),
+    'scripts/check-production-health-patrol-env.mjs',
+  );
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(nginxBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/current/pingora-gateway ; argv[]=/opt/genarrative/current/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    curlBinary,
+    '#!/usr/bin/env bash\necho \'{"ok":true,"service":"genarrative-api-server"}\'\n',
+    'utf8',
+  );
+  writeFileSync(
+    healthPatrolEnvFile,
+    [
+      'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx',
+      'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://nginx.example.com',
+      'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=nginx.example.com',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+  chmodExecutable(systemctlBinary);
+  chmodExecutable(curlBinary);
+
+  const result = runRollback(
+    [
+      '--apply',
+      '--reload-nginx',
+      '--dropin-path',
+      dropinPath,
+      '--nginx-binary',
+      nginxBinary,
+      '--curl-binary',
+      curlBinary,
+      '--nginx-smoke-url',
+      'http://127.0.0.1/healthz',
+      '--nginx-smoke-host',
+      'example.com',
+      '--health-patrol-env-file',
+      healthPatrolEnvFile,
+      '--health-patrol-env-check-script',
+      healthPatrolEnvCheckScript,
+      '--health-patrol-expected-public-base-url',
+      'https://nginx.example.com',
+      '--health-patrol-expected-public-host',
+      'nginx.example.com',
+      '--nginx-smoke-expect-body',
+      '"ok":true',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  assertStatus(
+    result,
+    0,
+    'health patrol public Host 与切换前记录一致时 rollback apply 应成功。',
+  );
+  assertIncludes(
+    result.stdout,
+    '--expected-public-host nginx.example.com',
+    'rollback apply 必须把显式 health patrol public Host 传给复核脚本。',
+  );
+  assertIncludes(
+    result.stdout,
+    '[check:production-health-patrol-env] OK',
+    'rollback apply 应执行 health patrol env 复核并通过。',
+  );
+  assertIncludes(
+    result.stdout,
+    'nginx smoke evidence matched expected body fragment.',
+    'rollback apply 应在 Nginx smoke body 匹配后输出证据摘要。',
+  );
+}
+
+function assertApplyFailsWhenSystemdExecStartDiffers() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'systemd-exec-mismatch-direct-entry.conf',
+  );
+  const serviceUnitPath = path.join(
+    tmpRoot,
+    'systemd-exec-mismatch.service',
+  );
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-exec-ok.sh');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+  const curlBinary = path.join(tmpRoot, 'fake-curl-exec-ok.sh');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(
+    serviceUnitPath,
+    [
+      '[Service]',
+      'ExecStart=/opt/genarrative/current/pingora-gateway',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(nginxBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/old-release/pingora-gateway ; argv[]=/opt/genarrative/old-release/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(curlBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  chmodExecutable(nginxBinary);
+  chmodExecutable(systemctlBinary);
+  chmodExecutable(curlBinary);
+
+  const result = runRollback(
+    [
+      '--apply',
+      '--reload-nginx',
+      '--service-unit-path',
+      serviceUnitPath,
+      '--dropin-path',
+      dropinPath,
+      '--nginx-binary',
+      nginxBinary,
+      '--curl-binary',
+      curlBinary,
+      '--nginx-smoke-url',
+      'http://127.0.0.1/healthz',
+      '--nginx-smoke-host',
+      'example.com',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push(
+      'systemctl show ExecStart 指向旧 release 时 rollback apply 必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    'systemctl show ExecStart 未指向主 service 模板中的 /opt/genarrative/current/pingora-gateway',
+    'systemd 最终 ExecStart 指向旧 release 时必须给出明确错误。',
+  );
+}
+
+function assertApplyFailsWhenPingoraShadowProbeBodyIsWrong() {
+  const dropinPath = path.join(
+    tmpRoot,
+    'shadow-probe-body-wrong-direct-entry.conf',
+  );
+  const nginxBinary = path.join(tmpRoot, 'fake-nginx-shadow-ok.sh');
+  const systemctlBinary = path.join(tmpRoot, 'systemctl');
+  const curlBinary = path.join(tmpRoot, 'fake-curl-shadow-body-wrong.sh');
+  writeFileSync(
+    dropinPath,
+    '[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE\n',
+    'utf8',
+  );
+  writeFileSync(nginxBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'if [[ "$1" == "cat" ]]; then',
+      '  echo "[Service]"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "show" ]]; then',
+      '  echo "{ path=/opt/genarrative/current/pingora-gateway ; argv[]=/opt/genarrative/current/pingora-gateway ; }"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "is-active" ]]; then',
+      '  echo active',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    curlBinary,
+    [
+      '#!/usr/bin/env bash',
+      'last_arg="${@: -1}"',
+      'if [[ "${last_arg}" == *"__genarrative_pingora/healthz"* ]]; then',
+      '  echo \'{"ok":true,"gateway":"not-pingora"}\'',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+  chmodExecutable(systemctlBinary);
+  chmodExecutable(curlBinary);
+
+  const result = runRollback(
+    [
+      '--apply',
+      '--reload-nginx',
+      '--dropin-path',
+      dropinPath,
+      '--nginx-binary',
+      nginxBinary,
+      '--curl-binary',
+      curlBinary,
+      '--nginx-smoke-url',
+      'http://127.0.0.1/healthz',
+      '--nginx-smoke-host',
+      'example.com',
+      '--pingora-shadow-probe-url',
+      'http://127.0.0.1:18081/__genarrative_pingora/healthz',
+      '--pingora-shadow-probe-token',
+      'test-shadow-probe-token',
+      '--no-status',
+    ],
+    { PATH: `${tmpRoot}:${process.env.PATH || ''}` },
+  );
+
+  if (result.status === 0) {
+    failures.push('Pingora shadow probe body 错误时 rollback apply 必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'Pingora shadow 探针响应不是预期 JSON',
+    'Pingora shadow probe body 错误时必须暴露明确错误。',
+  );
+}
+
+function runRollback(args, env = {}) {
+  return spawnSync('bash', [ROLLBACK_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      ...env,
+    },
+  });
+}
+
+function chmodExecutable(filePath) {
+  spawnSync('chmod', ['0755', filePath], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!content.includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
diff --git a/scripts/check-pingora-gateway-env-shadow-switch.mjs b/scripts/check-pingora-gateway-env-shadow-switch.mjs
new file mode 100644
index 000000000..57a28ee43
--- /dev/null
+++ b/scripts/check-pingora-gateway-env-shadow-switch.mjs
@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const SWITCH_SCRIPT = 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-gateway-env-shadow-switch-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-gateway-env-shadow-switch] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-gateway-env-shadow-switch] OK');
+
+function main() {
+  assertScriptShape();
+  assertDryRunDoesNotModifyEnv();
+  assertApplyRestoresShadowAndPreservesOtherKeys();
+  assertApplyPreservesEnvFileMode();
+  assertMissingManagedKeysAreAppended();
+  assertDuplicateManagedKeysFail();
+  assertRejectsRelativeAndRootEnvFile();
+  assertRejectsSymlinkEnvFileBeforeWrite();
+  assertRejectsControlCharacterEnvFile();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(SWITCH_SCRIPT, 'utf8');
+  assertIncludes(content, '--apply', '切换脚本必须显式要求 --apply 才写 env。');
+  assertIncludes(
+    content,
+    '当前是 dry-run',
+    '切换脚本必须在 dry-run 中明确不会写 env。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_LISTEN: \'127.0.0.1:18081\'',
+    '切换脚本必须固定恢复 Pingora shadow 高端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: \'\'',
+    '切换脚本必须清空 TLS 低端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: \'\'',
+    '切换脚本必须清空 HTTP redirect 低端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: \'\'',
+    '切换脚本必须清空 TLS 证书链路径，避免无 TLS_LISTEN 但残留 cert。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: \'\'',
+    '切换脚本必须清空 TLS 私钥路径，避免无 TLS_LISTEN 但残留 key。',
+  );
+  assertIncludes(
+    content,
+    'assertShadowEnv(checkFile);',
+    '切换脚本必须先用临时目标 env 复核 shadow 口径。',
+  );
+  assertIncludes(
+    content,
+    'writeEnvFileAtomically(config.envFile, nextText);',
+    '切换脚本通过复核后才可原子写入真实 env。',
+  );
+  assertIncludes(
+    content,
+    '--env-file 不能是符号链接',
+    'apply 写入真实 env 前必须拒绝符号链接目标。',
+  );
+  assertIncludes(
+    content,
+    'DRY_RUN_ENV_FILE_MODE = 0o600',
+    '临时复核 env 文件权限必须固定为 0600。',
+  );
+  assertIncludes(
+    content,
+    'chownSync(tempFile, currentStat.uid, currentStat.gid);',
+    '真实 env 原子替换必须保留原文件 owner/group。',
+  );
+}
+
+function assertDryRunDoesNotModifyEnv() {
+  const envFile = writeEnv('dry-run.env', {
+    GENARRATIVE_PINGORA_GATEWAY_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: '0.0.0.0:80',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: '/etc/genarrative/pingora-tls/example/privkey.pem',
+  });
+  const before = readFileSync(envFile, 'utf8');
+  const result = runSwitch(['--env-file', envFile]);
+
+  assertStatus(result, 0, 'dry-run 应成功。');
+  assertEqual(
+    readFileSync(envFile, 'utf8'),
+    before,
+    'dry-run 不应修改真实 Pingora gateway env。',
+  );
+  assertIncludes(
+    result.stdout,
+    '当前是 dry-run',
+    'dry-run 输出必须明确不会写入 env。',
+  );
+}
+
+function assertApplyRestoresShadowAndPreservesOtherKeys() {
+  const envFile = writeEnv('apply.env', {
+    GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API: 'http://127.0.0.1:8082',
+    GENARRATIVE_PINGORA_GATEWAY_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: '0.0.0.0:80',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: '/etc/genarrative/pingora-tls/example/privkey.pem',
+    GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED: 'true',
+  });
+  const result = runSwitch(['--env-file', envFile, '--apply']);
+  const content = readFileSync(envFile, 'utf8');
+
+  assertStatus(result, 0, 'apply 应成功。');
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+    'apply 必须恢复 shadow 高端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=',
+    'apply 必须清空 TLS 低端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=',
+    'apply 必须清空 HTTP redirect 低端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=',
+    'apply 必须清空 TLS 证书链路径。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=',
+    'apply 必须清空 TLS 私钥路径。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API=http://127.0.0.1:8082',
+    'apply 不应修改其它 Pingora gateway env。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true',
+    'apply 不应修改接流保护配置。',
+  );
+}
+
+function assertApplyPreservesEnvFileMode() {
+  const envFile = writeEnv('mode.env', {
+    GENARRATIVE_PINGORA_GATEWAY_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: '0.0.0.0:80',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: '/etc/genarrative/pingora-tls/example/privkey.pem',
+  });
+  chmodSync(envFile, 0o640);
+  const before = statSync(envFile);
+  const result = runSwitch(['--env-file', envFile, '--apply']);
+  const after = statSync(envFile);
+
+  assertStatus(result, 0, 'apply 保留权限 smoke 应成功。');
+  assertEqual(
+    after.mode & 0o777,
+    before.mode & 0o777,
+    'apply 原子替换必须保留 env 文件权限。',
+  );
+}
+
+function assertMissingManagedKeysAreAppended() {
+  const envFile = writeEnv('append.env', {
+    GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API: 'http://127.0.0.1:8082',
+  });
+  const result = runSwitch(['--env-file', envFile, '--apply']);
+  const content = readFileSync(envFile, 'utf8');
+
+  assertStatus(result, 0, '缺失目标键时 apply 应成功。');
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+    '缺失 LISTEN 时必须追加 shadow 默认值。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=',
+    '缺失 TLS_LISTEN 时必须追加空值。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=',
+    '缺失 HTTP_REDIRECT_LISTEN 时必须追加空值。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=',
+    '缺失 TLS_CERT_FILE 时必须追加空值。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=',
+    '缺失 TLS_KEY_FILE 时必须追加空值。',
+  );
+}
+
+function assertDuplicateManagedKeysFail() {
+  const envFile = path.join(tmpRoot, 'duplicate.env');
+  writeFileSync(
+    envFile,
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_LISTEN=0.0.0.0:443',
+      'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  const result = runSwitch(['--env-file', envFile]);
+
+  assertStatus(result, 1, '重复目标键必须失败。');
+  assertIncludes(
+    result.stderr,
+    'pingora gateway env 中存在重复配置',
+    '重复目标键失败时必须说明具体原因。',
+  );
+}
+
+function assertRejectsRelativeAndRootEnvFile() {
+  const relative = runSwitch(['--env-file', 'relative.env']);
+  assertStatus(relative, 1, '相对 env 路径必须失败。');
+  assertIncludes(
+    relative.stderr,
+    '--env-file 必须是绝对路径',
+    '相对 env 路径失败时必须说明原因。',
+  );
+
+  const root = runSwitch(['--env-file', '/']);
+  assertStatus(root, 1, '文件系统根目录 env 路径必须失败。');
+  assertIncludes(
+    root.stderr,
+    '--env-file 不能是文件系统根目录',
+    '根目录 env 路径失败时必须说明原因。',
+  );
+}
+
+function assertRejectsSymlinkEnvFileBeforeWrite() {
+  const target = writeEnv('symlink-target.env', {
+    GENARRATIVE_PINGORA_GATEWAY_LISTEN: '0.0.0.0:443',
+  });
+  const link = path.join(tmpRoot, 'symlink.env');
+  symlinkSync(target, link);
+  const before = readFileSync(target, 'utf8');
+  const result = runSwitch(['--env-file', link, '--apply']);
+
+  assertStatus(result, 1, '符号链接 env 必须失败。');
+  assertIncludes(
+    result.stderr,
+    '--env-file 不能是符号链接',
+    '符号链接 env 失败时必须说明原因。',
+  );
+  assertEqual(
+    readFileSync(target, 'utf8'),
+    before,
+    '符号链接 env 被拒绝后不应写真实目标文件。',
+  );
+}
+
+function assertRejectsControlCharacterEnvFile() {
+  const result = spawnSync(
+    process.execPath,
+    ['--', SWITCH_SCRIPT, '--env-file', `${tmpRoot}/bad\n.env`],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  assertStatus(result, 1, '控制字符 env 路径必须失败。');
+  assertIncludes(
+    result.stderr,
+    '--env-file 不能包含换行或 NUL 字符',
+    '控制字符 env 路径失败时必须说明原因。',
+  );
+}
+
+function runSwitch(args) {
+  return spawnSync(process.execPath, ['--', SWITCH_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function writeEnv(fileName, values) {
+  const filePath = path.join(tmpRoot, fileName);
+  const lines = Object.entries(values).map(([key, value]) => `${key}=${value}`);
+  writeFileSync(filePath, `${lines.join('\n')}\n`, 'utf8');
+  return filePath;
+}
+
+function assertStatus(result, expected, message) {
+  if ((result.status ?? 0) !== expected) {
+    failures.push(
+      `${message} 实际退出码 ${result.status}。stdout=${result.stdout || '<empty>'} stderr=${result.stderr || '<empty>'}`,
+    );
+  }
+}
+
+function assertIncludes(value, expected, message) {
+  if (!String(value || '').includes(expected)) {
+    failures.push(`${message} 缺少 ${expected}。`);
+  }
+}
+
+function assertEqual(actual, expected, message) {
+  if (actual !== expected) {
+    failures.push(`${message} 实际 ${actual}，预期 ${expected}。`);
+  }
+}
diff --git a/scripts/check-pingora-gateway-smoke.mjs b/scripts/check-pingora-gateway-smoke.mjs
new file mode 100644
index 000000000..ef2aac8c1
--- /dev/null
+++ b/scripts/check-pingora-gateway-smoke.mjs
@@ -0,0 +1,2481 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const repoRoot = process.cwd();
+const failures = [];
+const childProcesses = [];
+const servers = [];
+const sockets = new Set();
+const tempDirs = [];
+const SPACETIME_WEBSOCKET_PROTOCOL = 'v2.bsatn.spacetimedb';
+const SECRET_VALUE_FLAGS = new Set(['--probe-token']);
+const PNG_MAGIC_BYTES = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+
+const config = parseArgs(process.argv.slice(2));
+
+try {
+  await main();
+} catch (error) {
+  failures.push(error instanceof Error ? error.message : String(error));
+} finally {
+  await cleanup();
+}
+
+if (failures.length > 0) {
+  console.error('\n[pingora-gateway-smoke] 未通过：');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('\n[pingora-gateway-smoke] 通过');
+
+async function main() {
+  const tempRoot = await mkdtemp(
+    path.join(os.tmpdir(), 'genarrative-pingora-smoke-'),
+  );
+  tempDirs.push(tempRoot);
+  const webRoot = path.join(tempRoot, 'web');
+  const acmeRoot = path.join(tempRoot, 'acme');
+  const maintenanceFile = path.join(tempRoot, 'maintenance', 'enabled');
+  const accessLogFile = path.join(tempRoot, 'logs', 'pingora.access.log');
+
+  await prepareStaticRoots(webRoot, acmeRoot);
+
+  const api = await startApiMock();
+  const spacetime = await startSpacetimeMock();
+  const gitea = await startGiteaMock();
+  const listenPort = await getFreePort();
+  const tlsListenPort = await getFreePort();
+  const redirectListenPort = await getFreePort();
+  const tlsFiles = await createSelfSignedCertificate(tempRoot);
+  const probeToken = `probe-${randomBytes(8).toString('hex')}`;
+
+  if (!config.skipBuild) {
+    runCommand('cargo', [
+      'build',
+      '-p',
+      'pingora-gateway',
+      '--manifest-path',
+      'server-rs/Cargo.toml',
+    ]);
+  }
+
+  const gatewayBinary = resolveGatewayBinary();
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN:
+        '__GENARRATIVE_PINGORA_PROBE_TOKEN__',
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN',
+    'probe token 占位值',
+  );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL: '10',
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL',
+    'gzip 等级越界',
+  );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS: 'br',
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS',
+    '未验收压缩算法',
+  );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS: '0',
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS',
+    '上游读取超时为 0',
+  );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: `127.0.0.1:${tlsListenPort}`,
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE',
+    'TLS 证书未配置',
+  );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: `127.0.0.1:${redirectListenPort}`,
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+    'HTTP 重定向未配置 TLS 入口',
+  );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS: 'git.genarrative.world',
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM',
+    'Gitea Host 缺少上游',
+  );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM: '127.0.0.1:3000',
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS',
+    'Gitea 上游缺少 Host',
+  );
+  const gateway = spawn(gatewayBinary, [], {
+    cwd: repoRoot,
+    env: {
+      ...smokeEnv(),
+      GENARRATIVE_PINGORA_GATEWAY_LISTEN: `127.0.0.1:${listenPort}`,
+      GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: `127.0.0.1:${tlsListenPort}`,
+      GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: tlsFiles.certFile,
+      GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: tlsFiles.keyFile,
+      GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: `127.0.0.1:${redirectListenPort}`,
+      GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_TARGET_SCHEME: 'https',
+      GENARRATIVE_PINGORA_GATEWAY_API_UPSTREAM: `127.0.0.1:${api.port}`,
+      GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM: `127.0.0.1:${spacetime.port}`,
+      GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS:
+        'git.genarrative.world, Git-Alias.Genarrative.World:443',
+      GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM: `127.0.0.1:${gitea.port}`,
+      GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT: webRoot,
+      GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT: acmeRoot,
+      GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE: maintenanceFile,
+      GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE: accessLogFile,
+      GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN: probeToken,
+      GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO: 'https',
+      GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS: 'gzip',
+      GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED: 'true',
+      GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL: '5',
+      GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_CONNECT_TIMEOUT_MS: '1000',
+      GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS: '2',
+      GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS: '1',
+      GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_LONG_READ_TIMEOUT_SECONDS: '60',
+      GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_WRITE_TIMEOUT_SECONDS: '2',
+      GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR: 'true',
+      GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED: 'true',
+      GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES: '12',
+      GENARRATIVE_PINGORA_GATEWAY_API_MAX_CONCURRENT: '1',
+      GENARRATIVE_PINGORA_GATEWAY_API_RATE_PER_SECOND: '1',
+      GENARRATIVE_PINGORA_GATEWAY_API_BURST: '0',
+      GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_MAX_CONCURRENT: '1',
+      GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_RATE_PER_SECOND: '0',
+      GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_BURST: '0',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_MAX_CONCURRENT: '16',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_RATE_PER_SECOND: '100',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_BURST: '100',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_MAX_CONCURRENT: '16',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_RATE_PER_SECOND: '100',
+      GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_BURST: '100',
+      GENARRATIVE_PINGORA_GATEWAY_SPACETIME_MAX_CONCURRENT: '16',
+      GENARRATIVE_PINGORA_GATEWAY_SPACETIME_RATE_PER_SECOND: '100',
+      GENARRATIVE_PINGORA_GATEWAY_SPACETIME_BURST: '100',
+      GENARRATIVE_PINGORA_GATEWAY_LOG: config.verbose
+        ? 'info,pingora=info,pingora_gateway=info'
+        : 'warn,pingora=warn,pingora_gateway=warn',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  childProcesses.push({ child: gateway, name: 'pingora-gateway' });
+  collectProcessLogs(gateway, 'pingora-gateway');
+
+  const baseUrl = `http://127.0.0.1:${listenPort}`;
+  const tlsBaseUrl = `https://127.0.0.1:${tlsListenPort}`;
+  const redirectBaseUrl = `http://127.0.0.1:${redirectListenPort}`;
+  await waitForHttp(`${baseUrl}/`, 200);
+
+  await runDirectLiveSmoke(tlsBaseUrl, redirectBaseUrl, probeToken, accessLogFile);
+  await runSmokeCases(
+    baseUrl,
+    tlsBaseUrl,
+    redirectBaseUrl,
+    probeToken,
+    maintenanceFile,
+    accessLogFile,
+    api,
+    spacetime,
+    gitea,
+  );
+}
+
+function expectInvalidConfigRejected(
+  gatewayBinary,
+  env,
+  expectedNeedle,
+  label,
+) {
+  console.log(`[pingora-gateway-smoke] 配置错误启动失败: ${label}`);
+  const result = spawnSync(gatewayBinary, [], {
+    cwd: repoRoot,
+    env: {
+      ...smokeEnv(),
+      GENARRATIVE_PINGORA_GATEWAY_LISTEN: '127.0.0.1:0',
+      ...env,
+    },
+    shell: false,
+    encoding: 'utf8',
+    timeout: 3000,
+  });
+
+  if (result.error?.code === 'ETIMEDOUT') {
+    failures.push(`配置错误启动失败: ${label} 未被拒绝，进程超时后已终止`);
+  } else if (result.status === 0) {
+    failures.push(`配置错误启动失败: ${label} 未被拒绝`);
+  }
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  if (!output.includes(expectedNeedle)) {
+    failures.push(`配置错误启动失败: ${label} 错误输出缺少 ${expectedNeedle}`);
+  }
+}
+
+function parseArgs(argv) {
+  const result = {
+    skipBuild: false,
+    verbose: false,
+  };
+
+  for (const arg of argv) {
+    switch (arg) {
+      case '--skip-build':
+        result.skipBuild = true;
+        break;
+      case '--verbose':
+        result.verbose = true;
+        break;
+      case '-h':
+      case '--help':
+        console.log(`Usage:
+  node scripts/check-pingora-gateway-smoke.mjs [--skip-build] [--verbose]
+
+本地启动 mock api-server、mock SpacetimeDB 和 pingora-gateway，
+覆盖静态路由、API 代理、body limit、429 接流保护、维护模式和 WebSocket Upgrade。
+`);
+        process.exit(0);
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  return result;
+}
+
+async function prepareStaticRoots(webRoot, acmeRoot) {
+  await mkdir(path.join(webRoot, 'admin', 'assets'), { recursive: true });
+  await mkdir(path.join(webRoot, 'assets'), { recursive: true });
+  await mkdir(
+    path.join(
+      webRoot,
+      'Icons',
+      "Admurin's Pixel Items",
+      "Admurin's Pixel Items",
+      'General',
+      'Singles',
+    ),
+    { recursive: true },
+  );
+  await mkdir(path.join(acmeRoot, '.well-known', 'acme-challenge'), {
+    recursive: true,
+  });
+
+  await writeFile(
+    path.join(webRoot, 'index.html'),
+    [
+      '<main>site-shell</main>',
+      '<script type="module" src="/assets/app.js"></script>',
+      '<script type="module" src="/assets/index-B4dmVw0r.js"></script>',
+    ].join(''),
+  );
+  await writeFile(
+    path.join(webRoot, 'admin', 'index.html'),
+    '<main>admin-shell</main>',
+  );
+  await writeFile(
+    path.join(webRoot, 'assets', 'app.js'),
+    'console.log("site asset");\n',
+  );
+  await writeFile(
+    path.join(webRoot, 'assets', 'index-B4dmVw0r.js'),
+    'console.log("fingerprinted site asset");\n',
+  );
+  await writeFile(
+    path.join(webRoot, 'assets', 'large-app.js'),
+    `console.log("site asset large");\n${'/* asset filler */\n'.repeat(120)}`,
+  );
+  await writeFile(
+    path.join(webRoot, 'assets', 'large-image.webp'),
+    Buffer.alloc(4096, 0x52),
+  );
+  await writeFile(
+    path.join(
+      webRoot,
+      'Icons',
+      "Admurin's Pixel Items",
+      "Admurin's Pixel Items",
+      'General',
+      'Singles',
+      '499_Iron_Gear.png',
+    ),
+    Buffer.concat([
+      PNG_MAGIC_BYTES,
+      Buffer.from([0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52]),
+    ]),
+  );
+  await writeFile(
+    path.join(webRoot, 'admin', 'assets', 'admin.js'),
+    'console.log("admin asset");',
+  );
+  await writeFile(
+    path.join(webRoot, 'admin', 'assets', 'admin-Ca8f3012.css'),
+    'body{color:#123456;}',
+  );
+  await writeFile(
+    path.join(webRoot, 'maintenance.html'),
+    '<main>maintenance</main>',
+  );
+  await writeFile(
+    path.join(acmeRoot, '.well-known', 'acme-challenge', 'token'),
+    'acme-token',
+  );
+}
+
+async function createSelfSignedCertificate(tempRoot) {
+  const tlsDir = path.join(tempRoot, 'tls');
+  await mkdir(tlsDir, { recursive: true });
+  const certFile = path.join(tlsDir, 'cert.pem');
+  const keyFile = path.join(tlsDir, 'key.pem');
+  runCommand('openssl', [
+    'req',
+    '-x509',
+    '-newkey',
+    'rsa:2048',
+    '-nodes',
+    '-keyout',
+    keyFile,
+    '-out',
+    certFile,
+    '-subj',
+    '/CN=localhost',
+    '-addext',
+    'subjectAltName=DNS:localhost,IP:127.0.0.1',
+    '-days',
+    '1',
+  ]);
+  return { certFile, keyFile };
+}
+
+async function startApiMock() {
+  const state = {
+    requests: [],
+    releaseHold: undefined,
+  };
+  const server = http.createServer(async (request, response) => {
+    let body;
+    try {
+      body = await readRequestBody(request);
+    } catch (error) {
+      state.requests.push({
+        method: request.method || '',
+        url: request.url || '',
+        headers: request.headers,
+        body: Buffer.alloc(0),
+        aborted: true,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return;
+    }
+
+    state.requests.push({
+      method: request.method || '',
+      url: request.url || '',
+      headers: request.headers,
+      body,
+    });
+
+    if (request.url?.endsWith('/hold')) {
+      await new Promise((resolve) => {
+        state.releaseHold = resolve;
+      });
+    } else if (request.url?.endsWith('/upstream-close')) {
+      request.socket.destroy();
+      return;
+    } else if (request.url?.endsWith('/slow')) {
+      await delay(1500);
+    }
+
+    response.writeHead(200, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'X-Upstream': 'api',
+    });
+    response.end(
+      JSON.stringify({
+        ok: true,
+        upstream: 'api',
+        method: request.method,
+        url: request.url,
+        requestId: request.headers['x-request-id'] || '',
+        forwardedProto: request.headers['x-forwarded-proto'] || '',
+        forwardedHost: request.headers['x-forwarded-host'] || '',
+        forwardedFor: request.headers['x-forwarded-for'] || '',
+        realIp: request.headers['x-real-ip'] || '',
+        host: request.headers.host || '',
+        bodyBytes: body.length,
+      }),
+    );
+  });
+
+  const port = await listen(server);
+  return {
+    port,
+    state,
+  };
+}
+
+async function startSpacetimeMock() {
+  const state = {
+    websocketMessages: [],
+    requests: [],
+  };
+  const server = http.createServer(async (request, response) => {
+    state.requests.push({
+      method: request.method || '',
+      url: request.url || '',
+      headers: request.headers,
+    });
+    response.writeHead(200, {
+      'Content-Type': 'application/json; charset=utf-8',
+    });
+    response.end(
+      JSON.stringify({ ok: true, upstream: 'spacetime', url: request.url }),
+    );
+  });
+
+  server.on('upgrade', (request, socket) => {
+    socket.on('error', () => {});
+    state.requests.push({
+      method: request.method || '',
+      url: request.url || '',
+      headers: request.headers,
+    });
+    const key = request.headers['sec-websocket-key'];
+    if (!key) {
+      socket.destroy();
+      return;
+    }
+
+    const accept = createHash('sha1')
+      .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+      .digest('base64');
+    socket.write(
+      [
+        'HTTP/1.1 101 Switching Protocols',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Protocol: ${SPACETIME_WEBSOCKET_PROTOCOL}`,
+        `Sec-WebSocket-Accept: ${accept}`,
+        '',
+        '',
+      ].join('\r\n'),
+    );
+    socket.write(encodeWebSocketTextFrame('spacetime-upgrade-ok'));
+    socket.on('data', (chunk) => {
+      state.websocketMessages.push(chunk);
+    });
+  });
+
+  const port = await listen(server);
+  return {
+    port,
+    state,
+  };
+}
+
+async function startGiteaMock() {
+  const state = {
+    requests: [],
+  };
+  const server = http.createServer(async (request, response) => {
+    const body = await readRequestBody(request);
+    state.requests.push({
+      method: request.method || '',
+      url: request.url || '',
+      headers: request.headers,
+      body,
+    });
+
+    response.writeHead(200, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'X-Upstream': 'gitea',
+    });
+    response.end(
+      JSON.stringify({
+        ok: true,
+        upstream: 'gitea',
+        method: request.method,
+        url: request.url,
+        forwardedProto: request.headers['x-forwarded-proto'] || '',
+        forwardedHost: request.headers['x-forwarded-host'] || '',
+        host: request.headers.host || '',
+      }),
+    );
+  });
+
+  const port = await listen(server);
+  return {
+    port,
+    state,
+  };
+}
+
+async function runSmokeCases(
+  baseUrl,
+  tlsBaseUrl,
+  redirectBaseUrl,
+  probeToken,
+  maintenanceFile,
+  accessLogFile,
+  api,
+  spacetime,
+  gitea,
+) {
+  await expectHttp(
+    baseUrl,
+    '/',
+    200,
+    'site-shell',
+    '主站根路径返回 index.html',
+    {
+      validate: (response) =>
+        response.headers['cache-control'] === 'no-cache',
+    },
+  );
+  await expectHttp(
+    baseUrl,
+    '/some/deep/link',
+    200,
+    'site-shell',
+    '主站深链回退 index.html',
+    {
+      validate: (response) =>
+        response.headers['cache-control'] === 'no-cache',
+    },
+  );
+  await expectHttp(baseUrl, '/admin', 301, '', '/admin 301 到 /admin/', {
+    validate: (response) => response.headers.location === '/admin/',
+  });
+  await expectHttp(
+    baseUrl,
+    '/admin/settings',
+    200,
+    'admin-shell',
+    '后台深链回退 admin/index.html',
+  );
+  const staticAssetResponse = await expectHttp(
+    baseUrl,
+    '/assets/app.js',
+    200,
+    'site asset',
+    '主站静态资源精确读取',
+    {
+      validate: (response) =>
+        response.headers['cache-control'] === 'no-cache',
+    },
+  );
+  assertStaticValidatorHeaders(staticAssetResponse, '主站静态资源精确读取');
+  ensure(
+    staticAssetResponse.headers['accept-ranges'] === 'bytes',
+    `主站静态资源精确读取: 缺少 Accept-Ranges=bytes，实际 ${staticAssetResponse.headers['accept-ranges'] || '-'}`,
+  );
+  await expectHttp(
+    baseUrl,
+    '/assets/app.js',
+    200,
+    '',
+    'HEAD 静态资源只返回响应头',
+    {
+      method: 'HEAD',
+      validate: (response) =>
+        response.body === '' &&
+        response.headers.etag === staticAssetResponse.headers.etag &&
+        response.headers['last-modified'] ===
+          staticAssetResponse.headers['last-modified'] &&
+        Number(response.headers['content-length']) ===
+          Buffer.byteLength('console.log("site asset");\n'),
+    },
+  );
+  await expectStaticNotModifiedByEtag(
+    baseUrl,
+    '/assets/app.js',
+    staticAssetResponse,
+    {
+      headers: {
+        'X-Request-Id': 'static-etag-304-request-id',
+      },
+    },
+  );
+  await expectStaticNotModifiedByLastModified(
+    baseUrl,
+    '/assets/app.js',
+    staticAssetResponse,
+    {
+      headers: {
+        'X-Request-Id': 'static-last-modified-304-request-id',
+      },
+    },
+  );
+  await expectHttp(
+    baseUrl,
+    '/assets/app.js',
+    405,
+    '',
+    '静态资源非读取方法返回 405',
+    {
+      method: 'POST',
+      headers: {
+        'X-Request-Id': 'static-method-405-request-id',
+      },
+      body: 'ignored',
+      validate: (response) =>
+        response.body === '' &&
+        response.headers.allow === 'GET, HEAD' &&
+        response.headers['x-genarrative-gateway'] === 'pingora-shadow',
+    },
+  );
+  await expectStaticRange(
+    baseUrl,
+    '/assets/app.js',
+    'bytes=0-6',
+    206,
+    'console',
+    'bytes 0-6/27',
+    '静态资源 Range 返回 206',
+    {
+      headers: {
+        'X-Request-Id': 'static-range-206-request-id',
+      },
+    },
+  );
+  await expectStaticRange(
+    baseUrl,
+    '/assets/app.js',
+    'bytes=0-6',
+    206,
+    'console',
+    'bytes 0-6/27',
+    '静态资源 If-Range 日期匹配返回 206',
+    {
+      headers: {
+        'If-Range': staticAssetResponse.headers['last-modified'],
+      },
+    },
+  );
+  await expectStaticRangeFallback(
+    baseUrl,
+    '/assets/app.js',
+    'bytes=0-6',
+    'Tue, 14 Nov 2023 22:13:12 GMT',
+    '静态资源 If-Range 旧日期回完整文件',
+  );
+  await expectStaticRangeFallback(
+    baseUrl,
+    '/assets/app.js',
+    'bytes=0-6',
+    staticAssetResponse.headers.etag,
+    '静态资源 If-Range 弱 ETag 回完整文件',
+  );
+  await expectStaticRange(
+    baseUrl,
+    '/assets/app.js',
+    'bytes=-8',
+    206,
+    'sset");\n',
+    'bytes 19-26/27',
+    '静态资源 suffix Range 返回 206',
+  );
+  await expectStaticRange(
+    baseUrl,
+    '/assets/app.js',
+    'bytes=999-1000',
+    416,
+    '',
+    'bytes */27',
+    '静态资源越界 Range 返回 416',
+    {
+      headers: {
+        'X-Request-Id': 'static-range-416-request-id',
+      },
+    },
+  );
+  await expectStaticRange(
+    baseUrl,
+    '/assets/app.js',
+    'bytes=0-6',
+    206,
+    '',
+    'bytes 0-6/27',
+    'HEAD 静态资源 Range 只返回响应头',
+    {
+      method: 'HEAD',
+      expectedContentLength: 7,
+      headers: {
+        'X-Request-Id': 'static-head-range-206-request-id',
+      },
+    },
+  );
+  await expectHttp(
+    baseUrl,
+    '/assets/index-B4dmVw0r.js',
+    200,
+    'fingerprinted site asset',
+    '主站指纹静态资源长缓存',
+    {
+      validate: (response) =>
+        response.headers['cache-control'] ===
+        'public, max-age=31536000, immutable',
+    },
+  );
+  await expectNotCompressedResponse(
+    baseUrl,
+    '/assets/app.js',
+    'site asset',
+    'gzip 最小长度不压缩小响应',
+  );
+  await expectGzipResponse(baseUrl, '/assets/large-app.js', 'site asset large');
+  await expectGzipResponse(baseUrl, '/assets/large-app.js', 'site asset large', {
+    acceptEncoding: 'br, gzip',
+    label: 'gzip-only 压缩算法白名单',
+  });
+  await expectNotCompressedResponse(
+    baseUrl,
+    '/assets/large-image.webp',
+    undefined,
+    'gzip types 不压缩图片资源',
+  );
+  await expectStaticPng(
+    baseUrl,
+    "/Icons/Admurin%27s%20Pixel%20Items/Admurin%27s%20Pixel%20Items/General/Singles/499_Iron_Gear.png",
+    '百分号编码图标路径返回 PNG',
+  );
+  await expectHttp(
+    baseUrl,
+    '/assets%2ffavicon.svg',
+    404,
+    '',
+    '静态路径拒绝编码斜杠',
+  );
+  await expectRawPathHttp(
+    baseUrl,
+    '/assets/%2e%2e/favicon.svg',
+    404,
+    '',
+    '静态路径拒绝编码上级目录',
+  );
+  await expectHttp(
+    baseUrl,
+    '/assets/%GG',
+    404,
+    '',
+    '静态路径拒绝非法百分号编码',
+  );
+  await expectHttp(
+    baseUrl,
+    '/admin/assets/admin.js',
+    200,
+    'admin asset',
+    '后台静态资源精确读取',
+    {
+      validate: (response) =>
+        response.headers['cache-control'] === 'no-cache',
+    },
+  );
+  await expectHttp(
+    baseUrl,
+    '/admin/assets/admin-Ca8f3012.css',
+    200,
+    'body{color',
+    '后台指纹静态资源长缓存',
+    {
+      validate: (response) =>
+        response.headers['cache-control'] ===
+        'public, max-age=31536000, immutable',
+    },
+  );
+  await expectHttp(
+    baseUrl,
+    '/.well-known/acme-challenge/token',
+    200,
+    'acme-token',
+    'ACME challenge 读取',
+    {
+      validate: (response) =>
+        response.headers['cache-control'] === 'no-cache',
+    },
+  );
+  await expectHttp(
+    tlsBaseUrl,
+    '/',
+    200,
+    'site-shell',
+    'TLS 直连接口返回 index.html',
+    { insecureTls: true },
+  );
+  await expectHttp(
+    redirectBaseUrl,
+    '/api/creation-entry/config?from=smoke',
+    301,
+    '',
+    'HTTP 入口 301 到 HTTPS',
+    {
+      headers: { Host: 'example.test' },
+      validate: (response) =>
+        response.headers.location ===
+        'https://example.test/api/creation-entry/config?from=smoke',
+    },
+  );
+  await expectHttp(
+    redirectBaseUrl,
+    '/.well-known/acme-challenge/token',
+    200,
+    'acme-token',
+    'HTTP 重定向入口保留 ACME challenge',
+  );
+  await expectHttp(
+    baseUrl,
+    '/generated-puzzle-assets/a.png',
+    404,
+    '',
+    'generated 私有资产公网拒绝',
+  );
+  await expectHttp(baseUrl, '/healthz', 404, '', '公网 healthz 拒绝');
+  await expectHttp(
+    baseUrl,
+    '/v1/ping',
+    404,
+    '',
+    '非白名单 SpacetimeDB 路由拒绝',
+  );
+
+  await expectHttp(
+    baseUrl,
+    '/__genarrative_pingora/healthz',
+    404,
+    '',
+    'shadow probe 无 token 返回 404',
+  );
+  await expectHttp(
+    baseUrl,
+    '/__genarrative_pingora/healthz',
+    200,
+    '"gateway":"pingora-shadow"',
+    'shadow probe token 通过',
+    {
+      headers: { 'X-Genarrative-Pingora-Probe': probeToken },
+    },
+  );
+
+  const apiResponse = await expectHttp(
+    baseUrl,
+    '/api/creation-entry/config',
+    200,
+    '"upstream":"api"',
+    '通用 API 转发',
+    {
+      headers: {
+        'X-Request-Id': 'smoke-request-id',
+        'X-Forwarded-For': '203.0.113.10',
+        Host: 'example.test',
+      },
+    },
+  );
+  ensure(
+    apiResponse.headers['x-genarrative-gateway'] === 'pingora-shadow',
+    'API 响应缺少网关标记',
+  );
+  ensure(
+    apiResponse.headers['x-accel-buffering'] === 'no',
+    'API 响应缺少 X-Accel-Buffering=no',
+  );
+  const apiPayload = JSON.parse(apiResponse.body);
+  ensure(
+    apiPayload.requestId === 'smoke-request-id',
+    'API 上游未收到 X-Request-Id',
+  );
+  ensure(
+    apiPayload.forwardedProto === 'https',
+    'API 上游未收到配置的 X-Forwarded-Proto',
+  );
+  ensure(apiPayload.host === 'example.test', 'API 上游 Host 未透传');
+  ensure(
+    apiPayload.forwardedHost === 'example.test',
+    'API 上游未收到 X-Forwarded-Host',
+  );
+  ensure(
+    apiPayload.forwardedFor.endsWith(', 127.0.0.1'),
+    `API 上游 X-Forwarded-For 未追加 TCP 对端 IP：${apiPayload.forwardedFor}`,
+  );
+  ensure(
+    apiPayload.realIp === '127.0.0.1',
+    `API 上游 X-Real-IP 未使用 TCP 对端 IP：${apiPayload.realIp}`,
+  );
+
+  await expectHttp(
+    baseUrl,
+    '/api/upload',
+    413,
+    'PAYLOAD_TOO_LARGE',
+    'Content-Length body limit',
+    {
+      method: 'POST',
+      body: '0123456789abcdef',
+    },
+  );
+  await expectChunkedLimit(baseUrl, '/api/upload');
+
+  await expectConcurrencyLimit(baseUrl, api);
+
+  const rateLimitHeaders = { 'X-Forwarded-For': '203.0.113.13' };
+  const beforeRateLimitRequestCount = api.state.requests.length;
+  await expectHttp(
+    baseUrl,
+    '/api/rate-limited',
+    200,
+    '"upstream":"api"',
+    'API RPS 首次请求放行',
+    {
+      headers: rateLimitHeaders,
+    },
+  );
+  await expectHttp(
+    baseUrl,
+    '/api/rate-limited',
+    429,
+    'GATEWAY_RATE_LIMITED',
+    'API RPS 保护',
+    {
+      headers: rateLimitHeaders,
+    },
+  );
+  ensure(
+    api.state.requests.length === beforeRateLimitRequestCount + 1,
+    'API RPS 保护的 429 请求不应打到上游',
+  );
+  await expectHttp(
+    baseUrl,
+    '/api/upstream-close',
+    502,
+    'GATEWAY_UPSTREAM_ERROR',
+    'API 上游断连返回稳定 JSON',
+    {
+      headers: { 'X-Forwarded-For': '203.0.113.14' },
+    },
+  );
+  await expectHttp(
+    baseUrl,
+    '/api/slow',
+    504,
+    'GATEWAY_UPSTREAM_TIMEOUT',
+    'API 上游读取超时返回稳定 JSON',
+    {
+      headers: { 'X-Forwarded-For': '203.0.113.15' },
+      timeoutMs: 5000,
+    },
+  );
+
+  await expectHttp(
+    baseUrl,
+    '/v1/identity',
+    200,
+    '"upstream":"spacetime"',
+    'SpacetimeDB identity 转发',
+  );
+  await expectWebSocketUpgrade(
+    baseUrl,
+    '/v1/database/genarrative/subscribe',
+    spacetime,
+  );
+
+  const giteaBeforeRequests = gitea.state.requests.length;
+  const giteaResponse = await expectHttp(
+    baseUrl,
+    '/api/v1/repos/GenarrativeAI/Genarrative',
+    200,
+    '"upstream":"gitea"',
+    'Gitea Host 路由转发',
+    {
+      headers: {
+        Host: 'git.genarrative.world:443',
+        'X-Request-Id': 'gitea-host-request-id',
+      },
+    },
+  );
+  const giteaPayload = JSON.parse(giteaResponse.body || '{}');
+  ensure(
+    giteaPayload.host === 'git.genarrative.world:443',
+    `Gitea 上游 Host 未透传：${giteaPayload.host || '-'}`,
+  );
+  ensure(
+    giteaPayload.forwardedHost === 'git.genarrative.world:443',
+    `Gitea 上游 X-Forwarded-Host 未透传：${giteaPayload.forwardedHost || '-'}`,
+  );
+  ensure(
+    giteaPayload.forwardedProto === 'https',
+    `Gitea 上游 X-Forwarded-Proto 未对齐：${giteaPayload.forwardedProto || '-'}`,
+  );
+  await expectHttp(
+    baseUrl,
+    '/api/v1/repos/GenarrativeAI/Genarrative',
+    200,
+    '"upstream":"gitea"',
+    'Gitea Host 别名路由转发',
+    {
+      headers: {
+        Host: 'git-alias.genarrative.world',
+      },
+    },
+  );
+  ensure(
+    gitea.state.requests.length === giteaBeforeRequests + 2,
+    `Gitea Host 路由没有稳定打到 Gitea mock：${gitea.state.requests.length - giteaBeforeRequests}`,
+  );
+
+  await expectAccessLog(accessLogFile);
+  await expectAccessLogEntries(accessLogFile, [
+    {
+      requestId: 'static-etag-304-request-id',
+      method: 'GET',
+      path: '/assets/app.js',
+      status: 304,
+    },
+    {
+      requestId: 'static-last-modified-304-request-id',
+      method: 'GET',
+      path: '/assets/app.js',
+      status: 304,
+    },
+    {
+      requestId: 'static-method-405-request-id',
+      method: 'POST',
+      path: '/assets/app.js',
+      status: 405,
+    },
+    {
+      requestId: 'static-range-206-request-id',
+      method: 'GET',
+      path: '/assets/app.js',
+      status: 206,
+    },
+    {
+      requestId: 'static-range-416-request-id',
+      method: 'GET',
+      path: '/assets/app.js',
+      status: 416,
+    },
+    {
+      requestId: 'static-head-range-206-request-id',
+      method: 'HEAD',
+      path: '/assets/app.js',
+      status: 206,
+    },
+    {
+      requestId: 'gitea-host-request-id',
+      method: 'GET',
+      path: '/api/v1/repos/GenarrativeAI/Genarrative',
+      status: 200,
+      proxyTarget: 'Gitea',
+    },
+  ]);
+
+  await mkdir(path.dirname(maintenanceFile), { recursive: true });
+  await writeFile(maintenanceFile, 'enabled');
+  const giteaRequestsBeforeMaintenance = gitea.state.requests.length;
+  await expectHttp(
+    baseUrl,
+    '/user/login',
+    200,
+    '"upstream":"gitea"',
+    '维护模式不拦截 Gitea Host',
+    {
+      headers: {
+        Host: 'git.genarrative.world',
+      },
+    },
+  );
+  ensure(
+    gitea.state.requests.length === giteaRequestsBeforeMaintenance + 1,
+    '维护模式 Gitea Host 请求没有打到 Gitea mock',
+  );
+  await expectHttp(
+    baseUrl,
+    '/api/creation-entry/config',
+    503,
+    'MAINTENANCE',
+    '维护模式 API JSON',
+  );
+  await expectHttp(baseUrl, '/', 503, 'maintenance', '维护模式 Web 页面');
+  await expectAccessLogContains(accessLogFile, [
+    'status=503',
+    'path=/api/creation-entry/config',
+  ]);
+}
+
+async function expectAccessLog(accessLogFile) {
+  console.log('[pingora-gateway-smoke] access log 落盘');
+  await waitForCondition(async () => {
+    try {
+      const content = await readFile(accessLogFile, 'utf8');
+      return (
+        content.includes('request_id=smoke-request-id') &&
+        content.includes('method=GET') &&
+        content.includes('path=/api/creation-entry/config') &&
+        content.includes('status=200') &&
+        content.includes('proxy_target=Api') &&
+        content.includes('protection_class=api') &&
+        content.includes('status=429') &&
+        content.includes('status=502') &&
+        content.includes('status=504')
+      );
+    } catch {
+      return false;
+    }
+  });
+}
+
+function assertStaticValidatorHeaders(response, label) {
+  ensure(Boolean(response.headers.etag), `${label}: 缺少 ETag`);
+  ensure(
+    /^W\/"[0-9a-f]+-[0-9a-f]+"$/iu.test(String(response.headers.etag || '')),
+    `${label}: ETag 格式不符合静态弱校验器口径：${response.headers.etag || '-'}`,
+  );
+  ensure(Boolean(response.headers['last-modified']), `${label}: 缺少 Last-Modified`);
+  ensure(
+    Number.isFinite(Date.parse(response.headers['last-modified'] || '')),
+    `${label}: Last-Modified 不是有效 HTTP 日期：${response.headers['last-modified'] || '-'}`,
+  );
+}
+
+async function expectStaticNotModifiedByEtag(
+  baseUrl,
+  route,
+  sourceResponse,
+  options = {},
+) {
+  await expectHttp(
+    baseUrl,
+    route,
+    304,
+    '',
+    '静态资源 If-None-Match 返回 304',
+    {
+      headers: {
+        'If-None-Match': sourceResponse.headers.etag,
+        ...(options.headers || {}),
+      },
+      validate: (response) =>
+        response.body === '' &&
+        response.headers.etag === sourceResponse.headers.etag &&
+        response.headers['cache-control'] ===
+          sourceResponse.headers['cache-control'],
+    },
+  );
+}
+
+async function expectStaticNotModifiedByLastModified(
+  baseUrl,
+  route,
+  sourceResponse,
+  options = {},
+) {
+  await expectHttp(
+    baseUrl,
+    route,
+    304,
+    '',
+    '静态资源 If-Modified-Since 返回 304',
+    {
+      headers: {
+        'If-Modified-Since': sourceResponse.headers['last-modified'],
+        ...(options.headers || {}),
+      },
+      validate: (response) =>
+        response.body === '' &&
+        response.headers['last-modified'] ===
+          sourceResponse.headers['last-modified'] &&
+        response.headers['cache-control'] ===
+          sourceResponse.headers['cache-control'],
+    },
+  );
+}
+
+async function expectStaticRange(
+  baseUrl,
+  route,
+  range,
+  status,
+  bodyNeedle,
+  contentRange,
+  label,
+  options = {},
+) {
+  const headers = {
+    Range: range,
+    'Accept-Encoding': 'gzip',
+    ...(options.headers || {}),
+  };
+  await expectHttp(baseUrl, route, status, bodyNeedle, label, {
+    method: options.method,
+    headers,
+    validate: (response) =>
+      response.headers['accept-ranges'] === 'bytes' &&
+      response.headers['content-range'] === contentRange &&
+      !response.headers['content-encoding'] &&
+      (options.method === 'HEAD' ? response.body === '' : true) &&
+      (status === 206
+        ? Number(response.headers['content-length']) ===
+          (options.expectedContentLength ?? Buffer.byteLength(bodyNeedle))
+        : Number(response.headers['content-length']) === 0),
+  });
+}
+
+async function expectStaticRangeFallback(baseUrl, route, range, ifRange, label) {
+  await expectHttp(baseUrl, route, 200, 'site asset', label, {
+    headers: {
+      Range: range,
+      'If-Range': ifRange,
+      'Accept-Encoding': 'gzip',
+    },
+    validate: (response) =>
+      response.headers['accept-ranges'] === 'bytes' &&
+      !response.headers['content-range'] &&
+      Number(response.headers['content-length']) ===
+        Buffer.byteLength('console.log("site asset");\n'),
+  });
+}
+
+async function expectGzipResponse(baseUrl, route, bodyNeedle, options = {}) {
+  return expectCompressedResponse(baseUrl, route, bodyNeedle, {
+    acceptEncoding: options.acceptEncoding || 'gzip',
+    contentEncoding: 'gzip',
+    decode: (bodyBuffer) => gunzipSync(bodyBuffer).toString('utf8'),
+    label: options.label || 'gzip 压缩响应',
+  });
+}
+
+async function expectNotCompressedResponse(baseUrl, route, bodyNeedle, label) {
+  console.log(`[pingora-gateway-smoke] ${label}`);
+  const response = await requestHttp(`${baseUrl}${route}`, {
+    headers: {
+      'Accept-Encoding': 'gzip',
+    },
+    rawBody: true,
+  });
+
+  if (response.status !== 200) {
+    failures.push(`${label}: 期望 HTTP 200，实际 ${response.status}`);
+    return;
+  }
+  if (response.headers['content-encoding']) {
+    failures.push(
+      `${label}: 不应返回 Content-Encoding，实际 ${response.headers['content-encoding']}`,
+    );
+  }
+  const body = response.bodyBuffer.toString('utf8');
+  if (bodyNeedle && !body.includes(bodyNeedle)) {
+    failures.push(`${label}: 响应体缺少 ${bodyNeedle}`);
+  }
+}
+
+async function expectStaticPng(baseUrl, route, label) {
+  console.log(`[pingora-gateway-smoke] ${label}`);
+  const response = await requestHttp(`${baseUrl}${route}`, {
+    rawBody: true,
+  });
+
+  if (response.status !== 200) {
+    failures.push(`${label}: 期望 HTTP 200，实际 ${response.status}`);
+    return;
+  }
+  if (!String(response.headers['content-type'] || '').startsWith('image/png')) {
+    failures.push(
+      `${label}: 期望 Content-Type=image/png，实际 ${response.headers['content-type'] || '-'}`,
+    );
+  }
+  if (!response.bodyBuffer.subarray(0, 8).equals(PNG_MAGIC_BYTES)) {
+    failures.push(`${label}: 响应体不是 PNG magic bytes`);
+  }
+  if (response.body.includes('<!doctype html>')) {
+    failures.push(`${label}: 命中了 SPA fallback HTML`);
+  }
+}
+
+async function expectRawPathHttp(baseUrl, route, status, bodyNeedle, label) {
+  console.log(`[pingora-gateway-smoke] ${label}`);
+  let response;
+  try {
+    response = await rawHttpPathRequest(baseUrl, route);
+  } catch (error) {
+    failures.push(
+      `${label}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return;
+  }
+
+  if (response.status !== status) {
+    failures.push(`${label}: 期望 HTTP ${status}，实际 ${response.status}`);
+  }
+  if (bodyNeedle && !response.body.includes(bodyNeedle)) {
+    failures.push(`${label}: 响应体缺少 ${bodyNeedle}`);
+  }
+}
+
+async function expectCompressedResponse(baseUrl, route, bodyNeedle, options) {
+  const label = options.label;
+  console.log(`[pingora-gateway-smoke] ${label}`);
+  const response = await requestHttp(`${baseUrl}${route}`, {
+    headers: {
+      'Accept-Encoding': options.acceptEncoding,
+    },
+    rawBody: true,
+  });
+
+  if (response.status !== 200) {
+    failures.push(`${label}: 期望 HTTP 200，实际 ${response.status}`);
+    return;
+  }
+  if (response.headers['content-encoding'] !== options.contentEncoding) {
+    failures.push(
+      `${label}: 缺少 Content-Encoding=${options.contentEncoding}，实际 ${response.headers['content-encoding'] || '-'}`,
+    );
+  }
+  if (
+    !String(response.headers.vary || '')
+      .toLowerCase()
+      .includes('accept-encoding')
+  ) {
+    failures.push(
+      `${label}: 缺少 Vary: Accept-Encoding，实际 ${response.headers.vary || '-'}`,
+    );
+  }
+
+  let decoded = '';
+  try {
+    decoded = options.decode(response.bodyBuffer);
+  } catch (error) {
+    failures.push(
+      `${label}: 解压失败：${error instanceof Error ? error.message : String(error)}`,
+    );
+    return;
+  }
+  if (!decoded.includes(bodyNeedle)) {
+    failures.push(`${label}: 解压后内容缺少 ${bodyNeedle}`);
+  }
+}
+
+async function expectAccessLogContains(accessLogFile, needles) {
+  await waitForCondition(async () => {
+    try {
+      const content = await readFile(accessLogFile, 'utf8');
+      return needles.every((needle) => content.includes(needle));
+    } catch {
+      return false;
+    }
+  });
+}
+
+async function expectAccessLogEntries(accessLogFile, expectedEntries) {
+  console.log('[pingora-gateway-smoke] access log 静态边界状态对账');
+  await waitForCondition(async () => {
+    try {
+      const content = await readFile(accessLogFile, 'utf8');
+      const entries = content.split(/\r?\n/u).filter(Boolean).map(parseAccessLogLine);
+      return expectedEntries.every((expected) => {
+        const entry = entries.find((item) => item.request_id === expected.requestId);
+        return (
+          entry &&
+          entry.method === expected.method &&
+          entry.path === expected.path &&
+          Number.parseInt(entry.status || '', 10) === expected.status &&
+          entry.proxy_target === (expected.proxyTarget || 'Local')
+        );
+      });
+    } catch {
+      return false;
+    }
+  });
+}
+
+function parseAccessLogLine(line) {
+  const fields = {};
+  for (const part of line.split('\t')) {
+    const separator = part.indexOf('=');
+    if (separator <= 0) {
+      continue;
+    }
+    fields[part.slice(0, separator)] = unescapeAccessLogValue(
+      part.slice(separator + 1),
+    );
+  }
+  return fields;
+}
+
+function unescapeAccessLogValue(value) {
+  return value
+    .replace(/\\\\/gu, '\\')
+    .replace(/\\t/gu, '\t')
+    .replace(/\\n/gu, '\n')
+    .replace(/\\r/gu, '\r');
+}
+
+async function expectHttp(
+  baseUrl,
+  route,
+  status,
+  bodyNeedle,
+  label,
+  options = {},
+) {
+  console.log(`[pingora-gateway-smoke] ${label}`);
+  const pending = options.beforeRequest
+    ? await options.beforeRequest()
+    : undefined;
+  let response;
+  try {
+    response = await requestHttp(`${baseUrl}${route}`, {
+      method: options.method,
+      headers: options.headers,
+      body: options.body,
+      insecureTls: options.insecureTls,
+    });
+  } catch (error) {
+    failures.push(
+      `${label}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  } finally {
+    if (options.afterRequest) {
+      try {
+        await options.afterRequest(pending);
+      } catch (error) {
+        failures.push(error instanceof Error ? error.message : String(error));
+      }
+    }
+  }
+
+  if (!response) {
+    return { status: 0, headers: {}, body: '' };
+  }
+
+  if (config.verbose) {
+    console.log(`[pingora-gateway-smoke] ${label} -> HTTP ${response.status}`);
+  }
+
+  if (response.status !== status) {
+    failures.push(`${label}: 期望 HTTP ${status}，实际 ${response.status}`);
+  }
+
+  if (bodyNeedle && !response.body.includes(bodyNeedle)) {
+    failures.push(`${label}: 响应体缺少 ${bodyNeedle}`);
+  }
+
+  if (options.validate && !options.validate(response)) {
+    failures.push(`${label}: 自定义响应校验未通过`);
+  }
+
+  return response;
+}
+
+async function expectChunkedLimit(baseUrl, route) {
+  console.log('[pingora-gateway-smoke] chunked body limit');
+  const response = await new Promise((resolve, reject) => {
+    const request = http.request(
+      `${baseUrl}${route}`,
+      {
+        method: 'POST',
+        headers: {
+          'Transfer-Encoding': 'chunked',
+          'X-Forwarded-For': '203.0.113.11',
+        },
+      },
+      (incoming) => {
+        collectIncoming(incoming).then(resolve, reject);
+      },
+    );
+    request.on('error', reject);
+    request.write('012345');
+    request.write('6789abcdef');
+    request.end();
+  });
+
+  if (response.status !== 413 || !response.body.includes('PAYLOAD_TOO_LARGE')) {
+    failures.push(
+      `chunked body limit: 期望 413 PAYLOAD_TOO_LARGE，实际 ${response.status} ${response.body}`,
+    );
+  }
+}
+
+async function expectConcurrencyLimit(baseUrl, api) {
+  console.log('[pingora-gateway-smoke] API 并发保护');
+  const hold = await openRawHttpRequest(`${baseUrl}/admin/api/hold`, {
+    'X-Forwarded-For': '203.0.113.12',
+  });
+
+  try {
+    await waitForCondition(() => typeof api.state.releaseHold === 'function');
+    const beforeLimitedRequestCount = api.state.requests.length;
+    const response = await rawHttpRequest(`${baseUrl}/admin/api/users`, {
+      'X-Forwarded-For': '203.0.113.12',
+    });
+
+    if (response.status !== 429) {
+      failures.push(`API 并发保护: 期望 HTTP 429，实际 ${response.status}`);
+    }
+    if (!response.body.includes('GATEWAY_CONCURRENCY_LIMITED')) {
+      failures.push('API 并发保护: 响应体缺少 GATEWAY_CONCURRENCY_LIMITED');
+    }
+    ensure(
+      api.state.requests.length === beforeLimitedRequestCount,
+      `API 并发保护的 429 请求不应打到上游，上游请求为 ${describeRequests(api.state.requests.slice(beforeLimitedRequestCount))}`,
+    );
+  } finally {
+    api.state.releaseHold?.();
+    hold.socket.end();
+    const holdResponse = await hold.done.catch((error) => ({ error }));
+    if (holdResponse?.error) {
+      failures.push(
+        `API 并发保护: hold 请求失败：${holdResponse.error.message}`,
+      );
+    }
+  }
+}
+
+async function expectWebSocketUpgrade(baseUrl, route, spacetime) {
+  console.log('[pingora-gateway-smoke] SpacetimeDB WebSocket Upgrade');
+  const url = new URL(route, baseUrl);
+  const key = randomBytes(16).toString('base64');
+  const response = await new Promise((resolve, reject) => {
+    const socket = net.connect(
+      { host: url.hostname, port: Number(url.port) },
+      () => {
+        socket.write(
+          [
+            `GET ${url.pathname} HTTP/1.1`,
+            `Host: ${url.host}`,
+            'Upgrade: websocket',
+            'Connection: Upgrade',
+            `Sec-WebSocket-Key: ${key}`,
+            'Sec-WebSocket-Version: 13',
+            '',
+            '',
+          ].join('\r\n'),
+        );
+      },
+    );
+
+    let raw = Buffer.alloc(0);
+    let settled = false;
+    const timeout = setTimeout(() => {
+      settled = true;
+      socket.destroy();
+      reject(new Error('WebSocket Upgrade 超时'));
+    }, 5000);
+
+    socket.on('data', (chunk) => {
+      raw = Buffer.concat([raw, chunk]);
+      const text = raw.toString('latin1');
+      if (text.includes('\r\n\r\n') && text.includes('spacetime-upgrade-ok')) {
+        settled = true;
+        clearTimeout(timeout);
+        socket.destroy();
+        resolve(raw);
+      }
+    });
+    socket.on('error', (error) => {
+      settled = true;
+      clearTimeout(timeout);
+      reject(error);
+    });
+    socket.on('close', () => {
+      clearTimeout(timeout);
+      if (!settled) {
+        reject(new Error('WebSocket Upgrade 连接提前关闭'));
+      }
+    });
+  });
+
+  const text = response.toString('latin1');
+  ensure(
+    text.startsWith('HTTP/1.1 101'),
+    `WebSocket Upgrade 未返回 101：${text.split('\r\n')[0] || text}`,
+  );
+  ensure(
+    text.includes('spacetime-upgrade-ok'),
+    'WebSocket tunnel 未收到上游 welcome frame',
+  );
+  const upgradeRequest = spacetime.state.requests.find(
+    (request) =>
+      request.url === route && request.headers.upgrade === 'websocket',
+  );
+  ensure(
+    Boolean(upgradeRequest),
+    'SpacetimeDB mock 未收到 WebSocket Upgrade 请求',
+  );
+}
+
+function requestHttp(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const headers = { ...(options.headers || {}) };
+    if (
+      options.body !== undefined &&
+      !hasHeader(headers, 'content-length') &&
+      !hasHeader(headers, 'transfer-encoding')
+    ) {
+      headers['Content-Length'] = Buffer.byteLength(String(options.body));
+    }
+    const client = url.startsWith('https:') ? https : http;
+    const request = client.request(
+      url,
+      {
+        method: options.method || 'GET',
+        headers,
+        agent: false,
+        rejectUnauthorized: options.insecureTls ? false : undefined,
+      },
+      (incoming) => {
+        collectIncoming(incoming).then(resolve, reject);
+      },
+    );
+    const timeout = setTimeout(() => {
+      request.destroy(new Error(`HTTP 请求超时：${url}`));
+    }, options.timeoutMs || 5000);
+    request.on('error', reject);
+    request.on('close', () => {
+      clearTimeout(timeout);
+    });
+    if (options.body !== undefined) {
+      request.write(options.body);
+    }
+    request.end();
+  });
+}
+
+function openRawHttpRequest(url, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const socket = net.connect(
+      { host: target.hostname, port: Number(target.port) },
+      () => {
+        socket.write(buildRawHttpRequest(target, headers));
+        resolve({
+          socket,
+          done: collectRawHttpResponse(socket, url, 35000),
+        });
+      },
+    );
+    socket.on('error', reject);
+  });
+}
+
+async function rawHttpRequest(url, headers = {}) {
+  const request = await openRawHttpRequest(url, headers);
+  return request.done.finally(() => {
+    request.socket.destroy();
+  });
+}
+
+function rawHttpPathRequest(baseUrl, route, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(baseUrl);
+    const socket = net.connect(
+      { host: target.hostname, port: Number(target.port) },
+      () => {
+        socket.write(buildRawHttpPathRequest(target, route, headers));
+        collectRawHttpResponse(socket, `${baseUrl}${route}`, 35000)
+          .then(resolve, reject)
+          .finally(() => socket.destroy());
+      },
+    );
+    socket.on('error', reject);
+  });
+}
+
+function buildRawHttpRequest(target, headers) {
+  const mergedHeaders = {
+    Host: target.host,
+    Connection: 'close',
+    ...headers,
+  };
+  const headerLines = Object.entries(mergedHeaders).map(
+    ([name, value]) => `${name}: ${value}`,
+  );
+  return [
+    `GET ${target.pathname}${target.search} HTTP/1.1`,
+    ...headerLines,
+    '',
+    '',
+  ].join('\r\n');
+}
+
+function buildRawHttpPathRequest(target, route, headers) {
+  const mergedHeaders = {
+    Host: target.host,
+    Connection: 'close',
+    ...headers,
+  };
+  const headerLines = Object.entries(mergedHeaders).map(
+    ([name, value]) => `${name}: ${value}`,
+  );
+  return [`GET ${route} HTTP/1.1`, ...headerLines, '', ''].join('\r\n');
+}
+
+function collectRawHttpResponse(socket, url, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let raw = Buffer.alloc(0);
+    let settled = false;
+    const timer = setTimeout(() => {
+      settled = true;
+      socket.destroy();
+      reject(new Error(`HTTP 请求超时：${url}`));
+    }, timeoutMs);
+
+    socket.on('data', (chunk) => {
+      raw = Buffer.concat([raw, chunk]);
+      let parsed;
+      try {
+        parsed = tryParseRawHttpResponse(raw);
+      } catch (error) {
+        settled = true;
+        clearTimeout(timer);
+        socket.destroy();
+        reject(error);
+        return;
+      }
+      if (parsed) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(parsed);
+      }
+    });
+    socket.on('error', (error) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(error);
+      }
+    });
+    socket.on('close', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        try {
+          const parsed = tryParseRawHttpResponse(raw, { final: true });
+          if (parsed) {
+            resolve(parsed);
+          } else {
+            reject(new Error(`HTTP 响应提前关闭：${url}`));
+          }
+        } catch (error) {
+          reject(error);
+        }
+      }
+    });
+  });
+}
+
+function tryParseRawHttpResponse(raw, options = {}) {
+  const headerEnd = raw.indexOf('\r\n\r\n');
+  if (headerEnd < 0) {
+    return null;
+  }
+
+  const headerText = raw.slice(0, headerEnd).toString('latin1');
+  const [statusLine, ...headerLines] = headerText.split('\r\n');
+  const status = Number.parseInt(statusLine.split(' ')[1] || '0', 10);
+  const headers = {};
+  for (const line of headerLines) {
+    const separator = line.indexOf(':');
+    if (separator <= 0) {
+      continue;
+    }
+    headers[line.slice(0, separator).trim().toLowerCase()] = line
+      .slice(separator + 1)
+      .trim();
+  }
+
+  const bodyStart = headerEnd + 4;
+  const body = raw.slice(bodyStart);
+  if (hasToken(headers['transfer-encoding'], 'chunked')) {
+    const decoded = decodeChunkedBody(body);
+    if (!decoded.complete) {
+      return null;
+    }
+
+    return {
+      status,
+      headers,
+      body: decoded.body.toString('utf8'),
+    };
+  }
+
+  const contentLength = Number.parseInt(headers['content-length'] || '', 10);
+  if (Number.isFinite(contentLength) && body.length < contentLength) {
+    return null;
+  }
+  if (Number.isFinite(contentLength)) {
+    return {
+      status,
+      headers,
+      body: body.slice(0, contentLength).toString('utf8'),
+    };
+  }
+
+  if (!options.final) {
+    return null;
+  }
+
+  return {
+    status,
+    headers,
+    body: body.toString('utf8'),
+  };
+}
+
+function hasToken(value, expected) {
+  if (!value) {
+    return false;
+  }
+  const normalized = expected.toLowerCase();
+  return value
+    .split(',')
+    .map((token) => token.trim().toLowerCase())
+    .includes(normalized);
+}
+
+function decodeChunkedBody(body) {
+  let offset = 0;
+  const chunks = [];
+
+  while (offset < body.length) {
+    const lineEnd = body.indexOf('\r\n', offset);
+    if (lineEnd < 0) {
+      return { complete: false, body: Buffer.alloc(0) };
+    }
+
+    const sizeLine = body.slice(offset, lineEnd).toString('latin1');
+    const sizeText = sizeLine.split(';')[0]?.trim() || '';
+    const size = Number.parseInt(sizeText, 16);
+    if (!Number.isFinite(size)) {
+      throw new Error(`无法解析 chunked 响应大小：${sizeLine}`);
+    }
+
+    offset = lineEnd + 2;
+    if (size === 0) {
+      const trailerEnd = body.indexOf('\r\n\r\n', offset);
+      if (trailerEnd >= 0) {
+        return { complete: true, body: Buffer.concat(chunks) };
+      }
+      if (body.slice(offset, offset + 2).toString('latin1') === '\r\n') {
+        return { complete: true, body: Buffer.concat(chunks) };
+      }
+      return { complete: false, body: Buffer.alloc(0) };
+    }
+
+    const chunkStart = offset;
+    const chunkEnd = chunkStart + size;
+    const nextChunkStart = chunkEnd + 2;
+    if (body.length < nextChunkStart) {
+      return { complete: false, body: Buffer.alloc(0) };
+    }
+    if (body.slice(chunkEnd, nextChunkStart).toString('latin1') !== '\r\n') {
+      throw new Error('chunked 响应缺少 chunk 结束换行');
+    }
+
+    chunks.push(body.slice(chunkStart, chunkEnd));
+    offset = nextChunkStart;
+  }
+
+  return { complete: false, body: Buffer.alloc(0) };
+}
+
+function hasHeader(headers, name) {
+  const expected = name.toLowerCase();
+  return Object.keys(headers).some((key) => key.toLowerCase() === expected);
+}
+
+function collectIncoming(incoming, options = {}) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    incoming.on('data', (chunk) => chunks.push(chunk));
+    incoming.on('error', reject);
+    incoming.on('end', () => {
+      const bodyBuffer = Buffer.concat(chunks);
+      resolve({
+        status: incoming.statusCode || 0,
+        headers: incoming.headers,
+        body: options.rawBody ? '' : bodyBuffer.toString('utf8'),
+        bodyBuffer,
+      });
+    });
+  });
+}
+
+function readRequestBody(request) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    request.on('data', (chunk) => chunks.push(chunk));
+    request.on('error', reject);
+    request.on('end', () => resolve(Buffer.concat(chunks)));
+  });
+}
+
+function listen(server) {
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.on('connection', (socket) => {
+      sockets.add(socket);
+      socket.on('close', () => {
+        sockets.delete(socket);
+      });
+    });
+    server.listen(0, '127.0.0.1', () => {
+      servers.push(server);
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        reject(new Error('无法读取 mock server 端口'));
+        return;
+      }
+      resolve(address.port);
+    });
+  });
+}
+
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        server.close();
+        reject(new Error('无法分配临时端口'));
+        return;
+      }
+      const { port } = address;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+async function waitForHttp(url, expectedStatus) {
+  const startedAt = Date.now();
+  let lastError = '';
+  while (Date.now() - startedAt < 10000) {
+    try {
+      const response = await requestHttp(url);
+      if (response.status === expectedStatus) {
+        return;
+      }
+      lastError = `HTTP ${response.status}`;
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+    }
+    await delay(100);
+  }
+  throw new Error(`等待 Pingora 网关就绪超时：${lastError}`);
+}
+
+function runCommand(command, args) {
+  console.log(
+    `[pingora-gateway-smoke] ${command} ${redactSecretArgs(args).join(' ')}`,
+  );
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    env: smokeEnv(),
+    shell: false,
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    throw new Error(`${command} 启动失败：${result.error.message}`);
+  }
+  if (result.signal) {
+    throw new Error(`${command} 被信号终止：${result.signal}`);
+  }
+  if ((result.status ?? 0) !== 0) {
+    throw new Error(
+      `${command} ${redactSecretArgs(args).join(' ')} 退出码 ${result.status}`,
+    );
+  }
+}
+
+async function runDirectLiveSmoke(tlsBaseUrl, redirectBaseUrl, probeToken, accessLogFile) {
+  const output = await runCommandAsync('node', [
+    'scripts/check-pingora-direct-live.mjs',
+    '--https-base-url',
+    tlsBaseUrl,
+    '--http-base-url',
+    redirectBaseUrl,
+    '--host',
+    new URL(tlsBaseUrl).host,
+    '--probe-token',
+    probeToken,
+    '--pingora-access-log',
+    accessLogFile,
+    '--redirect-host',
+    new URL(tlsBaseUrl).host,
+    '--spacetime-database',
+    'genarrative',
+    '--require-wss-upgrade',
+    '--insecure-tls',
+    '--json',
+  ]);
+  assertDirectLiveAccessLogEvidence(output.stdout);
+}
+
+function runCommandAsync(command, args) {
+  console.log(
+    `[pingora-gateway-smoke] ${command} ${redactSecretArgs(args).join(' ')}`,
+  );
+  return new Promise((resolve, reject) => {
+    let stdout = '';
+    let stderr = '';
+    const child = spawn(command, args, {
+      cwd: repoRoot,
+      env: smokeEnv(),
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    child.stdout?.on('data', (chunk) => {
+      const text = String(chunk);
+      stdout += text;
+      process.stdout.write(text);
+    });
+    child.stderr?.on('data', (chunk) => {
+      const text = String(chunk);
+      stderr += text;
+      process.stderr.write(text);
+    });
+    child.on('error', (error) => {
+      reject(new Error(`${command} 启动失败：${error.message}`));
+    });
+    child.on('exit', (status, signal) => {
+      if (signal) {
+        reject(new Error(`${command} 被信号终止：${signal}`));
+        return;
+      }
+      if ((status ?? 0) !== 0) {
+        reject(
+          new Error(
+            `${command} ${redactSecretArgs(args).join(' ')} 退出码 ${status}\nstdout:\n${stdout}\nstderr:\n${stderr}`,
+          ),
+        );
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+function assertDirectLiveAccessLogEvidence(stdout) {
+  const payload = extractJsonObject(stdout, stdout.indexOf('{'));
+  if (!payload) {
+    failures.push('direct live JSON 输出缺失。');
+    return;
+  }
+  let result;
+  try {
+    result = JSON.parse(payload);
+  } catch (error) {
+    failures.push(
+      `direct live JSON 输出无法解析：${error instanceof Error ? error.message : String(error)}`,
+    );
+    return;
+  }
+  const accessLogCheck = result.results?.find(
+    (item) => item.name === 'direct-access-log',
+  );
+  const staticAssetCheck = result.results?.find(
+    (item) => item.name === 'https-static-asset',
+  );
+  ensure(
+    staticAssetCheck?.fingerprinted?.statusCode === 200,
+    'direct live 必须验证首页引用的指纹静态资源 GET 200。',
+  );
+  ensure(
+    staticAssetCheck?.fingerprinted?.head?.statusCode === 200,
+    'direct live 必须验证首页引用的指纹静态资源 HEAD 200。',
+  );
+  ensure(
+    staticAssetCheck?.fingerprinted?.range?.statusCode === 206,
+    'direct live 必须验证首页引用的指纹静态资源 Range 206。',
+  );
+  ensure(
+    staticAssetCheck?.headers?.['cache-control'] === 'no-cache',
+    'direct live JSON 必须保留普通静态资源 Cache-Control 证据。',
+  );
+  ensure(
+    Boolean(staticAssetCheck?.headers?.etag),
+    'direct live JSON 必须保留普通静态资源 ETag 证据。',
+  );
+  ensure(
+    staticAssetCheck?.range?.headers?.['content-range']?.startsWith('bytes 0-0/'),
+    'direct live JSON 必须保留普通静态资源 Content-Range 证据。',
+  );
+  ensure(
+    staticAssetCheck?.fingerprinted?.headers?.['cache-control'] ===
+      'public, max-age=31536000, immutable',
+    'direct live JSON 必须保留指纹静态资源 immutable Cache-Control 证据。',
+  );
+  ensure(
+    Boolean(staticAssetCheck?.fingerprinted?.headers?.etag),
+    'direct live JSON 必须保留指纹静态资源 ETag 证据。',
+  );
+  ensure(
+    staticAssetCheck?.fingerprinted?.range?.headers?.['content-range']?.startsWith(
+      'bytes 0-0/',
+    ),
+    'direct live JSON 必须保留指纹静态资源 Content-Range 证据。',
+  );
+  ensure(
+    staticAssetCheck?.notModified?.etag?.statusCode === 304,
+    'direct live 必须验证首页引用的静态资源 ETag 304。',
+  );
+  ensure(
+    staticAssetCheck?.notModified?.lastModified?.statusCode === 304,
+    'direct live 必须验证首页引用的静态资源 Last-Modified 304。',
+  );
+  ensure(
+    staticAssetCheck?.fingerprinted?.notModified?.etag?.statusCode === 304,
+    'direct live 必须验证首页引用的指纹静态资源 ETag 304。',
+  );
+  ensure(
+    staticAssetCheck?.fingerprinted?.notModified?.lastModified?.statusCode === 304,
+    'direct live 必须验证首页引用的指纹静态资源 Last-Modified 304。',
+  );
+  ensure(
+    staticAssetCheck?.notModified?.etag?.headers?.['cache-control'] ===
+      staticAssetCheck?.headers?.['cache-control'],
+    'direct live JSON 必须保留普通静态 304 Cache-Control 证据。',
+  );
+  ensure(
+    staticAssetCheck?.fingerprinted?.notModified?.etag?.headers?.['cache-control'] ===
+      staticAssetCheck?.fingerprinted?.headers?.['cache-control'],
+    'direct live JSON 必须保留指纹静态 304 Cache-Control 证据。',
+  );
+  if (!accessLogCheck) {
+    failures.push('direct live JSON 缺少 direct-access-log 检查结果。');
+    return;
+  }
+  ensure(accessLogCheck.checked >= 10, 'direct live access log 检查请求数不足。');
+  ensure(
+    accessLogCheck.matchedCount === accessLogCheck.checked,
+    'direct live access log matchedCount 必须等于 checked。',
+  );
+  ensure(
+    accessLogCheck.missingCount === 0,
+    'direct live access log 不应缺少 request_id。',
+  );
+  ensure(
+    accessLogCheck.mismatchCount === 0,
+    'direct live access log 不应出现 method/path/status 漂移。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.matched) &&
+      accessLogCheck.matched.some(
+        (item) =>
+          item.name === 'wss-spacetime-subscribe' &&
+          item.expectedMethod === 'GET' &&
+          item.actualMethod === 'GET' &&
+          item.expectedStatusCode === 101 &&
+          item.actualStatusCode === 101,
+      ),
+    'direct live access log 必须保留 WSS 101 的 method/path/status 明细。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.matched) &&
+      accessLogCheck.matched.some(
+        (item) =>
+          item.name === 'https-static-asset-head' &&
+          item.expectedMethod === 'HEAD' &&
+          item.actualMethod === 'HEAD' &&
+          item.expectedStatusCode === 200 &&
+          item.actualStatusCode === 200,
+      ),
+    'direct live access log 必须保留静态 HEAD 的 method/path/status 明细。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.matched) &&
+      accessLogCheck.matched.some(
+        (item) =>
+          item.name === 'https-static-fingerprinted-asset' &&
+          item.expectedMethod === 'GET' &&
+          item.actualMethod === 'GET' &&
+          item.expectedStatusCode === 200 &&
+          item.actualStatusCode === 200,
+      ),
+    'direct live access log 必须保留指纹静态 GET 的 method/path/status 明细。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.matched) &&
+      accessLogCheck.matched.some(
+        (item) =>
+          item.name === 'https-static-fingerprinted-asset-head' &&
+          item.expectedMethod === 'HEAD' &&
+          item.actualMethod === 'HEAD' &&
+          item.expectedStatusCode === 200 &&
+          item.actualStatusCode === 200,
+      ),
+    'direct live access log 必须保留指纹静态 HEAD 的 method/path/status 明细。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.matched) &&
+      accessLogCheck.matched.some(
+        (item) =>
+          item.name === 'https-static-fingerprinted-asset-range' &&
+          item.expectedMethod === 'GET' &&
+          item.actualMethod === 'GET' &&
+          item.expectedStatusCode === 206 &&
+          item.actualStatusCode === 206,
+      ),
+    'direct live access log 必须保留指纹静态 Range 的 method/path/status 明细。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.matched) &&
+      accessLogCheck.matched.some(
+        (item) =>
+          item.name === 'https-static-asset-etag-304' &&
+          item.expectedMethod === 'GET' &&
+          item.actualMethod === 'GET' &&
+          item.expectedStatusCode === 304 &&
+          item.actualStatusCode === 304,
+      ),
+    'direct live access log 必须保留静态 ETag 304 的 method/path/status 明细。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.matched) &&
+      accessLogCheck.matched.some(
+        (item) =>
+          item.name === 'https-static-fingerprinted-asset-etag-304' &&
+          item.expectedMethod === 'GET' &&
+          item.actualMethod === 'GET' &&
+          item.expectedStatusCode === 304 &&
+          item.actualStatusCode === 304,
+      ),
+    'direct live access log 必须保留指纹静态 ETag 304 的 method/path/status 明细。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.missing) &&
+      accessLogCheck.missing.length === 0,
+    'direct live access log missing 明细必须为空数组。',
+  );
+  ensure(
+    Array.isArray(accessLogCheck.mismatches) &&
+      accessLogCheck.mismatches.length === 0,
+    'direct live access log mismatches 明细必须为空数组。',
+  );
+}
+
+function extractJsonObject(text, startIndex) {
+  if (startIndex < 0) {
+    return '';
+  }
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let index = startIndex; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === '{') {
+      depth += 1;
+      continue;
+    }
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        return text.slice(startIndex, index + 1);
+      }
+    }
+  }
+
+  return '';
+}
+
+function redactSecretArgs(args) {
+  return args.map((arg, index) =>
+    index > 0 && SECRET_VALUE_FLAGS.has(args[index - 1])
+      ? '<redacted>'
+      : arg,
+  );
+}
+
+function resolveGatewayBinary() {
+  const explicit = process.env.GENARRATIVE_PINGORA_GATEWAY_BINARY;
+  if (explicit) {
+    return explicit;
+  }
+
+  const candidates = [
+    path.join(repoRoot, 'server-rs', 'target', 'debug', 'pingora-gateway'),
+    path.join(repoRoot, 'target', 'debug', 'pingora-gateway'),
+  ];
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (!found) {
+    throw new Error(
+      `未找到 pingora-gateway debug 二进制，请先构建或设置 GENARRATIVE_PINGORA_GATEWAY_BINARY。候选：${candidates.join(', ')}`,
+    );
+  }
+  return found;
+}
+
+function smokeEnv() {
+  return {
+    ...process.env,
+    PATH: `${path.join(os.homedir(), '.local', 'bin')}:${process.env.PATH || ''}`,
+  };
+}
+
+function collectProcessLogs(child, name) {
+  child.stdout?.on('data', (chunk) => {
+    if (config.verbose) {
+      process.stdout.write(`[${name}] ${chunk}`);
+    }
+  });
+  child.stderr?.on('data', (chunk) => {
+    if (config.verbose) {
+      process.stderr.write(`[${name}] ${chunk}`);
+    }
+  });
+}
+
+function encodeWebSocketTextFrame(text) {
+  const payload = Buffer.from(text, 'utf8');
+  if (payload.length > 125) {
+    throw new Error('smoke WebSocket frame payload too large');
+  }
+  return Buffer.concat([Buffer.from([0x81, payload.length]), payload]);
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForCondition(predicate, timeoutMs = 2000) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (await predicate()) {
+      return;
+    }
+    await delay(20);
+  }
+  throw new Error('等待 smoke 条件达成超时');
+}
+
+function ensure(condition, message) {
+  if (!condition) {
+    failures.push(message);
+  }
+}
+
+function describeRequests(requests) {
+  return JSON.stringify(
+    requests.map((request) => ({
+      method: request.method,
+      url: request.url,
+      xForwardedFor: request.headers?.['x-forwarded-for'],
+      aborted: Boolean(request.aborted),
+    })),
+  );
+}
+
+async function cleanup() {
+  for (const { child, name } of childProcesses.reverse()) {
+    await stopChild(child, name);
+  }
+
+  for (const socket of sockets) {
+    socket.destroy();
+  }
+  sockets.clear();
+
+  await Promise.all(
+    servers.reverse().map(
+      (server) =>
+        new Promise((resolve) => {
+          const timer = setTimeout(resolve, 1000);
+          server.close(() => {
+            clearTimeout(timer);
+            resolve();
+          });
+        }),
+    ),
+  );
+
+  await Promise.all(
+    tempDirs.reverse().map((dir) => rm(dir, { recursive: true, force: true })),
+  );
+}
+
+async function stopChild(child, name) {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+
+  child.kill('SIGTERM');
+  const exited = await waitForExit(child, 3000);
+  if (!exited) {
+    child.kill('SIGKILL');
+    const killed = await waitForExit(child, 3000);
+    if (!killed) {
+      failures.push(`${name} 未能退出`);
+    }
+  }
+}
+
+function waitForExit(child, timeoutMs) {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve(true);
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      child.off('exit', onExit);
+      resolve(false);
+    }, timeoutMs);
+
+    function onExit() {
+      clearTimeout(timer);
+      resolve(true);
+    }
+
+    child.once('exit', onExit);
+  });
+}
diff --git a/scripts/check-pingora-health-patrol-env-switch.mjs b/scripts/check-pingora-health-patrol-env-switch.mjs
new file mode 100644
index 000000000..922664aeb
--- /dev/null
+++ b/scripts/check-pingora-health-patrol-env-switch.mjs
@@ -0,0 +1,801 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const SWITCH_SCRIPT = 'scripts/deploy/pingora-health-patrol-env-switch.mjs';
+const ENV_CHECK_SCRIPT = path.join(
+  process.cwd(),
+  'scripts/check-production-health-patrol-env.mjs',
+);
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-health-patrol-switch-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-health-patrol-env-switch] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-health-patrol-env-switch] OK');
+
+function main() {
+  assertScriptShape();
+  assertDryRunDoesNotModifyEnv();
+  assertDryRunEnvFileModeIsPrivate();
+  assertApplyPreservesEnvFileModeAndOwnership();
+  assertApplySwitchesToPingoraDirectAndPreservesOtherKeys();
+  assertApplySwitchesBackToNginxAndClearsHost();
+  assertApplyDoesNotWriteWhenVerificationFails();
+  assertApplyRejectsSymlinkEnvFileBeforeWrite();
+  assertMissingManagedKeysAreAppended();
+  assertRejectsDirectLoopbackWithoutHost();
+  assertRejectsInvalidAndConflictingHostOptions();
+  assertRejectsRelativePaths();
+  assertRejectsFilesystemRootPaths();
+  assertRejectsControlCharacterInputsBeforeWrite();
+  assertRejectsInvalidBoolEnv();
+  assertReleaseLayoutUsesBundledCheckScript();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(SWITCH_SCRIPT, 'utf8');
+  assertIncludes(content, '--apply', '切换脚本必须显式要求 --apply 才写 env。');
+  assertIncludes(
+    content,
+    '当前是 dry-run',
+    '切换脚本必须在 dry-run 中明确不会写 env。',
+  );
+  assertIncludes(
+    content,
+    'check-production-health-patrol-env.mjs',
+    '切换脚本必须复用生产 health patrol env 复核脚本。',
+  );
+  assertIncludes(
+    content,
+    'Pingora direct 模式使用本机 public base URL 时必须提供 --public-host',
+    '切换脚本必须阻断 direct loopback 缺少正式 Host。',
+  );
+  assertIncludes(
+    content,
+    'health patrol env 中存在重复配置',
+    '切换脚本必须拒绝重复目标键，避免 env 解析歧义。',
+  );
+  assertIncludes(
+    content,
+    'runHealthPatrolEnvCheck(checkFile);',
+    '切换脚本必须先用临时目标 env 复核。',
+  );
+  assertIncludes(
+    content,
+    'writeEnvFileAtomically(config.envFile, nextText);',
+    '切换脚本通过复核后才可原子写入真实 env。',
+  );
+  assertIncludes(
+    content,
+    '--env-file 不能是符号链接',
+    'apply 写入真实 env 前必须拒绝符号链接目标。',
+  );
+  assertIncludes(
+    content,
+    'DRY_RUN_ENV_FILE_MODE = 0o600',
+    '临时复核 env 文件权限必须固定为 0600。',
+  );
+  assertIncludes(
+    content,
+    'chownSync(tempFile, currentStat.uid, currentStat.gid);',
+    '真实 env 原子替换必须保留原文件 owner/group。',
+  );
+}
+
+function assertDryRunDoesNotModifyEnv() {
+  const envFile = writeEnv('dry-run.env', {
+    GENARRATIVE_HEALTH_PATROL_API_BASE_URL: 'http://127.0.0.1:8082',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const before = readFileSync(envFile, 'utf8');
+  const result = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    'https://127.0.0.1',
+    '--public-host',
+    'example.com',
+  ]);
+
+  assertStatus(result, 0, 'dry-run 应成功并通过临时 env 复核。');
+  assertIncludes(result.stdout, 'apply=false', 'dry-run 输出必须显示 apply=false。');
+  assertIncludes(
+    result.stdout,
+    '[check:production-health-patrol-env] OK',
+    'dry-run 必须用临时 env 跑复核脚本。',
+  );
+  const after = readFileSync(envFile, 'utf8');
+  if (after !== before) {
+    failures.push('dry-run 不应修改 health patrol env 文件。');
+  }
+}
+
+function assertDryRunEnvFileModeIsPrivate() {
+  const envFile = writeEnv('dry-run-mode.env', {
+    GENARRATIVE_HEALTH_PATROL_API_BASE_URL: 'http://127.0.0.1:8082',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const modeCheckScript = path.join(tmpRoot, 'check-dry-run-env-mode.mjs');
+  writeFileSync(
+    modeCheckScript,
+    [
+      '#!/usr/bin/env node',
+      "import { statSync } from 'node:fs';",
+      "const envFileIndex = process.argv.indexOf('--env-file');",
+      'const envFile = process.argv[envFileIndex + 1];',
+      'const mode = statSync(envFile).mode & 0o777;',
+      'if (mode !== 0o600) {',
+      '  console.error(`dry-run env mode must be 0600, got ${mode.toString(8)}`);',
+      '  process.exit(1);',
+      '}',
+      'console.log(`[fake-health-patrol-env-check] dry-run env mode ${mode.toString(8)}`);',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodSync(modeCheckScript, 0o755);
+
+  const result = runSwitch([
+    '--env-file',
+    envFile,
+    '--check-script',
+    modeCheckScript,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    'https://127.0.0.1',
+    '--public-host',
+    'example.com',
+  ]);
+
+  assertStatus(result, 0, 'dry-run 临时复核 env 文件权限应为 0600。');
+  assertIncludes(
+    result.stdout,
+    'dry-run env mode 600',
+    'dry-run 必须把 0600 临时 env 交给复核脚本。',
+  );
+}
+
+function assertApplyPreservesEnvFileModeAndOwnership() {
+  const envFile = writeEnv('apply-mode-owner.env', {
+    GENARRATIVE_HEALTH_PATROL_API_BASE_URL: 'http://127.0.0.1:8082',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  chmodSync(envFile, 0o640);
+  const beforeStat = statSync(envFile);
+
+  const result = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    'https://127.0.0.1',
+    '--public-host',
+    'example.com',
+    '--apply',
+  ]);
+
+  assertStatus(result, 0, 'apply 原子替换应成功。');
+  const afterStat = statSync(envFile);
+  const beforeMode = beforeStat.mode & 0o777;
+  const afterMode = afterStat.mode & 0o777;
+  if (afterMode !== beforeMode) {
+    failures.push(
+      `apply 原子替换必须保留 env 文件权限，实际 ${afterMode.toString(8)}，预期 ${beforeMode.toString(8)}。`,
+    );
+  }
+  if (afterStat.uid !== beforeStat.uid || afterStat.gid !== beforeStat.gid) {
+    failures.push('apply 原子替换必须保留 env 文件 owner/group。');
+  }
+}
+
+function assertApplySwitchesToPingoraDirectAndPreservesOtherKeys() {
+  const envFile = writeEnv('direct.env', {
+    GENARRATIVE_HEALTH_PATROL_API_BASE_URL: 'http://127.0.0.1:8082',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+    GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS: '5000',
+  });
+  const result = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    'https://127.0.0.1',
+    '--public-host',
+    'example.com',
+    '--apply',
+  ]);
+
+  assertStatus(result, 0, 'apply 切到 pingora-direct 应成功。');
+  const content = readFileSync(envFile, 'utf8');
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct',
+    'apply 必须写入 pingora-direct gateway mode。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://127.0.0.1',
+    'apply 必须写入直连 public base URL。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=example.com',
+    'apply 必须写入正式 public Host。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS=5000',
+    'apply 必须保留其它 health patrol env 项。',
+  );
+}
+
+function assertApplySwitchesBackToNginxAndClearsHost() {
+  const envFile = writeEnv('nginx.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'https://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'pingora-direct',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: 'example.com',
+  });
+  const result = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--clear-public-host',
+    '--apply',
+  ]);
+
+  assertStatus(result, 0, 'apply 切回 nginx 并清空 Host 应成功。');
+  const content = readFileSync(envFile, 'utf8');
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx',
+    '回退 apply 必须写回 nginx gateway mode。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=http://127.0.0.1',
+    '回退 apply 必须恢复 Nginx public base URL。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=',
+    '回退 apply 必须清空 public Host。',
+  );
+}
+
+function assertApplyDoesNotWriteWhenVerificationFails() {
+  const envFile = writeEnv('apply-verify-fails.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const before = readFileSync(envFile, 'utf8');
+  const failingCheckScript = path.join(
+    tmpRoot,
+    'failing-health-patrol-env-check.mjs',
+  );
+  writeFileSync(
+    failingCheckScript,
+    [
+      '#!/usr/bin/env node',
+      'console.error("[fake-health-patrol-env-check] forced failure");',
+      'process.exit(1);',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+
+  const result = runSwitch([
+    '--env-file',
+    envFile,
+    '--check-script',
+    failingCheckScript,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    'https://127.0.0.1',
+    '--public-host',
+    'example.com',
+    '--apply',
+  ]);
+
+  assertStatus(result, 1, '复核失败时 apply 必须失败。');
+  assertIncludes(
+    result.stderr,
+    '[fake-health-patrol-env-check] forced failure',
+    '复核失败时必须透出复核脚本错误。',
+  );
+  const after = readFileSync(envFile, 'utf8');
+  if (after !== before) {
+    failures.push('复核失败时 apply 不应写入真实 health patrol env 文件。');
+  }
+}
+
+function assertApplyRejectsSymlinkEnvFileBeforeWrite() {
+  const targetEnvFile = writeEnv('symlink-target.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const symlinkEnvFile = path.join(tmpRoot, 'symlink-health-patrol.env');
+  symlinkSync(targetEnvFile, symlinkEnvFile);
+  const before = readFileSync(targetEnvFile, 'utf8');
+
+  const result = runSwitch([
+    '--env-file',
+    symlinkEnvFile,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    'https://127.0.0.1',
+    '--public-host',
+    'example.com',
+    '--apply',
+  ]);
+
+  assertStatus(result, 1, 'apply 传入符号链接 env 文件时必须失败。');
+  assertIncludes(
+    result.stderr,
+    '--env-file 不能是符号链接',
+    '符号链接 env 文件失败时必须给出明确错误。',
+  );
+  const after = readFileSync(targetEnvFile, 'utf8');
+  if (after !== before) {
+    failures.push('符号链接 env 文件被拒绝时不应写入真实目标文件。');
+  }
+  const linkText = readFileSync(symlinkEnvFile, 'utf8');
+  if (linkText !== before) {
+    failures.push('符号链接 env 文件被拒绝时不应替换或改写链接内容。');
+  }
+}
+
+function assertMissingManagedKeysAreAppended() {
+  const envFile = path.join(tmpRoot, 'append.env');
+  writeFileSync(
+    envFile,
+    [
+      '# existing env',
+      'GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS=5000',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  const result = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--clear-public-host',
+    '--apply',
+  ]);
+
+  assertStatus(result, 0, '缺少目标键时 apply 应追加并通过复核。');
+  const content = readFileSync(envFile, 'utf8');
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx',
+    '缺少 gateway mode 时必须追加。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=http://127.0.0.1',
+    '缺少 public base URL 时必须追加。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=',
+    '缺少 public Host 时必须追加。',
+  );
+}
+
+function assertRejectsDirectLoopbackWithoutHost() {
+  const envFile = writeEnv('direct-missing-host.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const result = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    'https://127.0.0.1',
+    '--clear-public-host',
+  ]);
+
+  assertStatus(result, 1, 'direct loopback 缺少 Host 必须失败。');
+  assertIncludes(
+    result.stderr,
+    'Pingora direct 模式使用本机 public base URL 时必须提供 --public-host',
+    'direct loopback 缺少 Host 必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidAndConflictingHostOptions() {
+  const envFile = writeEnv('invalid-host.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const invalidHost = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--public-host',
+    'https://example.com',
+  ]);
+  assertStatus(invalidHost, 1, '非法 Host 必须失败。');
+  assertIncludes(
+    invalidHost.stderr,
+    '--public-host 只能是 host 或 host:port',
+    '非法 Host 必须给出明确错误。',
+  );
+
+  const conflictingHost = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--public-host',
+    'example.com',
+    '--clear-public-host',
+  ]);
+  assertStatus(conflictingHost, 1, 'Host 与清空 Host 同时传入必须失败。');
+  assertIncludes(
+    conflictingHost.stderr,
+    '--public-host 和 --clear-public-host 不能同时使用',
+    'Host 选项冲突必须给出明确错误。',
+  );
+}
+
+function assertRejectsRelativePaths() {
+  const relativeEnv = runSwitch([
+    '--env-file',
+    'relative.env',
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--clear-public-host',
+  ]);
+  assertStatus(relativeEnv, 1, '相对 env 路径必须失败。');
+  assertIncludes(
+    relativeEnv.stderr,
+    '--env-file 必须是绝对路径',
+    '相对 env 路径必须给出明确错误。',
+  );
+
+  const envFile = writeEnv('relative-check.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const relativeCheck = runSwitch([
+    '--env-file',
+    envFile,
+    '--check-script',
+    'scripts/check-production-health-patrol-env.mjs',
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--clear-public-host',
+  ]);
+  assertStatus(relativeCheck, 1, '相对 check script 路径必须失败。');
+  assertIncludes(
+    relativeCheck.stderr,
+    '--check-script 必须是绝对路径',
+    '相对 check script 路径必须给出明确错误。',
+  );
+}
+
+function assertRejectsFilesystemRootPaths() {
+  const rootEnv = runSwitch([
+    '--env-file',
+    '/',
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--clear-public-host',
+  ]);
+  assertStatus(rootEnv, 1, '文件系统根目录 env 路径必须失败。');
+  assertIncludes(
+    rootEnv.stderr,
+    '--env-file 不能是文件系统根目录',
+    '文件系统根目录 env 路径必须给出明确错误。',
+  );
+
+  const envFile = writeEnv('root-check-script.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const rootCheckScript = runSwitch([
+    '--env-file',
+    envFile,
+    '--check-script',
+    '/',
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--clear-public-host',
+  ]);
+  assertStatus(rootCheckScript, 1, '文件系统根目录 check script 路径必须失败。');
+  assertIncludes(
+    rootCheckScript.stderr,
+    '--check-script 不能是文件系统根目录',
+    '文件系统根目录 check script 路径必须给出明确错误。',
+  );
+}
+
+function assertRejectsControlCharacterInputsBeforeWrite() {
+  const envFile = writeEnv('control-character.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const before = readFileSync(envFile, 'utf8');
+
+  const envFileResult = runSwitch([
+    '--env-file',
+    `${envFile}\nspoofed`,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--clear-public-host',
+    '--apply',
+  ]);
+  assertStatus(envFileResult, 1, '带控制字符的 env 文件路径必须失败。');
+  assertIncludes(
+    envFileResult.stderr,
+    '--env-file 不能包含换行或 NUL 字符',
+    '带控制字符的 env 文件路径必须给出明确错误。',
+  );
+
+  const checkScriptResult = runSwitch([
+    '--env-file',
+    envFile,
+    '--check-script',
+    `${ENV_CHECK_SCRIPT}\nspoofed`,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1',
+    '--clear-public-host',
+    '--apply',
+  ]);
+  assertStatus(checkScriptResult, 1, '带控制字符的 check script 路径必须失败。');
+  assertIncludes(
+    checkScriptResult.stderr,
+    '--check-script 不能包含换行或 NUL 字符',
+    '带控制字符的 check script 路径必须给出明确错误。',
+  );
+
+  const baseUrlResult = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    'http://127.0.0.1\nspoofed',
+    '--clear-public-host',
+    '--apply',
+  ]);
+  assertStatus(baseUrlResult, 1, '带控制字符的 public base URL 必须失败。');
+  assertIncludes(
+    baseUrlResult.stderr,
+    '--public-base-url 不能包含换行或 NUL 字符',
+    '带控制字符的 public base URL 必须给出明确错误。',
+  );
+
+  const hostResult = runSwitch([
+    '--env-file',
+    envFile,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    'https://127.0.0.1',
+    '--public-host',
+    'example.com\nspoofed',
+    '--apply',
+  ]);
+  assertStatus(hostResult, 1, '带控制字符的 public Host 必须失败。');
+  assertIncludes(
+    hostResult.stderr,
+    '--public-host 不能包含换行或 NUL 字符',
+    '带控制字符的 public Host 必须给出明确错误。',
+  );
+
+  const after = readFileSync(envFile, 'utf8');
+  if (after !== before) {
+    failures.push('带控制字符的切换参数被拒绝时不应写入真实 env 文件。');
+  }
+}
+
+function assertRejectsInvalidBoolEnv() {
+  const envFile = writeEnv('invalid-bool-env.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const result = runSwitch(
+    [
+      '--env-file',
+      envFile,
+      '--gateway-mode',
+      'nginx',
+      '--public-base-url',
+      'http://127.0.0.1',
+    ],
+    {
+      GENARRATIVE_HEALTH_PATROL_CLEAR_PUBLIC_HOST: 'maybe',
+    },
+  );
+  assertStatus(result, 1, 'health patrol env 切换脚本必须拒绝非法布尔 env。');
+  assertIncludes(
+    result.stderr,
+    'GENARRATIVE_HEALTH_PATROL_CLEAR_PUBLIC_HOST 必须是布尔值',
+    'health patrol env 切换脚本非法布尔 env 必须给出明确错误。',
+  );
+}
+
+function assertReleaseLayoutUsesBundledCheckScript() {
+  const releaseRoot = path.join(tmpRoot, 'current-release');
+  const releaseScript = path.join(
+    releaseRoot,
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+  );
+  const releaseCheckScript = path.join(
+    releaseRoot,
+    'scripts/check-production-health-patrol-env.mjs',
+  );
+  const envFile = writeEnv('release-layout.env', {
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+
+  mkdirSync(path.dirname(releaseScript), { recursive: true });
+  mkdirSync(path.dirname(releaseCheckScript), { recursive: true });
+  copyFileSync(SWITCH_SCRIPT, releaseScript);
+  copyFileSync('scripts/check-production-health-patrol-env.mjs', releaseCheckScript);
+  chmodSync(releaseScript, 0o755);
+
+  const result = spawnSync(
+    'node',
+    [
+      '--',
+      releaseScript,
+      '--env-file',
+      envFile,
+      '--gateway-mode',
+      'pingora-direct',
+      '--public-base-url',
+      'https://127.0.0.1',
+      '--public-host',
+      'example.com',
+    ],
+    { cwd: tmpRoot, encoding: 'utf8', env: cleanEnv() },
+  );
+
+  assertStatus(
+    result,
+    0,
+    'current release 中的切换脚本 dry-run 应能使用随包 env 复核脚本。',
+  );
+  assertIncludes(
+    result.stdout,
+    realpathSync(releaseCheckScript),
+    'current release 中的切换脚本必须默认调用随包 env 复核脚本。',
+  );
+  if (!existsSync(releaseCheckScript)) {
+    failures.push('release layout 测试必须保留随包 env 复核脚本。');
+  }
+}
+
+function writeEnv(name, values) {
+  const filePath = path.join(tmpRoot, name);
+  const body = Object.entries(values)
+    .map(([key, value]) => `${key}=${value}`)
+    .join('\n');
+  writeFileSync(filePath, `${body}\n`, 'utf8');
+  return filePath;
+}
+
+function runSwitch(args, extraEnv = {}) {
+  return spawnSync(
+    'node',
+    ['--', SWITCH_SCRIPT, '--check-script', ENV_CHECK_SCRIPT, ...args],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...cleanEnv(),
+        ...extraEnv,
+      },
+    },
+  );
+}
+
+function cleanEnv() {
+  return {
+    ...process.env,
+    GENARRATIVE_HEALTH_PATROL_ENV_FILE: '',
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: '',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: '',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+    GENARRATIVE_HEALTH_PATROL_CLEAR_PUBLIC_HOST: '',
+    GENARRATIVE_HEALTH_PATROL_ENV_CHECK_SCRIPT: '',
+  };
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!content.includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
diff --git a/scripts/check-pingora-production-release-build.mjs b/scripts/check-pingora-production-release-build.mjs
new file mode 100644
index 000000000..73da296c2
--- /dev/null
+++ b/scripts/check-pingora-production-release-build.mjs
@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const BUILD_SCRIPT = 'scripts/build-production-release.sh';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-production-release-build-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-production-release-build] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-production-release-build] OK');
+
+function main() {
+  const fixture = prepareFixture();
+  const result = runBuild(fixture);
+  assertStatus(result, 0, 'Pingora production release 真实构建烟测应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+
+  const releaseDir = path.join(process.cwd(), 'build', fixture.version);
+  try {
+    assertFileExists(
+      path.join(releaseDir, 'api-server'),
+      '发布包必须包含 api-server 占位 release binary。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'api-server.sha256'),
+      '发布包必须包含 api-server checksum。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'pingora-gateway'),
+      '真实 include Pingora 时发布包必须包含 pingora-gateway。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'pingora-gateway'),
+      'pingora-gateway 必须保留可执行权限。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'pingora-gateway.sha256'),
+      '真实 include Pingora 时发布包必须包含 pingora-gateway checksum。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/check-pingora-direct-live.mjs'),
+      '真实 include Pingora 的发布包仍必须携带 direct live smoke 脚本。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/ops/pingora-current-release-audit.mjs'),
+      '真实 include Pingora 的发布包仍必须携带 current release 自审脚本。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'deploy/pingora/nginx-route-parity.matrix.json'),
+      '真实 include Pingora 的发布包仍必须携带 Nginx/Pingora 路由矩阵。',
+    );
+
+    const manifest = readJson(path.join(releaseDir, 'release-manifest.json'));
+    if (manifest.component_type !== 'api-server') {
+      failures.push(
+        `release manifest component_type 应为 api-server，实际 ${manifest.component_type}`,
+      );
+    }
+    if (!manifest.artifacts?.some((item) => item.path === 'api-server')) {
+      failures.push('release manifest 必须登记 api-server artifact。');
+    }
+    if (!manifest.artifacts?.some((item) => item.path === 'pingora-gateway')) {
+      failures.push(
+        '真实 include Pingora 时 release manifest 必须登记 pingora-gateway artifact。',
+      );
+    }
+  } finally {
+    rmSync(releaseDir, { recursive: true, force: true });
+  }
+}
+
+function prepareFixture() {
+  const cargoTargetDir = path.join(tmpRoot, 'cargo-target');
+  const binaryDir = path.join(
+    cargoTargetDir,
+    'x86_64-unknown-linux-gnu/release',
+  );
+  const version = `check-pingora-production-release-build-${process.pid}-${Date.now()}`;
+  mkdirSync(binaryDir, { recursive: true });
+
+  const apiBinary = path.join(binaryDir, 'api-server');
+  writeFileSync(apiBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  spawnSync('chmod', ['0755', apiBinary], { encoding: 'utf8' });
+
+  return { cargoTargetDir, version };
+}
+
+function runBuild(fixture) {
+  return spawnSync(
+    'bash',
+    [
+      BUILD_SCRIPT,
+      '--component',
+      'api-server',
+      '--name',
+      fixture.version,
+      '--skip-api-build',
+      '--include-pingora-gateway',
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        CARGO_TARGET_DIR: fixture.cargoTargetDir,
+        PATH: `${path.join(process.env.HOME || '', '.local', 'bin')}:${process.env.PATH || ''}`,
+        SOURCE_BRANCH: 'test-branch',
+        SOURCE_COMMIT: 'test-commit',
+      },
+    },
+  );
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    failures.push(`${filePath} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function assertFileExists(filePath, reason) {
+  if (!existsSync(filePath)) {
+    failures.push(`${reason} 缺少: ${filePath}`);
+  }
+}
+
+function assertExecutable(filePath, reason) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  if ((statSync(filePath).mode & 0o111) === 0) {
+    failures.push(`${reason} 文件不可执行: ${filePath}`);
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
diff --git a/scripts/check-pingora-realpath-canary-toggle.mjs b/scripts/check-pingora-realpath-canary-toggle.mjs
new file mode 100644
index 000000000..22f0e0c95
--- /dev/null
+++ b/scripts/check-pingora-realpath-canary-toggle.mjs
@@ -0,0 +1,432 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const ENABLE_SCRIPT = 'scripts/deploy/pingora-realpath-canary-enable.sh';
+const DISABLE_SCRIPT = 'scripts/deploy/pingora-realpath-canary-disable.sh';
+const failures = [];
+const tmpRoot = mkdtempSync(path.join(tmpdir(), 'genarrative-realpath-canary-'));
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-realpath-canary-toggle] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-realpath-canary-toggle] OK');
+
+function main() {
+  assertScriptShape();
+  assertDryRunDoesNotWrite();
+  assertApplyWritesRenderedConfigAndRunsLive();
+  assertEnableRollsBackWhenLiveFails();
+  assertDisableRemovesConfig();
+  assertDisableRollsBackWhenReloadFails();
+  assertRejectsUnsafeInputs();
+}
+
+function assertScriptShape() {
+  for (const script of [ENABLE_SCRIPT, DISABLE_SCRIPT]) {
+    const content = readFileSync(script, 'utf8');
+    assertIncludes(content, '--apply', `${script} 必须默认 dry-run 并要求显式 --apply。`);
+    assertIncludes(content, 'nginx -t', `${script} 帮助文案必须说明会先做 nginx -t。`);
+    assertIncludes(
+      content,
+      'zz-genarrative-pingora-realpath-canary.conf',
+      `${script} 必须默认使用晚于主站配置加载的 conf.d 文件名。`,
+    );
+    assertIncludes(
+      content,
+      '不能包含换行或 NUL 字符',
+      `${script} 必须拒绝控制字符参数。`,
+    );
+    assertIncludes(content, '不能是文件系统根目录', `${script} 必须拒绝根路径。`);
+  }
+
+  const enableContent = readFileSync(ENABLE_SCRIPT, 'utf8');
+  assertIncludes(
+    enableContent,
+    'check-pingora-canary-live.mjs',
+    'enable 脚本必须默认运行 realpath live smoke。',
+  );
+  assertIncludes(
+    enableContent,
+    '恢复写入前配置',
+    'enable 脚本失败时必须恢复写入前配置。',
+  );
+
+  const disableContent = readFileSync(DISABLE_SCRIPT, 'utf8');
+  assertIncludes(
+    disableContent,
+    '恢复删除前配置',
+    'disable 脚本失败时必须恢复删除前配置。',
+  );
+}
+
+function assertDryRunDoesNotWrite() {
+  const fixture = createFixture('dry-run');
+  const targetPath = path.join(fixture.nginxDir, 'zz-genarrative-pingora-realpath-canary.conf');
+
+  const result = runScript(ENABLE_SCRIPT, [
+    '--probe-token',
+    'dry-run-token',
+    '--host',
+    'dev.genarrative.world',
+    '--template-path',
+    fixture.templatePath,
+    '--target-path',
+    targetPath,
+    '--nginx-binary',
+    fixture.nginxBinary,
+    '--systemctl-binary',
+    fixture.systemctlBinary,
+    '--live-script',
+    fixture.liveScript,
+  ]);
+
+  assertStatus(result, 0, 'enable dry-run 应成功。');
+  if (existsSync(targetPath)) {
+    failures.push('enable dry-run 不应写入目标 Nginx 配置。');
+  }
+  assertIncludes(result.stdout, 'dry-run', 'enable dry-run 应输出 dry-run 提示。');
+}
+
+function assertApplyWritesRenderedConfigAndRunsLive() {
+  const fixture = createFixture('apply-ok');
+  const targetPath = path.join(fixture.nginxDir, 'zz-genarrative-pingora-realpath-canary.conf');
+  const result = runScript(ENABLE_SCRIPT, [
+    '--apply',
+    '--probe-token',
+    'apply-real-token',
+    '--host',
+    'dev.genarrative.world',
+    '--base-url',
+    'http://127.0.0.1:18083',
+    '--template-path',
+    fixture.templatePath,
+    '--target-path',
+    targetPath,
+    '--nginx-binary',
+    fixture.nginxBinary,
+    '--systemctl-binary',
+    fixture.systemctlBinary,
+    '--live-script',
+    fixture.liveScript,
+    '--no-status',
+  ]);
+
+  assertStatus(result, 0, 'enable apply 应成功。');
+  const rendered = readFileSync(targetPath, 'utf8');
+  assertIncludes(rendered, '"apply-real-token"', 'enable apply 应替换 probe token。');
+  if (rendered.includes('__GENARRATIVE_PINGORA_PROBE_TOKEN__')) {
+    failures.push('enable apply 后目标配置不应保留 probe token 占位符。');
+  }
+  const calls = readFileSync(fixture.callsPath, 'utf8');
+  assertIncludes(calls, 'nginx -t', 'enable apply 必须执行 nginx -t。');
+  assertIncludes(calls, 'systemctl reload nginx.service', 'enable apply 必须 reload nginx。');
+  assertIncludes(
+    calls,
+    'live --realpath --base-url http://127.0.0.1:18083 --host dev.genarrative.world',
+    'enable apply 必须执行 realpath live smoke。',
+  );
+}
+
+function assertEnableRollsBackWhenLiveFails() {
+  const fixture = createFixture('enable-live-fails', { liveExitCode: 7 });
+  const targetPath = path.join(fixture.nginxDir, 'zz-genarrative-pingora-realpath-canary.conf');
+  writeFileSync(targetPath, 'previous-config\n', 'utf8');
+
+  const result = runScript(
+    ENABLE_SCRIPT,
+    [
+    '--apply',
+    '--probe-token',
+    'rollback-token',
+    '--host',
+    'dev.genarrative.world',
+    '--template-path',
+    fixture.templatePath,
+    '--target-path',
+    targetPath,
+    '--nginx-binary',
+    fixture.nginxBinary,
+    '--systemctl-binary',
+    fixture.systemctlBinary,
+    '--live-script',
+    fixture.liveScript,
+    '--no-status',
+    ],
+    fixture.env,
+  );
+
+  if (result.status === 0) {
+    failures.push('realpath live smoke 失败时 enable apply 必须失败。');
+  }
+  const restored = readFileSync(targetPath, 'utf8');
+  if (restored !== 'previous-config\n') {
+    failures.push('realpath live smoke 失败时 enable apply 必须恢复旧配置。');
+  }
+  assertIncludes(
+    result.stderr,
+    '恢复写入前配置',
+    'enable live 失败时必须说明已恢复写入前配置。',
+  );
+}
+
+function assertDisableRemovesConfig() {
+  const fixture = createFixture('disable-ok');
+  const targetPath = path.join(fixture.nginxDir, 'zz-genarrative-pingora-realpath-canary.conf');
+  writeFileSync(targetPath, 'enabled-config\n', 'utf8');
+
+  const result = runScript(
+    DISABLE_SCRIPT,
+    [
+    '--apply',
+    '--target-path',
+    targetPath,
+    '--nginx-binary',
+    fixture.nginxBinary,
+    '--systemctl-binary',
+    fixture.systemctlBinary,
+    '--no-status',
+    ],
+    fixture.env,
+  );
+
+  assertStatus(result, 0, 'disable apply 应成功。');
+  if (existsSync(targetPath)) {
+    failures.push('disable apply 成功后必须删除 realpath canary 配置。');
+  }
+  const calls = readFileSync(fixture.callsPath, 'utf8');
+  assertIncludes(calls, 'nginx -t', 'disable apply 必须执行 nginx -t。');
+  assertIncludes(calls, 'systemctl reload nginx.service', 'disable apply 必须 reload nginx。');
+}
+
+function assertDisableRollsBackWhenReloadFails() {
+  const fixture = createFixture('disable-reload-fails', { reloadExitCode: 9 });
+  const targetPath = path.join(fixture.nginxDir, 'zz-genarrative-pingora-realpath-canary.conf');
+  writeFileSync(targetPath, 'enabled-config\n', 'utf8');
+
+  const result = runScript(DISABLE_SCRIPT, [
+    '--apply',
+    '--target-path',
+    targetPath,
+    '--nginx-binary',
+    fixture.nginxBinary,
+    '--systemctl-binary',
+    fixture.systemctlBinary,
+    '--no-status',
+  ]);
+
+  if (result.status === 0) {
+    failures.push('reload 失败时 disable apply 必须失败。');
+  }
+  const restored = readFileSync(targetPath, 'utf8');
+  if (restored !== 'enabled-config\n') {
+    failures.push('reload 失败时 disable apply 必须恢复删除前配置。');
+  }
+  assertIncludes(
+    result.stderr,
+    '恢复删除前配置',
+    'disable reload 失败时必须说明已恢复删除前配置。',
+  );
+}
+
+function assertRejectsUnsafeInputs() {
+  const fixture = createFixture('unsafe-inputs');
+  const targetPath = path.join(fixture.nginxDir, 'zz-genarrative-pingora-realpath-canary.conf');
+  const cases = [
+    {
+      name: 'missing token',
+      script: ENABLE_SCRIPT,
+      args: [
+        '--apply',
+        '--host',
+        'dev.genarrative.world',
+        '--template-path',
+        fixture.templatePath,
+        '--target-path',
+        targetPath,
+        '--nginx-binary',
+        fixture.nginxBinary,
+        '--systemctl-binary',
+        fixture.systemctlBinary,
+        '--live-script',
+        fixture.liveScript,
+      ],
+      expected: '--apply 必须提供 --probe-token',
+    },
+    {
+      name: 'url host',
+      script: ENABLE_SCRIPT,
+      args: [
+        '--probe-token',
+        'unsafe-token',
+        '--host',
+        'https://dev.genarrative.world',
+        '--template-path',
+        fixture.templatePath,
+        '--target-path',
+        targetPath,
+        '--nginx-binary',
+        fixture.nginxBinary,
+        '--systemctl-binary',
+        fixture.systemctlBinary,
+        '--live-script',
+        fixture.liveScript,
+      ],
+      expected: '不能是 URL',
+    },
+    {
+      name: 'relative target',
+      script: DISABLE_SCRIPT,
+      args: ['--target-path', 'relative.conf'],
+      expected: '--target-path 必须是绝对路径',
+    },
+    {
+      name: 'root target',
+      script: DISABLE_SCRIPT,
+      args: ['--target-path', '/'],
+      expected: '--target-path 不能是文件系统根目录',
+    },
+  ];
+
+  for (const item of cases) {
+    const result = runScript(item.script, item.args);
+    if (result.status === 0) {
+      failures.push(`${item.name}: 不安全参数必须失败。`);
+    }
+    assertIncludes(
+      `${result.stderr}\n${result.stdout}`,
+      item.expected,
+      `${item.name}: 应输出明确错误。`,
+    );
+  }
+}
+
+function createFixture(name, options = {}) {
+  const root = path.join(tmpRoot, name);
+  const nginxDir = path.join(root, 'nginx-conf');
+  mkdirSync(nginxDir, { recursive: true });
+  const callsPath = path.join(root, 'calls.log');
+  const templatePath = path.join(root, 'genarrative-pingora-realpath-canary.conf');
+  const nginxBinary = path.join(root, 'nginx');
+  const systemctlBinary = path.join(root, 'systemctl');
+  const liveScript = path.join(root, 'live.mjs');
+
+  writeFileSync(
+    templatePath,
+    [
+      'server {',
+      '    listen 127.0.0.1:18083;',
+      '    access_log /var/log/nginx/genarrative-pingora-realpath-canary.access.log genarrative_upstream;',
+      '    location = /__genarrative_pingora_realpath_canary/healthz {',
+      '        proxy_set_header X-Genarrative-Pingora-Probe "__GENARRATIVE_PINGORA_PROBE_TOKEN__";',
+      '        proxy_pass http://127.0.0.1:18081/__genarrative_pingora/healthz;',
+      '    }',
+      '}',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    nginxBinary,
+    [
+      '#!/usr/bin/env bash',
+      `echo "nginx $*" >> ${shellQuote(callsPath)}`,
+      'if [[ "${GENARRATIVE_FAKE_NGINX_T_EXIT:-0}" != "0" ]]; then exit "${GENARRATIVE_FAKE_NGINX_T_EXIT}"; fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    systemctlBinary,
+    [
+      '#!/usr/bin/env bash',
+      `echo "systemctl $*" >> ${shellQuote(callsPath)}`,
+      `reload_exit="\${GENARRATIVE_FAKE_RELOAD_EXIT:-${Number(options.reloadExitCode || 0)}}"`,
+      'if [[ "$1" == "reload" && "${reload_exit}" != "0" ]]; then exit "${reload_exit}"; fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    liveScript,
+    [
+      '#!/usr/bin/env node',
+      "import { appendFileSync } from 'node:fs';",
+      `appendFileSync(${JSON.stringify(callsPath)}, 'live ' + process.argv.slice(2).join(' ') + '\\n');`,
+      `process.exit(Number(process.env.GENARRATIVE_FAKE_LIVE_EXIT || ${Number(options.liveExitCode || 0)}));`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(nginxBinary);
+  chmodExecutable(systemctlBinary);
+  chmodExecutable(liveScript);
+
+  return {
+    root,
+    nginxDir,
+    callsPath,
+    templatePath,
+    nginxBinary,
+    systemctlBinary,
+    liveScript,
+    env: {
+      GENARRATIVE_FAKE_RELOAD_EXIT: String(options.reloadExitCode || 0),
+      GENARRATIVE_FAKE_LIVE_EXIT: String(options.liveExitCode || 0),
+    },
+  };
+}
+
+function runScript(script, args, env = {}) {
+  return spawnSync('bash', [script, ...args], {
+    cwd: process.cwd(),
+    env: { ...process.env, ...env },
+    encoding: 'utf8',
+  });
+}
+
+function chmodExecutable(file) {
+  chmodSync(file, 0o755);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function assertStatus(result, expected, message) {
+  if (result.status !== expected) {
+    failures.push(
+      `${message} 实际退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, message) {
+  if (!content.includes(needle)) {
+    failures.push(`${message} 缺少 ${needle}`);
+  }
+}
diff --git a/scripts/check-pingora-release-readiness-plan.mjs b/scripts/check-pingora-release-readiness-plan.mjs
new file mode 100644
index 000000000..f2673d276
--- /dev/null
+++ b/scripts/check-pingora-release-readiness-plan.mjs
@@ -0,0 +1,4336 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const failures = [];
+
+const requireDirectBaseArgs = [
+  '--require-direct',
+  '--direct-https-base-url',
+  'https://127.0.0.1',
+  '--direct-http-base-url',
+  'http://127.0.0.1',
+  '--direct-host',
+  'example.com',
+  '--direct-redirect-host',
+  'example.com',
+  '--direct-preflight-env-file',
+  '/tmp/pingora-gateway.env',
+  '--direct-preflight-systemd',
+  '--direct-preflight-check-cert-readable',
+  '--direct-preflight-check-service-env-file',
+  '--direct-preflight-check-service-user-cert-readable',
+  '--direct-preflight-check-service-binary-executable',
+  '--direct-spacetime-database',
+  'genarrative-prod',
+  '--direct-pingora-access-log',
+  '/var/log/genarrative/pingora-gateway.access.log',
+  '--direct-health-patrol-env-file',
+  '/etc/genarrative/health-patrol.env',
+];
+
+const cutoverRequiredArgs = [
+  '--direct-preflight-check-ports-free',
+  '--rollback-nginx-smoke-url',
+  'https://example.com/',
+  '--rollback-nginx-smoke-expect-body',
+  '<!doctype html>',
+  '--rollback-health-patrol-public-base-url',
+  'http://127.0.0.1',
+];
+
+function cutoverPlanArgs(...extraArgs) {
+  return [
+    ...requireDirectBaseArgs,
+    '--dry-run-cutover',
+    ...cutoverRequiredArgs,
+    ...extraArgs,
+  ];
+}
+
+const requireLiveBaseArgs = [
+  '--require-live',
+  '--live-base-url',
+  'http://127.0.0.1',
+  '--live-host',
+  'example.com',
+  '--live-nginx-access-log',
+  '/var/log/nginx/genarrative.access.log',
+  '--live-pingora-access-log',
+  '/var/log/genarrative/pingora-gateway.access.log',
+  '--live-access-log-since-lines',
+  '3000',
+];
+
+const requireRealpathLiveBaseArgs = [
+  '--require-realpath-live',
+  '--realpath-live-base-url',
+  'http://127.0.0.1:18083',
+  '--realpath-live-host',
+  'example.com',
+  '--realpath-live-nginx-access-log',
+  '/var/log/nginx/genarrative-pingora-realpath-canary.access.log',
+  '--realpath-live-pingora-access-log',
+  '/var/log/genarrative/pingora-gateway.access.log',
+  '--realpath-live-access-log-since-lines',
+  '3000',
+];
+
+main();
+
+if (failures.length > 0) {
+  console.error('[check:pingora-release-readiness-plan] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-release-readiness-plan] OK');
+
+function main() {
+  assertDefaultPlanIncludesStaticDirectPreflight();
+  assertDefaultPlanIncludesProductionApiReleaseSmoke();
+  assertDefaultPlanIncludesProductionApiDeploySmoke();
+  assertDefaultPlanIncludesHealthPatrolEnvSmoke();
+  assertDefaultPlanIncludesPingoraHealthPatrolEnvSwitchSmoke();
+  assertDefaultPlanIncludesPingoraGatewayEnvShadowSwitchSmoke();
+  assertDefaultPlanIncludesPingoraCurrentReleaseAuditSmoke();
+  assertDefaultPlanIncludesPingoraDirectRehearsalStatusSmoke();
+  assertDefaultPlanIncludesPingoraCutoverStatusSnapshotSmoke();
+  assertDefaultPlanIncludesPingoraCutoverEvidenceBundleSmoke();
+  assertDefaultPlanIncludesPingoraCutoverCommandEvidenceSmoke();
+  assertDefaultPlanIncludesPingoraCutoverEvidenceVerifySmoke();
+  assertDefaultPlanIncludesPingoraCutoverEvidenceAuditSmoke();
+  assertDefaultPlanIncludesCanaryAccessLogParitySmoke();
+  assertDefaultPlanIncludesRealpathCanaryToggleSmoke();
+  assertDefaultPlanIncludesPingoraProductionReleaseBuildSmoke();
+  assertReleaseRuntimeOnlyPlanUsesCurrentReleaseScripts();
+  assertReleaseRuntimeOnlyPlanIncludesDirectRehearsalStatus();
+  assertReleaseRuntimeOnlyAllowsRealpathOnlyCanary();
+  assertReleaseRuntimeOnlyKeepsInvokedCurrentSymlinkPath();
+  assertReleaseRuntimeOnlyRejectsSourceOnlyFlags();
+  assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook();
+  assertDryRunCutoverExplicitRollbackBodyIgnoresProcessEnv();
+  assertDryRunCutoverPostEnableReadinessRedactsDirectProbeToken();
+  assertDryRunCutoverPlanIncludesHostConsistencyConfirmation();
+  assertDryRunCutoverAllowsSameHostnameWithDifferentPorts();
+  assertDryRunCutoverCanRestoreRollbackHealthPatrolPublicHost();
+  assertDryRunCutoverPlanCanIncludeRollbackShadowProbe();
+  assertDryRunCutoverPlanCanOverrideEvidenceTimelineMaxSpan();
+  assertDryRunCutoverPlanAvoidsManualEvidenceEscapeHatches();
+  assertTechnicalDocCutoverAuditExamplesRequireCommandExecutables();
+  assertDryRunCutoverPlanCarriesCutoverRunId();
+  assertDryRunCutoverPlanGeneratesDefaultCutoverRunId();
+  assertRequireLiveForcesHost();
+  assertRequireRealpathLiveForcesHostAndRealpathParity();
+  assertRequireLiveRejectsRelativeAccessLog();
+  assertRequireLiveRejectsFilesystemRootAccessLog();
+  assertRequireLiveRejectsInvalidAccessLogSinceLines();
+  assertRequireRealpathLiveRejectsMissingHost();
+  assertRequireRealpathLiveRejectsRelativeAccessLog();
+  assertLiveSmokeScriptsRejectInvalidTimeout();
+  assertDirectLiveRejectsInvalidBoolEnv();
+  assertDirectLiveRejectsFilesystemRootAccessLog();
+  assertReleaseReadinessRejectsInvalidDirectBoolEnv();
+  assertDirectPreflightRejectsInvalidBoolEnv();
+  assertDirectPreflightRejectsUnconfirmedMultiInstanceProtection();
+  assertCutoverEvidenceScriptsRejectInvalidBoolEnv();
+  assertRequireDirectForcesWssUpgrade();
+  assertRequireDirectForcesHttpBaseUrl();
+  assertRequireDirectForcesHostSni();
+  assertRequireDirectForcesRedirectHost();
+  assertRequireDirectForcesPingoraAccessLog();
+  assertRequireDirectForcesPreflightSystemdCertReadable();
+  assertDryRunCutoverForcesPortsFreePreflight();
+  assertRequireDirectForcesExplicitSpacetimeDatabase();
+  assertRequireDirectForcesHealthPatrolEnvCheck();
+  assertDryRunPlanRedactsDirectProbeToken();
+  assertRunStepLogRedactsDirectProbeToken();
+  assertRequireLiveRejectsMissingHost();
+  assertRequireLiveRejectsInvalidHost();
+  assertRequireDirectRejectsMissingHttpBaseUrl();
+  assertRequireDirectRejectsMissingHost();
+  assertRequireDirectRejectsInvalidHost();
+  assertRequireDirectRejectsMissingRedirectHost();
+  assertRequireDirectRejectsInvalidRedirectHost();
+  assertRequireDirectRejectsMissingPingoraAccessLog();
+  assertRequireDirectRejectsFilesystemRootPingoraAccessLog();
+  assertRequireDirectRejectsMissingSystemdPreflight();
+  assertRequireDirectRejectsMissingCertReadablePreflight();
+  assertRequireDirectRejectsMissingServiceEnvFilePreflight();
+  assertRequireDirectRejectsMissingServiceUserCertReadablePreflight();
+  assertRequireDirectRejectsMissingServiceBinaryExecutablePreflight();
+  assertRequireDirectAllowsPostEnablePortsOwnedByPingora();
+  assertDryRunCutoverRejectsMissingPortsFreePreflight();
+  assertRequireDirectRejectsMissingSpacetimeDatabase();
+  assertRequireDirectRejectsFilesystemRootPreflightEnvFile();
+  assertRequireDirectRejectsMissingHealthPatrolEnvFile();
+  assertRequireDirectRejectsRelativeHealthPatrolEnvFile();
+  assertRequireDirectRejectsFilesystemRootHealthPatrolEnvFile();
+  assertRequireDirectRejectsSkipWss();
+  assertRequireDirectRejectsInsecureTls();
+  assertDryRunCutoverRejectsMissingRequireDirect();
+  assertDryRunCutoverRejectsRelativeEvidenceOutputRoot();
+  assertDryRunCutoverRejectsFilesystemRootReleaseRoot();
+  assertDryRunCutoverRejectsFilesystemRootEvidenceOutputRoot();
+  assertUsageCutoverExampleIncludesExplicitEvidenceOutputRoot();
+  assertUsageExamplesIncludeDirectPingoraAccessLog();
+  assertDryRunCutoverRejectsMissingRollbackSmokeBody();
+  assertDryRunCutoverRejectsMissingRollbackHealthPatrolPublicBaseUrl();
+  assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicBaseUrl();
+  assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicHost();
+  assertDryRunCutoverRejectsRedirectHostMismatch();
+  assertDryRunCutoverRejectsRollbackHostMismatch();
+  assertDryRunCutoverRejectsIncompleteRollbackShadowProbe();
+  assertDryRunCutoverRejectsInvalidRollbackShadowProbeUrl();
+  assertDryRunCutoverRejectsInvalidEvidenceTimelineMaxSpan();
+  assertDryRunCutoverRejectsInvalidCutoverRunId();
+}
+
+function assertDefaultPlanIncludesStaticDirectPreflight() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora direct entry 静态预检');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 direct-entry 静态预检。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-direct-preflight',
+    'direct-entry 静态预检必须调用 check:pingora-direct-preflight。',
+  );
+}
+
+function assertDefaultPlanIncludesProductionApiDeploySmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'API deploy release 烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 API deploy release 烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:production-api-deploy',
+    'API deploy release 烟测必须调用 check:production-api-deploy。',
+  );
+}
+
+function assertDefaultPlanIncludesHealthPatrolEnvSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, '生产健康巡检 env 复核烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含生产健康巡检 env 复核烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:production-health-patrol-env',
+    '生产健康巡检 env 复核烟测必须调用 check:production-health-patrol-env。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraHealthPatrolEnvSwitchSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora health patrol env 切换烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora health patrol env 切换烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-health-patrol-env-switch',
+    'Pingora health patrol env 切换烟测必须调用 check:pingora-health-patrol-env-switch。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraGatewayEnvShadowSwitchSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora gateway env shadow 切换烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora gateway env shadow 切换烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-gateway-env-shadow-switch',
+    'Pingora gateway env shadow 切换烟测必须调用 check:pingora-gateway-env-shadow-switch。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraCutoverStatusSnapshotSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora cutover 状态快照烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora cutover 状态快照烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-cutover-status-snapshot',
+    'Pingora cutover 状态快照烟测必须调用 check:pingora-cutover-status-snapshot。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraCurrentReleaseAuditSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora current release 自审烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora current release 自审烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-current-release-audit',
+    'Pingora current release 自审烟测必须调用 check:pingora-current-release-audit。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraDirectRehearsalStatusSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora direct rehearsal 状态烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora direct rehearsal 状态烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-direct-rehearsal-status',
+    'Pingora direct rehearsal 状态烟测必须调用 check:pingora-direct-rehearsal-status。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraCutoverEvidenceBundleSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora cutover 证据包烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora cutover 证据包烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-cutover-evidence-bundle',
+    'Pingora cutover 证据包烟测必须调用 check:pingora-cutover-evidence-bundle。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraCutoverCommandEvidenceSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora cutover 命令证据烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora cutover 命令证据烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-cutover-command-evidence',
+    'Pingora cutover 命令证据烟测必须调用 check:pingora-cutover-command-evidence。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraCutoverEvidenceVerifySmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora cutover 证据 manifest 验真烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora cutover 证据 manifest 验真烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-cutover-evidence-verify',
+    'Pingora cutover 证据 manifest 验真烟测必须调用 check:pingora-cutover-evidence-verify。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraCutoverEvidenceAuditSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora cutover 证据根目录审计烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora cutover 证据根目录审计烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-cutover-evidence-audit',
+    'Pingora cutover 证据根目录审计烟测必须调用 check:pingora-cutover-evidence-audit。',
+  );
+}
+
+function assertDefaultPlanIncludesCanaryAccessLogParitySmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora canary access log 对账烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora canary access log 对账烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-canary-access-log-parity',
+    'Pingora canary access log 对账烟测必须调用 check:pingora-canary-access-log-parity。',
+  );
+}
+
+function assertDefaultPlanIncludesRealpathCanaryToggleSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora realpath canary 启停烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora realpath canary 启停烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-realpath-canary-toggle',
+    'Pingora realpath canary 启停烟测必须调用 check:pingora-realpath-canary-toggle。',
+  );
+}
+
+function assertDefaultPlanIncludesProductionApiReleaseSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'API release build 烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 API release build 烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:production-api-release',
+    'API release build 烟测必须调用 check:production-api-release。',
+  );
+}
+
+function assertDefaultPlanIncludesPingoraProductionReleaseBuildSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora production release 真实构建烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora production release 真实构建烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-production-release-build',
+    'Pingora production release 真实构建烟测必须调用 check:pingora-production-release-build。',
+  );
+}
+
+function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
+  const plan = readPlan(cutoverPlanArgs(
+    '--cutover-release-root',
+    '/opt/genarrative/current',
+  ));
+  const preflight = findStep(
+    plan,
+    '切换前 current release 直连 env / 证书 / 端口预检',
+  );
+  const releaseAudit = findStep(plan, '切换前 current release 自包含自审');
+  if (!releaseAudit) {
+    failures.push('dry-run cutover 必须包含切换前 current release 自包含自审。');
+  } else {
+    assertIncludes(
+      releaseAudit.args,
+      '/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs',
+      '切换前 current release 自审必须使用 current release 随包脚本。',
+    );
+    assertIncludes(
+      releaseAudit.args,
+      '--require-pingora-gateway',
+      '正式直连 runbook 的 current release 自审必须要求 pingora-gateway 已随包存在。',
+    );
+    assertIncludes(
+      releaseAudit.args,
+      '--systemd-show',
+      '正式直连 runbook 的 current release 自审必须核验 systemd ExecStart。',
+    );
+  }
+  const preSnapshot = findStep(plan, '切换前状态快照证据包');
+  const preVerify = findStep(plan, '切换前证据 manifest 只读验真');
+  if (!preSnapshot) {
+    failures.push('dry-run cutover 必须包含切换前状态快照证据包。');
+  } else {
+    assertIncludes(
+      preSnapshot.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs',
+      '切换前状态快照证据包必须使用 current release 随包证据包脚本。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      '--snapshot-script',
+      '切换前状态快照证据包必须显式透传 snapshot 脚本。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      '--output-root',
+      '切换前状态快照证据包必须显式传证据输出根目录。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      '/var/log/genarrative/pingora-cutover-evidence',
+      '切换前状态快照证据包必须默认写入固定证据根目录。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-status-snapshot.mjs',
+      '切换前状态快照证据包必须使用 current release 随包状态快照脚本。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      '--expected-gateway-mode',
+      '切换前状态快照证据包必须显式传 expected gateway mode。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      'nginx',
+      '切换前状态快照证据包必须确认仍是 Nginx 巡检口径。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      '--run-health-patrol',
+      '切换前状态快照证据包必须执行生产健康巡检。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      '--require-pingora-gateway',
+      '切换前状态快照证据包必须收录 Pingora 发布物 checksum / manifest 自审。',
+    );
+    assertIncludes(
+      preSnapshot.args,
+      '--fail-on-critical',
+      '切换前状态快照证据包出现 CRITICAL 必须阻断切换。',
+    );
+  }
+  if (!preVerify) {
+    failures.push('dry-run cutover 必须包含切换前证据 manifest 只读验真。');
+  } else {
+    assertIncludes(
+      preVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '切换前证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      preVerify.args,
+      '<pre-cutover-bundle-dir>',
+      '切换前证据验真必须提示替换刚生成的 pre-cutover bundleDir。',
+    );
+    assertIncludes(
+      preVerify.args,
+      '--require-summary-ok',
+      '切换前证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
+  if (!preflight) {
+    failures.push('dry-run cutover 必须包含启用前 current release 预检。');
+  } else {
+    assertIncludes(
+      preflight.args,
+      '/opt/genarrative/current/scripts/check-pingora-direct-preflight.mjs',
+      'dry-run cutover 启用前预检必须使用 current release 随包脚本。',
+    );
+    assertIncludes(
+      preflight.args,
+      '--check-service-user-cert-readable',
+      'dry-run cutover 启用前预检必须检查 systemd 服务用户可读证书和私钥。',
+    );
+    assertIncludes(
+      preflight.args,
+      '--check-service-env-file',
+      'dry-run cutover 启用前预检必须检查 service EnvironmentFile 包含本次 env。',
+    );
+    assertIncludes(
+      preflight.args,
+      '--check-service-binary-executable',
+      'dry-run cutover 启用前预检必须检查 current release Pingora 二进制可执行。',
+    );
+    assertIncludes(
+      preflight.args,
+      '--check-ports-free',
+      'dry-run cutover 启用前预检必须检查 80/443 端口释放。',
+    );
+    assertIncludes(
+      preflight.args,
+      '--systemd-cat',
+      'dry-run cutover 启用前预检必须检查当前 systemd direct-entry 状态。',
+    );
+  }
+
+  const baseReadiness = findStep(plan, '切换前 release readiness 基础门禁');
+  if (!baseReadiness) {
+    failures.push(
+      'dry-run cutover 必须包含启用前 release readiness 基础门禁。',
+    );
+  } else if (baseReadiness.args.includes('--require-direct')) {
+    failures.push(
+      'dry-run cutover 启用前基础门禁不能带 --require-direct；systemd drop-in 尚未生效。',
+    );
+  } else {
+    assertIncludes(
+      baseReadiness.args,
+      '/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs',
+      'dry-run cutover 启用前基础门禁必须使用 current release 随包 release readiness 聚合门禁脚本。',
+    );
+    assertIncludes(
+      baseReadiness.args,
+      '--release-runtime-only',
+      'dry-run cutover 启用前基础门禁必须使用 current release 包内运行时复核模式。',
+    );
+  }
+
+  const enableDryRun = findStep(plan, 'Pingora direct enable dry-run');
+  if (!enableDryRun) {
+    failures.push('dry-run cutover 必须包含 direct enable dry-run。');
+  } else {
+    assertIncludes(
+      enableDryRun.command,
+      '/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+      'dry-run cutover enable dry-run 必须使用 current release 随包启用脚本。',
+    );
+    if (enableDryRun.args.includes('--apply')) {
+      failures.push('dry-run cutover enable dry-run 不能带 --apply。');
+    }
+    assertIncludes(
+      enableDryRun.args,
+      '--current-release-audit-script',
+      'dry-run cutover enable dry-run 必须显式固定 current release 自审脚本。',
+    );
+    assertIncludes(
+      enableDryRun.args,
+      '/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs',
+      'dry-run cutover enable dry-run 必须使用 current release 随包自审脚本。',
+    );
+    assertIncludes(
+      enableDryRun.args,
+      '--current-release-root',
+      'dry-run cutover enable dry-run 必须显式固定 current release 根目录。',
+    );
+    assertIncludes(
+      enableDryRun.args,
+      '/opt/genarrative/current',
+      'dry-run cutover enable dry-run 必须把 current release 根目录传给启用脚本。',
+    );
+    assertIncludes(
+      enableDryRun.args,
+      '/opt/genarrative/current/scripts/check-pingora-direct-live.mjs',
+      'dry-run cutover enable dry-run 必须指定 current release 随包 direct live smoke。',
+    );
+  }
+
+  const enableApply = findStep(plan, 'Pingora direct enable apply');
+  const enableApplyVerify = findStep(plan, '启用命令证据 manifest 只读验真');
+  if (!enableApply) {
+    failures.push('dry-run cutover 必须包含 direct enable apply。');
+  } else {
+    assertIncludes(
+      enableApply.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs',
+      'dry-run cutover enable apply 必须通过 current release 随包命令证据脚本归档执行输出。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--command-name',
+      'dry-run cutover enable apply 必须显式记录命令证据名称。',
+    );
+    assertIncludes(
+      enableApply.args,
+      'pingora-direct-enable-apply',
+      'dry-run cutover enable apply 必须记录固定命令证据名称。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--output-root',
+      'dry-run cutover enable apply 必须显式传证据输出根目录。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '/var/log/genarrative/pingora-cutover-evidence',
+      'dry-run cutover enable apply 必须使用固定证据根目录。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+      'dry-run cutover enable apply 必须在命令证据脚本后执行 current release 随包启用脚本。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--expected-executable',
+      'dry-run cutover enable apply 必须把预期真实命令绑定到命令证据。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--require-arg',
+      'dry-run cutover enable apply 必须在命令证据脚本中要求真实命令参数。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--apply',
+      'dry-run cutover enable apply 必须显式带 --apply。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--current-release-audit-script',
+      'dry-run cutover enable apply 必须显式固定 current release 自审脚本。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs',
+      'dry-run cutover enable apply 必须使用 current release 随包自审脚本。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--current-release-root',
+      'dry-run cutover enable apply 必须显式固定 current release 根目录。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--preflight-check-service-user-cert-readable',
+      'dry-run cutover enable apply 必须验证 systemd 服务用户可读证书和私钥。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--preflight-check-service-env-file',
+      'dry-run cutover enable apply 必须验证 service EnvironmentFile 包含本次 env。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--preflight-check-service-binary-executable',
+      'dry-run cutover enable apply 必须验证 current release Pingora 二进制可执行。',
+    );
+    assertIncludes(
+      enableApply.args,
+      '--direct-spacetime-database',
+      'dry-run cutover enable apply 必须验证显式 SpacetimeDB 数据库名。',
+    );
+  }
+  if (!enableApplyVerify) {
+    failures.push('dry-run cutover 必须包含启用命令证据 manifest 只读验真。');
+  } else {
+    assertIncludes(
+      enableApplyVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '启用命令证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      enableApplyVerify.args,
+      '<enable-apply-bundle-dir>',
+      '启用命令证据验真必须提示替换刚生成的 enable apply bundleDir。',
+    );
+    assertIncludes(
+      enableApplyVerify.args,
+      '--require-summary-ok',
+      '启用命令证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
+
+  const postReadiness = findStep(plan, '启用后 release readiness 直连复核');
+  const postEnableSnapshot = findStep(plan, '启用后状态快照证据包');
+  const postEnableVerify = findStep(plan, '启用后证据 manifest 只读验真');
+  if (!postEnableSnapshot) {
+    failures.push('dry-run cutover 必须包含启用后状态快照证据包。');
+  } else {
+    assertIncludes(
+      postEnableSnapshot.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs',
+      '启用后状态快照证据包必须使用 current release 随包证据包脚本。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--snapshot-script',
+      '启用后状态快照证据包必须显式透传 snapshot 脚本。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--output-root',
+      '启用后状态快照证据包必须显式传证据输出根目录。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-status-snapshot.mjs',
+      '启用后状态快照证据包必须使用 current release 随包状态快照脚本。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      'pingora-direct',
+      '启用后状态快照证据包必须确认 pingora-direct 巡检口径。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--expected-pingora-env-mode',
+      '启用后状态快照证据包必须显式校验 active Pingora env 姿态。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      'direct',
+      '启用后状态快照证据包必须要求 active Pingora env 是 direct 姿态。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--expected-public-host',
+      '启用后状态快照证据包必须确认正式 Host 覆盖。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--run-health-patrol',
+      '启用后状态快照证据包必须执行生产健康巡检。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--direct-live-script',
+      '启用后状态快照证据包必须显式透传 direct live smoke 脚本。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '/opt/genarrative/current/scripts/check-pingora-direct-live.mjs',
+      '启用后状态快照证据包必须使用 current release 随包 direct live smoke。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--run-direct-live',
+      '启用后状态快照证据包必须归档 direct live smoke 证据。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--direct-pingora-access-log',
+      '启用后状态快照证据包必须归档 direct access log request_id 证据。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '/var/log/genarrative/pingora-gateway.access.log',
+      '启用后状态快照证据包必须使用显式 Pingora access log 路径。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--direct-spacetime-database',
+      '启用后状态快照证据包必须传递显式 SpacetimeDB 数据库名。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--require-pingora-gateway',
+      '启用后状态快照证据包必须收录 Pingora 发布物 checksum / manifest 自审。',
+    );
+  }
+  if (!postEnableVerify) {
+    failures.push('dry-run cutover 必须包含启用后证据 manifest 只读验真。');
+  } else {
+    assertIncludes(
+      postEnableVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '启用后证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      postEnableVerify.args,
+      '<post-enable-bundle-dir>',
+      '启用后证据验真必须提示替换刚生成的 post-enable bundleDir。',
+    );
+    assertIncludes(
+      postEnableVerify.args,
+      '--require-summary-ok',
+      '启用后证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
+  if (!postReadiness) {
+    failures.push(
+      'dry-run cutover 必须包含启用后 release readiness 直连复核。',
+    );
+  } else {
+    assertIncludes(
+      postReadiness.args,
+      '/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs',
+      '启用后 release readiness 直连复核必须使用 current release 随包 release readiness 聚合门禁脚本。',
+    );
+    assertIncludes(
+      postReadiness.args,
+      '--release-runtime-only',
+      '启用后 release readiness 直连复核必须使用 current release 包内运行时复核模式。',
+    );
+    assertIncludes(
+      postReadiness.args,
+      '--require-direct',
+      'dry-run cutover 启用后复核必须带 --require-direct。',
+    );
+    assertIncludes(
+      postReadiness.args,
+      '--direct-preflight-check-service-user-cert-readable',
+      'dry-run cutover 启用后复核必须检查 systemd 服务用户可读证书和私钥。',
+    );
+    assertIncludes(
+      postReadiness.args,
+      '--direct-preflight-check-service-env-file',
+      'dry-run cutover 启用后复核必须检查 service EnvironmentFile 包含本次 env。',
+    );
+    assertIncludes(
+      postReadiness.args,
+      '--direct-preflight-check-service-binary-executable',
+      'dry-run cutover 启用后复核必须检查 Pingora service 二进制可执行。',
+    );
+    assertIncludes(
+      postReadiness.args,
+      '--direct-preflight-systemd',
+      'dry-run cutover 启用后复核必须检查 systemd drop-in 生效。',
+    );
+    if (postReadiness.args.includes('--direct-preflight-check-ports-free')) {
+      failures.push(
+        'dry-run cutover 启用后 release readiness 复核不能继续要求 80/443 空闲；此时端口应由 Pingora 直连入口占用。',
+      );
+    }
+  }
+
+  const healthPatrolEnvCheck = findStep(
+    plan,
+    '启用后 health patrol env 直连复核',
+  );
+  if (!healthPatrolEnvCheck) {
+    failures.push('dry-run cutover 必须包含启用后 health patrol env 复核。');
+  } else {
+    assertIncludes(
+      healthPatrolEnvCheck.args,
+      '/opt/genarrative/current/scripts/check-production-health-patrol-env.mjs',
+      'dry-run cutover health patrol env 复核必须使用 current release 随包脚本。',
+    );
+    assertIncludes(
+      healthPatrolEnvCheck.args,
+      '/etc/genarrative/health-patrol.env',
+      'dry-run cutover health patrol env 复核必须检查目标 env 文件。',
+    );
+    assertIncludes(
+      healthPatrolEnvCheck.args,
+      '--expected-gateway-mode',
+      'dry-run cutover health patrol env 复核必须显式传 gateway mode。',
+    );
+    assertIncludes(
+      healthPatrolEnvCheck.args,
+      'pingora-direct',
+      'dry-run cutover health patrol env 复核必须要求 pingora-direct。',
+    );
+    assertIncludes(
+      healthPatrolEnvCheck.args,
+      '--expected-public-base-url',
+      'dry-run cutover health patrol env 复核必须校验 public base URL。',
+    );
+    assertIncludes(
+      healthPatrolEnvCheck.args,
+      '--expected-public-host',
+      'dry-run cutover health patrol env 复核必须校验正式 Host。',
+    );
+  }
+
+  const healthPatrolDirect = findStep(
+    plan,
+    '切换后 health patrol 切到 Pingora direct',
+  );
+  const healthPatrolDirectVerify = findStep(
+    plan,
+    '切换后 health patrol direct 命令证据 manifest 只读验真',
+  );
+  if (!healthPatrolDirect) {
+    failures.push(
+      'dry-run cutover 必须包含切换后 health patrol direct 模式脚本。',
+    );
+  } else {
+    assertIncludes(
+      healthPatrolDirect.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs',
+      'dry-run cutover 切换后 health patrol env 切换必须通过命令证据脚本归档。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--command-name',
+      'dry-run cutover 切换后 health patrol env 切换必须显式记录命令证据名称。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      'pingora-health-patrol-direct-env-switch',
+      'dry-run cutover 切换后 health patrol env 切换必须记录固定命令证据名称。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--expected-executable',
+      'dry-run cutover 切换后 health patrol env 切换必须绑定真实脚本身份。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+      'dry-run cutover 切换后必须使用 current release 随包 health patrol env 切换脚本。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--apply',
+      'dry-run cutover 切换后 health patrol env 切换必须显式带 --apply。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--env-file',
+      'dry-run cutover 切换后 health patrol env 切换必须显式传 env 文件。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '/etc/genarrative/health-patrol.env',
+      'dry-run cutover 切换后 health patrol env 切换必须使用显式 env 文件。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--gateway-mode',
+      'dry-run cutover 切换后 health patrol env 切换必须显式传 gateway mode。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      'pingora-direct',
+      'dry-run cutover 切换后 health patrol env 切换必须改为 pingora-direct。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--public-base-url',
+      'dry-run cutover 切换后 health patrol env 切换必须写 direct public base URL。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      'https://127.0.0.1',
+      'dry-run cutover 切换后 health patrol env 切换必须写 direct HTTPS base URL。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--public-host',
+      'dry-run cutover 切换后 health patrol env 切换必须写正式 Host。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      'example.com',
+      'dry-run cutover 切换后 health patrol env 切换必须使用正式 Host。',
+    );
+  }
+  if (!healthPatrolDirectVerify) {
+    failures.push(
+      'dry-run cutover 必须包含切换后 health patrol direct 命令证据 manifest 只读验真。',
+    );
+  } else {
+    assertIncludes(
+      healthPatrolDirectVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '切换后 health patrol direct 命令证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      healthPatrolDirectVerify.args,
+      '<health-patrol-direct-env-switch-bundle-dir>',
+      '切换后 health patrol direct 命令证据验真必须提示替换刚生成的 bundleDir。',
+    );
+    assertIncludes(
+      healthPatrolDirectVerify.args,
+      '--require-summary-ok',
+      '切换后 health patrol direct 命令证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
+  assertStepBefore(
+    plan,
+    'Pingora direct enable apply',
+    '启用命令证据 manifest 只读验真',
+    'dry-run cutover 必须先生成 enable apply 命令证据，再验真该命令证据。',
+  );
+  assertStepBefore(
+    plan,
+    '启用命令证据 manifest 只读验真',
+    '切换后 health patrol 切到 Pingora direct',
+    'dry-run cutover 必须先验真 enable apply 命令证据，再切换 health patrol 到 pingora-direct。',
+  );
+  assertStepBefore(
+    plan,
+    '切换后 health patrol 切到 Pingora direct',
+    '切换后 health patrol direct 命令证据 manifest 只读验真',
+    'dry-run cutover 必须先生成 health patrol direct env 命令证据，再验真该命令证据。',
+  );
+  assertStepBefore(
+    plan,
+    '切换后 health patrol direct 命令证据 manifest 只读验真',
+    '启用后 health patrol env 直连复核',
+    'dry-run cutover 必须先验真 health patrol direct env 命令证据，再执行直连 env 复核。',
+  );
+
+  const rollbackDryRun = findStep(plan, 'Pingora direct rollback dry-run');
+  if (!rollbackDryRun) {
+    failures.push('dry-run cutover 必须包含 rollback dry-run。');
+  } else {
+    assertIncludes(
+      rollbackDryRun.command,
+      '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+      'dry-run cutover rollback dry-run 必须使用 current release 随包回退脚本。',
+    );
+    if (rollbackDryRun.args.includes('--apply')) {
+      failures.push('dry-run cutover rollback dry-run 不能带 --apply。');
+    }
+    assertIncludes(
+      rollbackDryRun.args,
+      '--reload-nginx',
+      'dry-run cutover rollback dry-run 必须包含 Nginx reload。',
+    );
+    assertIncludes(
+      rollbackDryRun.args,
+      '--nginx-smoke-host',
+      'dry-run cutover rollback dry-run 使用 loopback smoke URL 时必须带正式 Host。',
+    );
+    assertIncludes(
+      rollbackDryRun.args,
+      '--nginx-smoke-expect-body',
+      'dry-run cutover rollback dry-run 必须校验 Nginx smoke 响应体片段。',
+    );
+    assertIncludes(
+      rollbackDryRun.args,
+      '<!doctype html>',
+      'dry-run cutover rollback dry-run 必须使用显式传入的 Nginx smoke body 片段。',
+    );
+    assertIncludes(
+      rollbackDryRun.args,
+      '--health-patrol-env-file',
+      'dry-run cutover rollback dry-run 必须把 health patrol env 复核交给回退脚本。',
+    );
+    assertIncludes(
+      rollbackDryRun.args,
+      '/etc/genarrative/health-patrol.env',
+      'dry-run cutover rollback dry-run 必须使用显式 health patrol env 文件。',
+    );
+    assertIncludes(
+      rollbackDryRun.args,
+      '--health-patrol-expected-public-base-url',
+      'dry-run cutover rollback dry-run 必须校验回退 health patrol public base URL。',
+    );
+    assertIncludes(
+      rollbackDryRun.args,
+      'http://127.0.0.1',
+      'dry-run cutover rollback dry-run 必须传递显式回退 public base URL。',
+    );
+    assertIncludes(
+      rollbackDryRun.args,
+      '--health-patrol-require-empty-public-host',
+      'dry-run cutover rollback dry-run 默认必须要求回退 public Host 为空。',
+    );
+  }
+
+  const rollbackApply = findStep(plan, 'Pingora direct rollback apply');
+  const rollbackApplyVerify = findStep(plan, '回退命令证据 manifest 只读验真');
+  if (!rollbackApply) {
+    failures.push('dry-run cutover 必须包含 rollback apply。');
+  } else {
+    assertIncludes(
+      rollbackApply.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs',
+      'dry-run cutover rollback apply 必须通过 current release 随包命令证据脚本归档执行输出。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--command-name',
+      'dry-run cutover rollback apply 必须显式记录命令证据名称。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      'pingora-direct-rollback-apply',
+      'dry-run cutover rollback apply 必须记录固定命令证据名称。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+      'dry-run cutover rollback apply 必须在命令证据脚本后执行 current release 随包回退脚本。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--expected-executable',
+      'dry-run cutover rollback apply 必须把预期真实命令绑定到命令证据。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--require-arg',
+      'dry-run cutover rollback apply 必须在命令证据脚本中要求真实命令参数。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--apply',
+      'dry-run cutover rollback apply 必须显式带 --apply。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      'https://example.com/',
+      'dry-run cutover rollback apply 必须包含 Nginx smoke URL。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      'example.com',
+      'dry-run cutover rollback apply 默认必须复用 direct Host 作为 Nginx smoke Host。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--nginx-smoke-host',
+      'dry-run cutover rollback apply 使用 loopback smoke URL 时必须带正式 Host。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--nginx-smoke-expect-body',
+      'dry-run cutover rollback apply 必须校验 Nginx smoke 响应体片段。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '<!doctype html>',
+      'dry-run cutover rollback apply 必须使用显式传入的 Nginx smoke body 片段。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--health-patrol-env-file',
+      'dry-run cutover rollback apply 必须把 health patrol env 复核交给回退脚本。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--health-patrol-expected-public-base-url',
+      'dry-run cutover rollback apply 必须校验回退 health patrol public base URL。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      'http://127.0.0.1',
+      'dry-run cutover rollback apply 必须传递显式回退 public base URL。',
+    );
+    assertIncludes(
+      rollbackApply.args,
+      '--health-patrol-require-empty-public-host',
+      'dry-run cutover rollback apply 默认必须要求回退 public Host 为空。',
+    );
+  }
+  if (!rollbackApplyVerify) {
+    failures.push('dry-run cutover 必须包含回退命令证据 manifest 只读验真。');
+  } else {
+    assertIncludes(
+      rollbackApplyVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '回退命令证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      rollbackApplyVerify.args,
+      '<rollback-apply-bundle-dir>',
+      '回退命令证据验真必须提示替换刚生成的 rollback apply bundleDir。',
+    );
+    assertIncludes(
+      rollbackApplyVerify.args,
+      '--require-summary-ok',
+      '回退命令证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
+
+  const healthPatrolNginx = findStep(plan, '回退前 health patrol 预置回 Nginx');
+  const pingoraEnvShadow = findStep(plan, '回退前 Pingora env 预置回 shadow');
+  const pingoraEnvShadowVerify = findStep(
+    plan,
+    '回退前 Pingora env shadow 命令证据 manifest 只读验真',
+  );
+  const healthPatrolNginxVerify = findStep(
+    plan,
+    '回退前 health patrol nginx 命令证据 manifest 只读验真',
+  );
+  if (!pingoraEnvShadow) {
+    failures.push(
+      'dry-run cutover 必须包含回退前 Pingora env shadow 配置预置确认。',
+    );
+  } else {
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs',
+      'dry-run cutover 回退前 Pingora env shadow 预置必须通过命令证据脚本归档。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '--command-name',
+      'dry-run cutover 回退前 Pingora env shadow 预置必须显式记录命令证据名称。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      'pingora-gateway-shadow-env-switch',
+      'dry-run cutover 回退前 Pingora env shadow 预置必须记录固定命令证据名称。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '--expected-executable',
+      'dry-run cutover 回退前 Pingora env shadow 预置必须绑定真实脚本身份。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+      'dry-run cutover 回退前必须使用 current release 随包 Pingora gateway env shadow 切换脚本。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '--apply',
+      'dry-run cutover 回退前 Pingora gateway env shadow 切换必须显式带 --apply。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '--env-file',
+      'dry-run cutover 回退前 Pingora gateway env shadow 切换必须显式传 env 文件。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '/tmp/pingora-gateway.env',
+      'dry-run cutover 回退前 Pingora gateway env shadow 切换必须使用显式 env 文件。',
+    );
+    if (!pingoraEnvShadow.when.includes('80/443 direct')) {
+      failures.push(
+        'dry-run cutover 回退前 Pingora env shadow 预置说明必须解释从 80/443 direct 配置恢复。',
+      );
+    }
+  }
+  if (!pingoraEnvShadowVerify) {
+    failures.push(
+      'dry-run cutover 必须包含回退前 Pingora env shadow 命令证据 manifest 只读验真。',
+    );
+  } else {
+    assertIncludes(
+      pingoraEnvShadowVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '回退前 Pingora env shadow 命令证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      pingoraEnvShadowVerify.args,
+      '<pingora-gateway-shadow-env-switch-bundle-dir>',
+      '回退前 Pingora env shadow 命令证据验真必须提示替换刚生成的 bundleDir。',
+    );
+    assertIncludes(
+      pingoraEnvShadowVerify.args,
+      '--require-summary-ok',
+      '回退前 Pingora env shadow 命令证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
+  if (!healthPatrolNginx) {
+    failures.push(
+      'dry-run cutover 必须包含回退前 health patrol Nginx 模式预置脚本。',
+    );
+  } else {
+    assertIncludes(
+      healthPatrolNginx.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs',
+      'dry-run cutover 回退前 health patrol env 切回 nginx 必须通过命令证据脚本归档。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--command-name',
+      'dry-run cutover 回退前 health patrol env 切回 nginx 必须显式记录命令证据名称。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      'pingora-health-patrol-nginx-env-switch',
+      'dry-run cutover 回退前 health patrol env 切回 nginx 必须记录固定命令证据名称。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--expected-executable',
+      'dry-run cutover 回退前 health patrol env 切回 nginx 必须绑定真实脚本身份。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+      'dry-run cutover 回退前必须使用 current release 随包 health patrol env 切换脚本。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--apply',
+      'dry-run cutover 回退前 health patrol env 切换必须显式带 --apply。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--gateway-mode',
+      'dry-run cutover 回退前 health patrol env 切换必须显式传 gateway mode。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      'nginx',
+      'dry-run cutover 回退前 health patrol env 切换必须改回 nginx。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--public-base-url',
+      'dry-run cutover 回退前 health patrol env 切换必须恢复 Nginx public base URL。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      'http://127.0.0.1',
+      'dry-run cutover 回退前 health patrol env 切换必须恢复切换前 Nginx public base URL。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--clear-public-host',
+      'dry-run cutover 回退前 health patrol env 切换必须清理 public Host 覆盖。',
+    );
+  }
+  if (!healthPatrolNginxVerify) {
+    failures.push(
+      'dry-run cutover 必须包含回退前 health patrol nginx 命令证据 manifest 只读验真。',
+    );
+  } else {
+    assertIncludes(
+      healthPatrolNginxVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '回退前 health patrol nginx 命令证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      healthPatrolNginxVerify.args,
+      '<health-patrol-nginx-env-switch-bundle-dir>',
+      '回退前 health patrol nginx 命令证据验真必须提示替换刚生成的 bundleDir。',
+    );
+    assertIncludes(
+      healthPatrolNginxVerify.args,
+      '--require-summary-ok',
+      '回退前 health patrol nginx 命令证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
+
+  const healthPatrolIndex = plan.findIndex(
+    (step) => step.name === '回退前 health patrol 预置回 Nginx',
+  );
+  const rollbackApplyIndex = plan.findIndex(
+    (step) => step.name === 'Pingora direct rollback apply',
+  );
+  const pingoraEnvShadowIndex = plan.findIndex(
+    (step) => step.name === '回退前 Pingora env 预置回 shadow',
+  );
+  if (
+    pingoraEnvShadowIndex >= 0 &&
+    rollbackApplyIndex >= 0 &&
+    pingoraEnvShadowIndex > rollbackApplyIndex
+  ) {
+    failures.push(
+      'dry-run cutover 必须先预置 Pingora shadow env，再执行 rollback apply。',
+    );
+  }
+  if (
+    healthPatrolIndex >= 0 &&
+    rollbackApplyIndex >= 0 &&
+    healthPatrolIndex > rollbackApplyIndex
+  ) {
+    failures.push(
+      'dry-run cutover 必须先预置 health patrol env，再执行 rollback apply。',
+    );
+  }
+  assertStepBefore(
+    plan,
+    '回退前 Pingora env 预置回 shadow',
+    '回退前 Pingora env shadow 命令证据 manifest 只读验真',
+    'dry-run cutover 必须先生成 Pingora shadow env 命令证据，再验真该命令证据。',
+  );
+  assertStepBefore(
+    plan,
+    '回退前 Pingora env shadow 命令证据 manifest 只读验真',
+    '回退前 health patrol 预置回 Nginx',
+    'dry-run cutover 必须先验真 Pingora shadow env 命令证据，再预置 health patrol nginx env。',
+  );
+  assertStepBefore(
+    plan,
+    '回退前 health patrol 预置回 Nginx',
+    '回退前 health patrol nginx 命令证据 manifest 只读验真',
+    'dry-run cutover 必须先生成 health patrol nginx env 命令证据，再验真该命令证据。',
+  );
+  assertStepBefore(
+    plan,
+    '回退前 health patrol nginx 命令证据 manifest 只读验真',
+    'Pingora direct rollback apply',
+    'dry-run cutover 必须先验真 health patrol nginx env 命令证据，再执行 rollback apply。',
+  );
+  assertStepBefore(
+    plan,
+    'Pingora direct rollback apply',
+    '回退命令证据 manifest 只读验真',
+    'dry-run cutover 必须先生成 rollback apply 命令证据，再验真该命令证据。',
+  );
+  assertStepBefore(
+    plan,
+    '回退命令证据 manifest 只读验真',
+    '回退后 health patrol env Nginx 模式复核',
+    'dry-run cutover 必须先验真 rollback apply 命令证据，再执行回退后 env 复核。',
+  );
+
+  const healthPatrolNginxCheck = findStep(
+    plan,
+    '回退后 health patrol env Nginx 模式复核',
+  );
+  if (!healthPatrolNginxCheck) {
+    failures.push(
+      'dry-run cutover 必须包含回退后 health patrol env Nginx 模式复核。',
+    );
+  } else {
+    assertIncludes(
+      healthPatrolNginxCheck.args,
+      '/opt/genarrative/current/scripts/check-production-health-patrol-env.mjs',
+      'dry-run cutover 回退后 health patrol env 复核必须使用 current release 随包脚本。',
+    );
+    assertIncludes(
+      healthPatrolNginxCheck.args,
+      '--expected-gateway-mode',
+      'dry-run cutover 回退后 health patrol env 复核必须显式传 gateway mode。',
+    );
+    assertIncludes(
+      healthPatrolNginxCheck.args,
+      'nginx',
+      'dry-run cutover 回退后 health patrol env 复核必须要求 nginx。',
+    );
+    assertIncludes(
+      healthPatrolNginxCheck.args,
+      '--expected-public-base-url',
+      'dry-run cutover 回退后 health patrol env 复核必须校验 Nginx public base URL。',
+    );
+    assertIncludes(
+      healthPatrolNginxCheck.args,
+      'http://127.0.0.1',
+      'dry-run cutover 回退后 health patrol env 复核必须使用显式回退 public base URL。',
+    );
+    assertIncludes(
+      healthPatrolNginxCheck.args,
+      '--require-empty-public-host',
+      'dry-run cutover 回退后 health patrol env 复核必须要求清空 public Host。',
+    );
+  }
+
+  const postRollbackSnapshot = findStep(plan, '回退后状态快照证据包');
+  const postRollbackVerify = findStep(plan, '回退后证据 manifest 只读验真');
+  const evidenceRootAudit = findStep(plan, '切换证据根目录三阶段总审计');
+  if (!postRollbackSnapshot) {
+    failures.push('dry-run cutover 必须包含回退后状态快照证据包。');
+  } else {
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs',
+      '回退后状态快照证据包必须使用 current release 随包证据包脚本。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '--snapshot-script',
+      '回退后状态快照证据包必须显式透传 snapshot 脚本。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '--output-root',
+      '回退后状态快照证据包必须显式传证据输出根目录。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-status-snapshot.mjs',
+      '回退后状态快照证据包必须使用 current release 随包状态快照脚本。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      'nginx',
+      '回退后状态快照证据包必须确认 nginx 巡检口径。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '--expected-pingora-env-mode',
+      '回退后状态快照证据包必须显式校验 active Pingora env 姿态。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      'shadow',
+      '回退后状态快照证据包必须要求 active Pingora env 已恢复 shadow 姿态。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '--require-empty-public-host',
+      '默认回退后状态快照证据包必须要求 public Host 为空。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '--run-health-patrol',
+      '回退后状态快照证据包必须执行生产健康巡检。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '--require-pingora-gateway',
+      '回退后状态快照证据包必须收录 Pingora 发布物 checksum / manifest 自审。',
+    );
+  }
+  if (!postRollbackVerify) {
+    failures.push('dry-run cutover 必须包含回退后证据 manifest 只读验真。');
+  } else {
+    assertIncludes(
+      postRollbackVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '回退后证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      postRollbackVerify.args,
+      '<post-rollback-bundle-dir>',
+      '回退后证据验真必须提示替换刚生成的 post-rollback bundleDir。',
+    );
+    assertIncludes(
+      postRollbackVerify.args,
+      '--require-summary-ok',
+      '回退后证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
+  if (!evidenceRootAudit) {
+    failures.push('dry-run cutover 必须包含切换证据根目录三阶段总审计。');
+  } else {
+    assertIncludes(
+      evidenceRootAudit.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs',
+      '三阶段总审计必须使用 current release 随包 evidence audit 脚本。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--evidence-root',
+      '三阶段总审计必须显式传证据根目录。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '/var/log/genarrative/pingora-cutover-evidence',
+      '三阶段总审计必须使用固定证据根目录。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--verify-script',
+      '三阶段总审计必须显式固定 verifier 脚本。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '三阶段总审计必须复用 current release 随包 verifier。',
+    );
+    for (const phase of ['pre-cutover', 'post-enable', 'post-rollback']) {
+      assertIncludes(
+        evidenceRootAudit.args,
+        phase,
+        `三阶段总审计必须要求 ${phase} 证据。`,
+      );
+    }
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--require-phase-direct-live-access-log',
+      '三阶段总审计必须要求 post-enable 阶段带 direct live access log 对账摘要。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      'post-enable',
+      '三阶段总审计必须把 direct live access log 摘要要求绑定到 post-enable 阶段。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--require-phase-direct-live-static-headers',
+      '三阶段总审计必须要求 post-enable 阶段带 direct live 静态响应头摘要。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      'post-enable',
+      '三阶段总审计必须把 direct live 静态响应头摘要要求绑定到 post-enable 阶段。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--require-phase-pingora-env-shadow',
+      '三阶段总审计必须要求 post-rollback 阶段带 Pingora env shadow 摘要。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      'post-rollback',
+      '三阶段总审计必须把 Pingora env shadow 摘要要求绑定到 post-rollback 阶段。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--require-command',
+      '三阶段总审计必须显式要求真实切换命令证据。',
+    );
+    for (const command of [
+      'enable-apply:pingora-direct-enable-apply',
+      'post-enable:pingora-health-patrol-direct-env-switch',
+      'rollback-prep:pingora-gateway-shadow-env-switch',
+      'rollback-prep:pingora-health-patrol-nginx-env-switch',
+      'rollback-apply:pingora-direct-rollback-apply',
+    ]) {
+      assertIncludes(
+        evidenceRootAudit.args,
+        command,
+        `三阶段总审计必须要求 ${command} 命令证据。`,
+      );
+    }
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--require-command-executable',
+      '三阶段总审计必须显式要求真实切换脚本身份。',
+    );
+    for (const commandExecutable of [
+      'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+      'post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+      'rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+      'rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+      'rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+    ]) {
+      assertIncludes(
+        evidenceRootAudit.args,
+        commandExecutable,
+        `三阶段总审计必须要求 ${commandExecutable} 命令脚本身份。`,
+      );
+    }
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--require-command-arg',
+      '三阶段总审计必须显式要求真实切换命令必需参数。',
+    );
+    for (const commandArg of [
+      'enable-apply:pingora-direct-enable-apply:--apply',
+      'post-enable:pingora-health-patrol-direct-env-switch:--apply',
+      'post-enable:pingora-health-patrol-direct-env-switch:pingora-direct',
+      'rollback-prep:pingora-gateway-shadow-env-switch:--apply',
+      'rollback-prep:pingora-health-patrol-nginx-env-switch:--apply',
+      'rollback-prep:pingora-health-patrol-nginx-env-switch:nginx',
+      'rollback-apply:pingora-direct-rollback-apply:--apply',
+    ]) {
+      assertIncludes(
+        evidenceRootAudit.args,
+        commandArg,
+        `三阶段总审计必须要求 ${commandArg} 命令参数。`,
+      );
+    }
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--timeline-max-span-ms',
+      '三阶段总审计必须显式传标准切换时间线最大跨度。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '86400000',
+      '三阶段总审计默认必须把标准切换时间线最大跨度固定为 24 小时。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--require-cutover-run-id',
+      '三阶段总审计必须要求同一 cutoverRunId。',
+    );
+  }
+
+}
+
+function assertDryRunCutoverPlanCanOverrideEvidenceTimelineMaxSpan() {
+  const plan = readPlan(cutoverPlanArgs(
+    '--cutover-evidence-timeline-max-span-ms',
+    '172800000',
+  ));
+  const evidenceRootAudit = findStep(plan, '切换证据根目录三阶段总审计');
+  if (!evidenceRootAudit) {
+    failures.push('dry-run cutover 必须包含切换证据根目录三阶段总审计。');
+    return;
+  }
+  assertIncludes(
+    evidenceRootAudit.args,
+    '--timeline-max-span-ms',
+    '三阶段总审计必须传递自定义标准切换时间线最大跨度参数。',
+  );
+  assertIncludes(
+    evidenceRootAudit.args,
+    '172800000',
+    '三阶段总审计必须传递自定义标准切换时间线最大跨度值。',
+  );
+}
+
+function assertDryRunCutoverPlanAvoidsManualEvidenceEscapeHatches() {
+  const plan = readPlan(cutoverPlanArgs());
+  const forbiddenArgs = [
+    '--warn-only',
+    '--allow-extra-files',
+    '--allow-extra-root-entries',
+  ];
+
+  for (const step of plan) {
+    for (const forbiddenArg of forbiddenArgs) {
+      assertNotIncludes(
+        step.args || [],
+        forbiddenArg,
+        `正式 dry-run cutover 计划的 ${step.name} 不能携带人工排障放行参数 ${forbiddenArg}。`,
+      );
+    }
+  }
+}
+
+function assertTechnicalDocCutoverAuditExamplesRequireCommandExecutables() {
+  const docPath =
+    'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md';
+  const content = readFileSync(docPath, 'utf8');
+  const executableArgs = [
+    '--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+    '--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+  ];
+  const auditExamples = [
+    ...content.matchAll(
+      /\/opt\/genarrative\/current\/scripts\/ops\/pingora-cutover-evidence-audit\.mjs[\s\S]*?(?=。|` 生成总审计 JSON|`，由脚本|`。)/gu,
+    ),
+  ]
+    .map((match) => match[0])
+    .filter(
+      (example) =>
+        example.includes(
+          '--require-command enable-apply:pingora-direct-enable-apply',
+        ) ||
+        example.includes(
+          '--require-command rollback-apply:pingora-direct-rollback-apply',
+        ),
+    );
+
+  if (auditExamples.length === 0) {
+    failures.push('Pingora 技术文档必须包含最终证据根目录总审计命令示例。');
+    return;
+  }
+  for (const example of auditExamples) {
+    for (const executableArg of executableArgs) {
+      assertIncludes(
+        example,
+        executableArg,
+        'Pingora 技术文档里的最终证据根目录总审计命令示例必须要求真实脚本身份。',
+      );
+    }
+  }
+}
+
+function assertDryRunCutoverPlanIncludesHostConsistencyConfirmation() {
+  const plan = readPlan(cutoverPlanArgs(
+    '--cutover-release-root',
+    '/opt/genarrative/current',
+  ));
+  const step = findStep(plan, '切换 Host 一致性确认');
+  if (!step) {
+    failures.push('dry-run cutover 必须包含 Host 一致性确认步骤。');
+    return;
+  }
+  if (
+    !step.args.some((arg) => String(arg).startsWith('cutover-run-id='))
+  ) {
+    failures.push('dry-run cutover Host 一致性确认必须展示 cutoverRunId。');
+  }
+  assertIncludes(
+    step.args,
+    'direct-host=example.com',
+    'dry-run cutover Host 一致性确认必须展示 direct Host。',
+  );
+  assertIncludes(
+    step.args,
+    'direct-redirect-host=example.com',
+    'dry-run cutover Host 一致性确认必须展示 redirect Host。',
+  );
+  assertIncludes(
+    step.args,
+    'health-patrol-public-host=example.com',
+    'dry-run cutover Host 一致性确认必须展示 health patrol Host。',
+  );
+  assertIncludes(
+    step.args,
+    'rollback-nginx-smoke-host=example.com',
+    'dry-run cutover Host 一致性确认必须展示 rollback smoke Host。',
+  );
+  assertIncludes(
+    step.args,
+    'rollback-nginx-smoke-expect-body=<!doctype html>',
+    'dry-run cutover Host 一致性确认必须展示 rollback smoke body 证据片段。',
+  );
+  assertIncludes(
+    step.args,
+    'rollback-health-patrol-public-base-url=http://127.0.0.1',
+    'dry-run cutover Host 一致性确认必须展示回退 health patrol public base URL。',
+  );
+  assertIncludes(
+    step.args,
+    'rollback-health-patrol-public-host=',
+    'dry-run cutover Host 一致性确认必须展示回退 health patrol public Host 为空。',
+  );
+}
+
+function assertDryRunCutoverPlanCarriesCutoverRunId() {
+  const plan = readPlan(cutoverPlanArgs(
+    '--cutover-run-id',
+    'cutover-20260617T010000Z',
+  ));
+  const hostConsistency = findStep(plan, '切换 Host 一致性确认');
+  if (!hostConsistency) {
+    failures.push('dry-run cutover 必须包含 Host 一致性确认步骤。');
+  } else {
+    assertIncludes(
+      hostConsistency.args,
+      'cutover-run-id=cutover-20260617T010000Z',
+      'Host 一致性确认必须展示显式 cutoverRunId。',
+    );
+  }
+
+  for (const stepName of [
+    '切换前状态快照证据包',
+    'Pingora direct enable apply',
+    '启用后状态快照证据包',
+    'Pingora direct rollback apply',
+    '回退后状态快照证据包',
+  ]) {
+    const step = findStep(plan, stepName);
+    if (!step) {
+      failures.push(`dry-run cutover 必须包含 ${stepName}。`);
+      continue;
+    }
+    assertIncludes(
+      step.args,
+      '--cutover-run-id',
+      `${stepName} 必须传递 cutoverRunId。`,
+    );
+    assertIncludes(
+      step.args,
+      'cutover-20260617T010000Z',
+      `${stepName} 必须使用同一个 cutoverRunId。`,
+    );
+  }
+
+  const evidenceRootAudit = findStep(plan, '切换证据根目录三阶段总审计');
+  if (!evidenceRootAudit) {
+    failures.push('dry-run cutover 必须包含切换证据根目录三阶段总审计。');
+    return;
+  }
+  assertIncludes(
+    evidenceRootAudit.args,
+    '--require-cutover-run-id',
+    '三阶段总审计必须要求同一 cutoverRunId。',
+  );
+  assertIncludes(
+    evidenceRootAudit.args,
+    'cutover-20260617T010000Z',
+    '三阶段总审计必须使用同一个 cutoverRunId。',
+  );
+}
+
+function assertDryRunCutoverPlanGeneratesDefaultCutoverRunId() {
+  const plan = readPlan(cutoverPlanArgs());
+  const hostConsistency = findStep(plan, '切换 Host 一致性确认');
+  if (!hostConsistency) {
+    failures.push('dry-run cutover 必须包含 Host 一致性确认步骤。');
+    return;
+  }
+  const runArg = hostConsistency.args.find((arg) =>
+    String(arg).startsWith('cutover-run-id='),
+  );
+  if (!runArg) {
+    failures.push('dry-run cutover 未显式提供 run id 时必须自动生成 cutoverRunId。');
+    return;
+  }
+  const runId = runArg.slice('cutover-run-id='.length);
+  if (!/^pingora-direct-\d{8}T\d{6}Z$/u.test(runId)) {
+    failures.push(`自动生成的 cutoverRunId 格式不正确: ${runId}`);
+  }
+
+  const evidenceRootAudit = findStep(plan, '切换证据根目录三阶段总审计');
+  if (!evidenceRootAudit) {
+    failures.push('dry-run cutover 必须包含切换证据根目录三阶段总审计。');
+    return;
+  }
+  assertIncludes(
+    evidenceRootAudit.args,
+    runId,
+    '自动生成的 cutoverRunId 必须传给三阶段总审计。',
+  );
+}
+
+function assertDryRunCutoverExplicitRollbackBodyIgnoresProcessEnv() {
+  const previous =
+    process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY;
+  process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY =
+    'polluted-body';
+  try {
+    const plan = readPlan(cutoverPlanArgs(
+      '--cutover-release-root',
+      '/opt/genarrative/current',
+    ));
+    const rollbackApply = findStep(plan, 'Pingora direct rollback apply');
+    if (!rollbackApply) {
+      failures.push('dry-run cutover 必须包含 rollback apply。');
+      return;
+    }
+    assertIncludes(
+      rollbackApply.args,
+      '<!doctype html>',
+      'dry-run cutover 必须使用显式 rollback body 断言，且不能被本机 env 污染。',
+    );
+    if (rollbackApply.args.includes('polluted-body')) {
+      failures.push(
+        'readinessPlanEnv 必须清理 GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY，避免 plan 自测受本机 env 污染。',
+      );
+    }
+  } finally {
+    if (previous === undefined) {
+      delete process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY;
+    } else {
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY =
+        previous;
+    }
+  }
+}
+
+function assertDryRunCutoverPostEnableReadinessRedactsDirectProbeToken() {
+  const plan = readPlan(cutoverPlanArgs(
+    '--direct-probe-token',
+    'direct-secret-token',
+    '--cutover-release-root',
+    '/opt/genarrative/current',
+  ));
+  const step = findStep(plan, '启用后 release readiness 直连复核');
+  if (!step) {
+    failures.push('带 direct probe token 的 cutover runbook 必须包含启用后 readiness 复核。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--direct-probe-token',
+    '启用后 release readiness 直连复核必须继续传递 direct probe token 参数。',
+  );
+  assertIncludes(
+    step.args,
+    '<redacted>',
+    '启用后 release readiness 直连复核必须隐藏 direct probe token 值。',
+  );
+  if (JSON.stringify(plan).includes('direct-secret-token')) {
+    failures.push('dry-run cutover JSON 不能泄露 direct probe token 原文。');
+  }
+}
+
+function assertDryRunCutoverAllowsSameHostnameWithDifferentPorts() {
+  const plan = readPlan(cutoverPlanArgs(
+    '--direct-redirect-host',
+    'example.com:443',
+    '--cutover-release-root',
+    '/opt/genarrative/current',
+    '--rollback-nginx-smoke-host',
+    'example.com:80',
+  ));
+  const step = findStep(plan, '切换 Host 一致性确认');
+  if (!step) {
+    failures.push('dry-run cutover 同 hostname 不同端口时仍必须能生成计划。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'direct-redirect-host=example.com:443',
+    'dry-run cutover 应允许 redirect Host 使用同 hostname 的显式端口。',
+  );
+  assertIncludes(
+    step.args,
+    'rollback-nginx-smoke-host=example.com:80',
+    'dry-run cutover 应允许 rollback smoke Host 使用同 hostname 的显式端口。',
+  );
+  assertIncludes(
+    step.args,
+    'rollback-health-patrol-public-base-url=http://127.0.0.1',
+    'dry-run cutover 同 hostname 不同端口时仍必须展示回退 health patrol public base URL。',
+  );
+}
+
+function assertDryRunCutoverCanRestoreRollbackHealthPatrolPublicHost() {
+  const plan = readPlan(cutoverPlanArgs(
+    '--cutover-release-root',
+    '/opt/genarrative/current',
+    '--rollback-health-patrol-public-host',
+    'nginx.example.com',
+  ));
+  const healthPatrolNginx = findStep(plan, '回退前 health patrol 预置回 Nginx');
+  const hostConsistency = findStep(plan, '切换 Host 一致性确认');
+  if (!hostConsistency) {
+    failures.push('dry-run cutover 必须包含 Host 一致性确认步骤。');
+  } else {
+    assertIncludes(
+      hostConsistency.args,
+      'rollback-health-patrol-public-base-url=http://127.0.0.1',
+      'dry-run cutover Host 一致性确认必须展示回退 health patrol public base URL。',
+    );
+    assertIncludes(
+      hostConsistency.args,
+      'rollback-health-patrol-public-host=nginx.example.com',
+      'dry-run cutover Host 一致性确认必须展示显式回退 health patrol public Host。',
+    );
+  }
+
+  if (!healthPatrolNginx) {
+    failures.push(
+      'dry-run cutover 必须包含回退前 health patrol Nginx 模式预置脚本。',
+    );
+  } else {
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--public-host',
+      'dry-run cutover 回退前必须能恢复切换前 Nginx public Host。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      'nginx.example.com',
+      'dry-run cutover 回退前必须使用显式回退 public Host。',
+    );
+  }
+
+  const healthPatrolNginxCheck = findStep(
+    plan,
+    '回退后 health patrol env Nginx 模式复核',
+  );
+  if (!healthPatrolNginxCheck) {
+    failures.push(
+      'dry-run cutover 必须包含回退后 health patrol env Nginx 模式复核。',
+    );
+    return;
+  }
+  assertIncludes(
+    healthPatrolNginxCheck.args,
+    '--expected-public-host',
+    'dry-run cutover 回退后 health patrol env 复核必须能校验 Nginx public Host。',
+  );
+  assertIncludes(
+    healthPatrolNginxCheck.args,
+    'nginx.example.com',
+    'dry-run cutover 回退后 health patrol env 复核必须使用显式回退 public Host。',
+  );
+  if (healthPatrolNginxCheck.args.includes('--require-empty-public-host')) {
+    failures.push(
+      '显式提供回退 public Host 时，回退后 health patrol env 复核不能同时要求 Host 为空。',
+    );
+  }
+
+  for (const stepName of [
+    'Pingora direct rollback dry-run',
+    'Pingora direct rollback apply',
+  ]) {
+    const step = findStep(plan, stepName);
+    if (!step) {
+      failures.push(`dry-run cutover 必须包含 ${stepName}。`);
+      continue;
+    }
+    assertIncludes(
+      step.args,
+      '--health-patrol-expected-public-host',
+      `dry-run cutover ${stepName} 必须把显式回退 public Host 传给回退脚本。`,
+    );
+    assertIncludes(
+      step.args,
+      'nginx.example.com',
+      `dry-run cutover ${stepName} 必须使用显式回退 public Host。`,
+    );
+    if (step.args.includes('--health-patrol-require-empty-public-host')) {
+      failures.push(
+        `显式提供回退 public Host 时，${stepName} 不能同时要求 Host 为空。`,
+      );
+    }
+  }
+}
+
+function assertDryRunCutoverPlanCanIncludeRollbackShadowProbe() {
+  const plan = readPlan(cutoverPlanArgs(
+    '--cutover-release-root',
+    '/opt/genarrative/current',
+    '--rollback-pingora-shadow-probe-url',
+    'http://127.0.0.1:18081/__genarrative_pingora/healthz',
+    '--rollback-pingora-shadow-probe-token',
+    'probe-secret-token',
+  ));
+  const rollbackDryRun = findStep(plan, 'Pingora direct rollback dry-run');
+  const rollbackApply = findStep(plan, 'Pingora direct rollback apply');
+  for (const step of [rollbackDryRun, rollbackApply]) {
+    if (!step) {
+      failures.push('带 shadow probe 的 dry-run cutover 必须包含 rollback 步骤。');
+      continue;
+    }
+    assertIncludes(
+      step.args,
+      '--pingora-shadow-probe-url',
+      'dry-run cutover rollback 步骤必须传递 shadow probe URL。',
+    );
+    assertIncludes(
+      step.args,
+      'http://127.0.0.1:18081/__genarrative_pingora/healthz',
+      'dry-run cutover rollback 步骤必须保留 shadow probe URL。',
+    );
+    assertIncludes(
+      step.args,
+      '--pingora-shadow-probe-token',
+      'dry-run cutover rollback 步骤必须传递 shadow probe token 参数。',
+    );
+    assertIncludes(
+      step.args,
+      '<redacted>',
+      'dry-run cutover rollback 步骤必须隐藏 shadow probe token 值。',
+    );
+    if (step.args.includes('probe-secret-token')) {
+      failures.push('dry-run cutover JSON 不能泄露 shadow probe token 原文。');
+    }
+  }
+}
+
+function assertRequireLiveForcesHost() {
+  const plan = readPlan([...requireLiveBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Nginx live canary smoke');
+  if (!step) {
+    failures.push('--require-live 计划必须包含 live canary smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--host',
+    '--require-live 必须把正式域名 Host 传给 live canary smoke。',
+  );
+  assertIncludes(
+    step.args,
+    'example.com',
+    '--require-live live canary smoke 必须使用显式传入的正式域名 Host。',
+  );
+
+  const parity = findStep(plan, '目标 Nginx live canary access log 对账');
+  if (!parity) {
+    failures.push('--require-live 计划必须在 live smoke 后包含 access log 对账。');
+    return;
+  }
+  assertIncludes(
+    parity.args,
+    'scripts/check-pingora-canary-access-log-parity.mjs',
+    '--require-live 必须调用 canary access log 对账脚本。',
+  );
+  assertIncludes(
+    parity.args,
+    '--nginx-log-file',
+    '--require-live access log 对账必须显式传 Nginx access log。',
+  );
+  assertIncludes(
+    parity.args,
+    '/var/log/nginx/genarrative.access.log',
+    '--require-live access log 对账必须使用显式 Nginx access log 路径。',
+  );
+  assertIncludes(
+    parity.args,
+    '--pingora-log-file',
+    '--require-live access log 对账必须显式传 Pingora access log。',
+  );
+  assertIncludes(
+    parity.args,
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--require-live access log 对账必须使用显式 Pingora access log 路径。',
+  );
+  assertIncludes(
+    parity.args,
+    '--since-lines',
+    '--require-live access log 对账必须显式传 tail 行数。',
+  );
+  assertIncludes(
+    parity.args,
+    '3000',
+    '--require-live access log 对账必须使用显式 tail 行数。',
+  );
+  assertIncludes(
+    parity.args,
+    '/__genarrative_pingora_canary/healthz',
+    '--require-live access log 对账必须覆盖 canary healthz。',
+  );
+  assertIncludes(
+    parity.args,
+    '/__genarrative_pingora_canary/api/creation-entry/config',
+    '--require-live access log 对账必须覆盖代表性 API canary 路径。',
+  );
+}
+
+function assertRequireRealpathLiveForcesHostAndRealpathParity() {
+  const plan = readPlan([...requireRealpathLiveBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Nginx realpath canary smoke');
+  if (!step) {
+    failures.push('--require-realpath-live 计划必须包含 realpath canary smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--realpath',
+    '--require-realpath-live 必须把 live smoke 切到真实路径 canary 模式。',
+  );
+  assertIncludes(
+    step.args,
+    '--host',
+    '--require-realpath-live 必须把正式域名 Host 传给 realpath live canary smoke。',
+  );
+  assertIncludes(
+    step.args,
+    'example.com',
+    '--require-realpath-live realpath smoke 必须使用显式传入的正式域名 Host。',
+  );
+
+  const parity = findStep(plan, '目标 Nginx realpath canary access log 对账');
+  if (!parity) {
+    failures.push(
+      '--require-realpath-live 计划必须在 realpath smoke 后包含 access log 对账。',
+    );
+    return;
+  }
+  assertIncludes(
+    parity.args,
+    '--realpath',
+    '--require-realpath-live access log 对账必须使用真实路径模式。',
+  );
+  assertIncludes(
+    parity.args,
+    '/var/log/nginx/genarrative-pingora-realpath-canary.access.log',
+    '--require-realpath-live access log 对账必须使用独立 Nginx realpath canary access log。',
+  );
+  assertIncludes(
+    parity.args,
+    '/__genarrative_pingora_realpath_canary/healthz',
+    '--require-realpath-live access log 对账必须覆盖 realpath healthz。',
+  );
+  assertIncludes(
+    parity.args,
+    '/api/creation-entry/config',
+    '--require-realpath-live access log 对账必须覆盖真实 API 路径。',
+  );
+  assertIncludes(
+    parity.args,
+    '/v1/identity',
+    '--require-realpath-live access log 对账必须覆盖真实 SpacetimeDB identity 路径。',
+  );
+  assertIncludes(
+    parity.args,
+    '/assets/app.js',
+    '--require-realpath-live access log 对账必须覆盖真实静态资源路径。',
+  );
+}
+
+function assertReleaseRuntimeOnlyPlanUsesCurrentReleaseScripts() {
+  const plan = readPlan([
+    ...requireLiveBaseArgs,
+    ...requireRealpathLiveBaseArgs,
+    ...requireDirectBaseArgs,
+    '--release-runtime-only',
+    '--dry-run-plan',
+  ]);
+  const sourceOnlyNames = new Set([
+    'Rust 路由与保护单测',
+    'Pingora mock 上游 smoke',
+    'Nginx/Pingora 路由矩阵 parity',
+    'Pingora production release 真实构建烟测',
+    'API deploy release 烟测',
+  ]);
+  for (const name of sourceOnlyNames) {
+    if (findStep(plan, name)) {
+      failures.push(`release runtime-only 计划不能包含源码全量门禁: ${name}。`);
+    }
+  }
+
+  const audit = findStep(plan, 'current release 自包含自审');
+  if (!audit) {
+    failures.push('release runtime-only 计划必须先包含 current release 自包含自审。');
+  } else {
+    assertAbsoluteScriptArg(
+      audit.args,
+      'scripts/ops/pingora-current-release-audit.mjs',
+      'release runtime-only 自审必须使用随当前脚本定位的包内自审脚本。',
+    );
+    assertIncludes(
+      audit.args,
+      '--release-root',
+      'release runtime-only 自审必须显式传 current release 根目录。',
+    );
+    assertIncludes(
+      audit.args,
+      '--require-pingora-gateway',
+      'release runtime-only direct 复核必须要求 Pingora 发布物存在。',
+    );
+    assertIncludes(
+      audit.args,
+      '--systemd-show',
+      'release runtime-only direct 复核必须核验 systemd ExecStart。',
+    );
+  }
+
+  const live = findStep(plan, '目标 Nginx live canary smoke');
+  if (!live) {
+    failures.push('release runtime-only 计划必须包含 live canary smoke。');
+  } else {
+    assertAbsoluteScriptArg(
+      live.args,
+      'scripts/check-pingora-canary-live.mjs',
+      'release runtime-only live canary smoke 必须使用随当前脚本定位的包内脚本。',
+    );
+  }
+
+  const liveParity = findStep(plan, '目标 Nginx live canary access log 对账');
+  if (!liveParity) {
+    failures.push('release runtime-only 计划必须包含 live access log 对账。');
+  } else {
+    assertAbsoluteScriptArg(
+      liveParity.args,
+      'scripts/check-pingora-canary-access-log-parity.mjs',
+      'release runtime-only live access log 对账必须使用随当前脚本定位的包内脚本。',
+    );
+  }
+
+  const realpathLive = findStep(plan, '目标 Nginx realpath canary smoke');
+  if (!realpathLive) {
+    failures.push('release runtime-only 计划必须包含 realpath live canary smoke。');
+  } else {
+    assertAbsoluteScriptArg(
+      realpathLive.args,
+      'scripts/check-pingora-canary-live.mjs',
+      'release runtime-only realpath live canary smoke 必须使用随当前脚本定位的包内脚本。',
+    );
+    assertIncludes(
+      realpathLive.args,
+      '--realpath',
+      'release runtime-only realpath live canary smoke 必须传 --realpath。',
+    );
+  }
+
+  const realpathParity = findStep(
+    plan,
+    '目标 Nginx realpath canary access log 对账',
+  );
+  if (!realpathParity) {
+    failures.push('release runtime-only 计划必须包含 realpath live access log 对账。');
+  } else {
+    assertAbsoluteScriptArg(
+      realpathParity.args,
+      'scripts/check-pingora-canary-access-log-parity.mjs',
+      'release runtime-only realpath access log 对账必须使用随当前脚本定位的包内脚本。',
+    );
+    assertIncludes(
+      realpathParity.args,
+      '--realpath',
+      'release runtime-only realpath access log 对账必须传 --realpath。',
+    );
+  }
+
+  const preflight = findStep(plan, '目标 Pingora direct entry preflight');
+  if (!preflight) {
+    failures.push('release runtime-only 计划必须包含 direct preflight。');
+  } else {
+    assertAbsoluteScriptArg(
+      preflight.args,
+      'scripts/check-pingora-direct-preflight.mjs',
+      'release runtime-only direct preflight 必须使用随当前脚本定位的包内脚本。',
+    );
+  }
+
+  const healthPatrol = findStep(plan, '目标 health patrol env 直连模式复核');
+  if (!healthPatrol) {
+    failures.push('release runtime-only 计划必须包含 health patrol env 复核。');
+  } else {
+    assertAbsoluteScriptArg(
+      healthPatrol.args,
+      'scripts/check-production-health-patrol-env.mjs',
+      'release runtime-only health patrol env 复核必须使用随当前脚本定位的包内脚本。',
+    );
+  }
+
+  const direct = findStep(plan, '目标 Pingora direct live smoke');
+  if (!direct) {
+    failures.push('release runtime-only 计划必须包含 direct live smoke。');
+  } else {
+    assertAbsoluteScriptArg(
+      direct.args,
+      'scripts/check-pingora-direct-live.mjs',
+      'release runtime-only direct live smoke 必须使用随当前脚本定位的包内脚本。',
+    );
+  }
+}
+
+function assertReleaseRuntimeOnlyPlanIncludesDirectRehearsalStatus() {
+  const basePlan = readPlan(['--release-runtime-only', '--dry-run-plan']);
+  const baseStep = findStep(
+    basePlan,
+    '目标 Pingora direct rehearsal 状态复核',
+  );
+  if (!baseStep) {
+    failures.push(
+      'release runtime-only 基础计划必须包含直连彩排状态复核。',
+    );
+    return;
+  }
+  assertAbsoluteScriptArg(
+    baseStep.args,
+    'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    'release runtime-only 直连彩排状态复核必须使用 current release 随包脚本。',
+  );
+  assertIncludes(
+    baseStep.args,
+    '--release-root',
+    'release runtime-only 直连彩排状态复核必须显式传 current release 根目录。',
+  );
+  assertIncludes(
+    baseStep.args,
+    '--expect-public-gateway',
+    'release runtime-only 直连彩排状态复核必须声明公网入口期望。',
+  );
+  assertIncludes(
+    baseStep.args,
+    'nginx',
+    'release runtime-only 直连彩排状态复核必须确认 Nginx 仍接公网。',
+  );
+  assertIncludes(
+    baseStep.args,
+    '--require-pingora-shadow',
+    'release runtime-only 直连彩排状态复核必须要求 Pingora shadow 高端口在线。',
+  );
+  assertIncludes(
+    baseStep.args,
+    '--require-realpath-canary',
+    'release runtime-only 直连彩排状态复核必须要求 realpath canary 高端口在线。',
+  );
+  assertIncludes(
+    baseStep.args,
+    '--require-current-release-gateway',
+    'release runtime-only 直连彩排状态复核必须复用 current release Pingora 自审。',
+  );
+  assertIncludes(
+    baseStep.args,
+    '--fail-on-critical',
+    'release runtime-only 直连彩排状态复核出现 CRITICAL 必须阻断门禁。',
+  );
+
+  const directPlan = readPlan([
+    ...requireDirectBaseArgs,
+    '--release-runtime-only',
+    '--dry-run-plan',
+  ]);
+  if (findStep(directPlan, '目标 Pingora direct rehearsal 状态复核')) {
+    failures.push(
+      'release runtime-only --require-direct 阶段不能继续要求 Nginx 接公网的彩排状态。',
+    );
+  }
+}
+
+function assertReleaseRuntimeOnlyAllowsRealpathOnlyCanary() {
+  const plan = readPlan([
+    ...requireRealpathLiveBaseArgs,
+    '--release-runtime-only',
+    '--dry-run-plan',
+  ]);
+  const prefixLive = findStep(plan, '目标 Nginx live canary smoke');
+  if (prefixLive) {
+    failures.push(
+      'release runtime-only 只要求 realpath canary 时不能强制执行前缀 canary smoke。',
+    );
+  }
+  const prefixParity = findStep(plan, '目标 Nginx live canary access log 对账');
+  if (prefixParity) {
+    failures.push(
+      'release runtime-only 只要求 realpath canary 时不能强制执行前缀 canary access log 对账。',
+    );
+  }
+
+  const realpathLive = findStep(plan, '目标 Nginx realpath canary smoke');
+  if (!realpathLive) {
+    failures.push(
+      'release runtime-only 只要求 realpath canary 时必须包含 realpath smoke。',
+    );
+  } else {
+    assertAbsoluteScriptArg(
+      realpathLive.args,
+      'scripts/check-pingora-canary-live.mjs',
+      'release runtime-only realpath-only smoke 必须使用 current release 随包脚本。',
+    );
+    assertIncludes(
+      realpathLive.args,
+      '--realpath',
+      'release runtime-only realpath-only smoke 必须传 --realpath。',
+    );
+  }
+
+  const realpathParity = findStep(
+    plan,
+    '目标 Nginx realpath canary access log 对账',
+  );
+  if (!realpathParity) {
+    failures.push(
+      'release runtime-only 只要求 realpath canary 时必须包含 realpath access log 对账。',
+    );
+  } else {
+    assertAbsoluteScriptArg(
+      realpathParity.args,
+      'scripts/check-pingora-canary-access-log-parity.mjs',
+      'release runtime-only realpath-only 对账必须使用 current release 随包脚本。',
+    );
+    assertIncludes(
+      realpathParity.args,
+      '--realpath',
+      'release runtime-only realpath-only 对账必须传 --realpath。',
+    );
+  }
+}
+
+function assertReleaseRuntimeOnlyKeepsInvokedCurrentSymlinkPath() {
+  const tmpRoot = mkdtempSync(
+    path.join(tmpdir(), 'genarrative-release-readiness-current-'),
+  );
+  try {
+    const releaseDir = path.join(tmpRoot, 'releases', 'test-release');
+    const currentLink = path.join(tmpRoot, 'current');
+    const scriptDir = path.join(releaseDir, 'scripts');
+    mkdirSync(scriptDir, { recursive: true });
+    symlinkSync(releaseDir, currentLink, 'dir');
+    const invokedScript = path.join(
+      currentLink,
+      'scripts',
+      'check-pingora-release-readiness.mjs',
+    );
+    const realScript = path.join(
+      scriptDir,
+      'check-pingora-release-readiness.mjs',
+    );
+    symlinkSync(
+      path.join(process.cwd(), 'scripts/check-pingora-release-readiness.mjs'),
+      realScript,
+    );
+
+    const result = spawnSync(
+      'node',
+      [invokedScript, '--release-runtime-only', '--dry-run-plan'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: readinessPlanEnv(),
+      },
+    );
+    if ((result.status ?? 0) !== 0) {
+      failures.push(
+        `通过 current symlink 读取 runtime-only plan 失败，退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      );
+      return;
+    }
+    const plan = JSON.parse(result.stdout);
+    const audit = findStep(plan, 'current release 自包含自审');
+    const rehearsal = findStep(plan, '目标 Pingora direct rehearsal 状态复核');
+    for (const [label, step] of [
+      ['current release 自审', audit],
+      ['直连彩排状态复核', rehearsal],
+    ]) {
+      if (!step) {
+        failures.push(
+          `通过 current symlink 生成的 runtime-only plan 缺少${label}步骤。`,
+        );
+        continue;
+      }
+      assertIncludes(
+        step.args,
+        currentLink,
+        `${label}必须保留调用方 current symlink 作为 release root，而不是展开到真实 release 目录。`,
+      );
+      if (step.args.includes(releaseDir)) {
+        failures.push(
+          `${label}不应把 current symlink 展开成真实 release 目录: ${releaseDir}`,
+        );
+      }
+    }
+  } catch (error) {
+    failures.push(`current symlink runtime-only plan 自测异常: ${error.message}`);
+  } finally {
+    rmSync(tmpRoot, { recursive: true, force: true });
+  }
+}
+
+function assertReleaseRuntimeOnlyRejectsSourceOnlyFlags() {
+  for (const flag of ['--require-docker', '--pull-docker', '--require-nginx']) {
+    const result = runReadinessExpectFailure([
+      '--release-runtime-only',
+      flag,
+      '--dry-run-plan',
+    ]);
+    assertFailureIncludes(
+      result,
+      '--release-runtime-only 只执行 current release 包内运行时复核',
+      `release runtime-only 不能同时接受源码或本机依赖参数 ${flag}。`,
+    );
+  }
+}
+
+function assertRequireDirectForcesWssUpgrade() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct live smoke');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct live smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--require-wss-upgrade',
+    '--require-direct 必须自动强制 WSS subscribe 返回 101。',
+  );
+}
+
+function assertRequireDirectForcesHttpBaseUrl() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct live smoke');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct live smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--http-base-url',
+    '--require-direct 必须把 HTTP redirect / ACME 入口纳入 direct live smoke。',
+  );
+}
+
+function assertRequireDirectForcesHostSni() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct live smoke');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct live smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--host',
+    '--require-direct 必须把正式域名 Host/SNI 传给 direct live smoke。',
+  );
+  assertIncludes(
+    step.args,
+    'example.com',
+    '--require-direct direct live smoke 必须使用显式传入的正式域名 Host/SNI。',
+  );
+}
+
+function assertRequireDirectForcesRedirectHost() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct live smoke');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct live smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--redirect-host',
+    '--require-direct 必须把显式 redirect Location host 传给 direct live smoke。',
+  );
+  assertIncludes(
+    step.args,
+    'example.com',
+    '--require-direct direct live smoke 必须使用显式传入的 redirect Location host。',
+  );
+}
+
+function assertRequireDirectForcesPingoraAccessLog() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct live smoke');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct live smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--pingora-access-log',
+    '--require-direct 必须把 Pingora access log 落盘校验传给 direct live smoke。',
+  );
+  assertIncludes(
+    step.args,
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--require-direct direct live smoke 必须使用显式 Pingora access log 路径。',
+  );
+}
+
+function assertRequireDirectForcesPreflightSystemdCertReadable() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct entry preflight');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct entry preflight。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--systemd-cat',
+    '--require-direct 必须检查 systemd drop-in 最终生效配置。',
+  );
+  assertIncludes(
+    step.args,
+    '--check-cert-readable',
+    '--require-direct 必须检查当前用户可读 TLS 证书和私钥。',
+  );
+  assertIncludes(
+    step.args,
+    '--check-service-env-file',
+    '--require-direct 必须检查 service EnvironmentFile 包含本次 env。',
+  );
+  assertIncludes(
+    step.args,
+    '--check-service-user-cert-readable',
+    '--require-direct 必须检查 systemd 服务用户可读 TLS 证书和私钥。',
+  );
+  assertIncludes(
+    step.args,
+    '--check-service-binary-executable',
+    '--require-direct 必须检查 Pingora service ExecStart 二进制可执行。',
+  );
+  assertNotIncludes(
+    step.args,
+    '--check-ports-free',
+    '--require-direct 启用后复核不能继续要求 TLS/HTTP redirect 端口空闲；此时端口应由 Pingora 占用。',
+  );
+}
+
+function assertDryRunCutoverForcesPortsFreePreflight() {
+  const plan = readPlan(cutoverPlanArgs());
+  const step = findStep(plan, '切换前 current release 直连 env / 证书 / 端口预检');
+  if (!step) {
+    failures.push('dry-run cutover 计划必须包含切换前 direct entry preflight。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--check-ports-free',
+    'dry-run cutover 启用前 preflight 必须检查 TLS/HTTP redirect 端口已释放。',
+  );
+}
+
+function assertRequireDirectForcesExplicitSpacetimeDatabase() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct live smoke');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct live smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--spacetime-database',
+    '--require-direct 必须把显式 SpacetimeDB 数据库名传给 direct live smoke。',
+  );
+  assertIncludes(
+    step.args,
+    'genarrative-prod',
+    '--require-direct direct live smoke 必须使用显式传入的 SpacetimeDB 数据库名。',
+  );
+}
+
+function assertRequireDirectForcesHealthPatrolEnvCheck() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 health patrol env 直连模式复核');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 health patrol env 复核。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'scripts/check-production-health-patrol-env.mjs',
+    '--require-direct 必须复核 health patrol env。',
+  );
+  assertIncludes(
+    step.args,
+    '/etc/genarrative/health-patrol.env',
+    '--require-direct health patrol env 复核必须使用显式 env 文件。',
+  );
+  assertIncludes(
+    step.args,
+    'pingora-direct',
+    '--require-direct health patrol env 复核必须要求 pingora-direct。',
+  );
+  assertIncludes(
+    step.args,
+    'https://127.0.0.1',
+    '--require-direct health patrol env 复核必须校验 direct HTTPS base URL。',
+  );
+  assertIncludes(
+    step.args,
+    'example.com',
+    '--require-direct health patrol env 复核必须校验正式 Host。',
+  );
+}
+
+function assertDryRunPlanRedactsDirectProbeToken() {
+  const plan = readPlan([
+    ...requireDirectBaseArgs,
+    '--direct-probe-token',
+    'direct-secret-token',
+    '--dry-run-plan',
+  ]);
+  const step = findStep(plan, '目标 Pingora direct live smoke');
+  if (!step) {
+    failures.push('带 direct probe token 的计划必须包含 direct live smoke。');
+    return;
+  }
+  assertIncludes(
+    step.args,
+    '--probe-token',
+    'dry-run plan direct live smoke 必须传递 probe token 参数。',
+  );
+  assertIncludes(
+    step.args,
+    '<redacted>',
+    'dry-run plan direct live smoke 必须隐藏 probe token 值。',
+  );
+  if (step.args.includes('direct-secret-token')) {
+    failures.push('dry-run plan JSON 不能泄露 direct probe token 原文。');
+  }
+}
+
+function assertRunStepLogRedactsDirectProbeToken() {
+  const output = readFileSync(
+    'scripts/check-pingora-release-readiness.mjs',
+    'utf8',
+  );
+  assertIncludes(
+    output,
+    'redactSecretArgs(args).join',
+    '真实执行日志里的命令展示必须使用脱敏参数。',
+  );
+}
+
+function assertRequireLiveRejectsMissingHost() {
+  const result = runReadinessExpectFailure([
+    '--require-live',
+    '--live-base-url',
+    'http://127.0.0.1',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-live 时必须提供 --live-host 或 GENARRATIVE_PINGORA_CANARY_HOST',
+    '--require-live 缺少 live Host 时必须失败。',
+  );
+}
+
+function assertRequireLiveRejectsInvalidHost() {
+  const result = runReadinessExpectFailure([
+    '--require-live',
+    '--live-base-url',
+    'http://127.0.0.1',
+    '--live-host',
+    'https://example.com',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--live-host 只能是 host 或 host:port',
+    '--require-live 的 live Host 不能接受 URL 或路径。',
+  );
+}
+
+function assertRequireLiveRejectsRelativeAccessLog() {
+  const result = runReadinessExpectFailure([
+    '--require-live',
+    '--live-base-url',
+    'http://127.0.0.1',
+    '--live-host',
+    'example.com',
+    '--live-nginx-access-log',
+    'nginx.access.log',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--live-nginx-access-log 必须是绝对路径',
+    '--require-live 的 Nginx access log 不能接受相对路径。',
+  );
+}
+
+function assertRequireLiveRejectsFilesystemRootAccessLog() {
+  const result = runReadinessExpectFailure([
+    '--require-live',
+    '--live-base-url',
+    'http://127.0.0.1',
+    '--live-host',
+    'example.com',
+    '--live-nginx-access-log',
+    '/',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--live-nginx-access-log 不能是文件系统根目录',
+    '--require-live 的 Nginx access log 不能指向文件系统根目录。',
+  );
+}
+
+function assertRequireLiveRejectsInvalidAccessLogSinceLines() {
+  const result = runReadinessExpectFailure([
+    '--require-live',
+    '--live-base-url',
+    'http://127.0.0.1',
+    '--live-host',
+    'example.com',
+    '--live-access-log-since-lines',
+    '0',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--live-access-log-since-lines 必须是正整数',
+    '--require-live 的 access log tail 行数必须是正整数。',
+  );
+}
+
+function assertRequireRealpathLiveRejectsMissingHost() {
+  const result = runReadinessExpectFailure([
+    '--require-realpath-live',
+    '--realpath-live-base-url',
+    'http://127.0.0.1:18083',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-realpath-live 时必须提供 --realpath-live-host 或 GENARRATIVE_PINGORA_REALPATH_CANARY_HOST',
+    '--require-realpath-live 缺少 realpath live Host 时必须失败。',
+  );
+}
+
+function assertRequireRealpathLiveRejectsRelativeAccessLog() {
+  const result = runReadinessExpectFailure([
+    '--require-realpath-live',
+    '--realpath-live-base-url',
+    'http://127.0.0.1:18083',
+    '--realpath-live-host',
+    'example.com',
+    '--realpath-live-nginx-access-log',
+    'nginx.realpath.access.log',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--realpath-live-nginx-access-log 必须是绝对路径',
+    '--require-realpath-live 的 Nginx access log 不能接受相对路径。',
+  );
+}
+
+function assertRequireDirectRejectsMissingHttpBaseUrl() {
+  const result = spawnSync(
+    'node',
+    [
+      'scripts/check-pingora-release-readiness.mjs',
+      '--require-direct',
+      '--direct-https-base-url',
+      'https://127.0.0.1',
+      '--direct-host',
+      'example.com',
+      '--direct-redirect-host',
+      'example.com',
+      '--direct-pingora-access-log',
+      '/var/log/genarrative/pingora-gateway.access.log',
+      '--direct-preflight-env-file',
+      '/tmp/pingora-gateway.env',
+      '--direct-preflight-systemd',
+      '--direct-preflight-check-cert-readable',
+      '--direct-preflight-check-service-env-file',
+      '--direct-preflight-check-service-user-cert-readable',
+      '--direct-preflight-check-service-binary-executable',
+      '--direct-preflight-check-ports-free',
+      '--direct-spacetime-database',
+      'genarrative-prod',
+      '--dry-run-plan',
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: readinessPlanEnv(),
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('--require-direct 缺少 direct HTTP base URL 时必须失败。');
+    return;
+  }
+  const output = `${result.stdout}\n${result.stderr}`;
+  if (
+    !output.includes(
+      '启用 --require-direct 时必须提供 --direct-http-base-url 或 GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL',
+    )
+  ) {
+    failures.push(
+      '--require-direct 缺少 direct HTTP base URL 时必须给出明确错误。',
+    );
+  }
+}
+
+function assertRequireDirectRejectsMissingHost() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-host 或 GENARRATIVE_PINGORA_DIRECT_HOST',
+    '--require-direct 缺少 direct Host/SNI 时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsInvalidHost() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com/path',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--direct-host 只能是 host 或 host:port',
+    '--require-direct 的 direct Host/SNI 不能接受 URL 或路径。',
+  );
+}
+
+function assertRequireDirectRejectsMissingRedirectHost() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-redirect-host 或 GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST',
+    '--require-direct 缺少 direct redirect Location host 时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsInvalidRedirectHost() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'https://example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--direct-redirect-host 只能是 host 或 host:port',
+    '--require-direct 的 redirect Location host 不能接受 URL 或路径。',
+  );
+}
+
+function assertRequireDirectRejectsMissingPingoraAccessLog() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-pingora-access-log 或 GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG',
+    '--require-direct 缺少 direct Pingora access log 时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsFilesystemRootPingoraAccessLog() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--direct-health-patrol-env-file',
+    '/etc/genarrative/health-patrol.env',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--direct-pingora-access-log 不能是文件系统根目录',
+    '--require-direct 的 Pingora access log 不能指向文件系统根目录。',
+  );
+}
+
+function assertRequireDirectRejectsMissingSystemdPreflight() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-preflight-systemd 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT=true',
+    '--require-direct 缺少 systemd preflight 时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsMissingCertReadablePreflight() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-preflight-check-cert-readable 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE=true',
+    '--require-direct 缺少证书可读 preflight 时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsMissingServiceEnvFilePreflight() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-preflight-check-service-env-file 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE=true',
+    '--require-direct 缺少 service EnvironmentFile preflight 时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsMissingServiceUserCertReadablePreflight() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-preflight-check-service-user-cert-readable 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE=true',
+    '--require-direct 缺少服务用户证书可读 preflight 时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsMissingServiceBinaryExecutablePreflight() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-preflight-check-service-binary-executable 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE=true',
+    '--require-direct 缺少 service 二进制可执行 preflight 时必须失败。',
+  );
+}
+
+function assertRequireDirectAllowsPostEnablePortsOwnedByPingora() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct entry preflight');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct entry preflight。');
+    return;
+  }
+  assertNotIncludes(
+    step.args,
+    '--check-ports-free',
+    '--require-direct post-enable 复核不能要求 80/443 空闲。',
+  );
+}
+
+function assertDryRunCutoverRejectsMissingPortsFreePreflight() {
+  const result = runReadinessExpectFailure([
+    ...requireDirectBaseArgs,
+    '--dry-run-cutover',
+    '--rollback-nginx-smoke-url',
+    'https://example.com/',
+    '--rollback-nginx-smoke-expect-body',
+    '<!doctype html>',
+    '--rollback-health-patrol-public-base-url',
+    'http://127.0.0.1',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --dry-run-cutover 时必须提供 --direct-preflight-check-ports-free',
+    'dry-run cutover 缺少端口释放 preflight 时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsMissingSpacetimeDatabase() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-spacetime-database 或 GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE',
+    '--require-direct 缺少 SpacetimeDB 数据库名时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsFilesystemRootPreflightEnvFile() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--direct-health-patrol-env-file',
+    '/etc/genarrative/health-patrol.env',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--direct-preflight-env-file 不能是文件系统根目录',
+    '--require-direct 的 Pingora preflight env 文件不能指向文件系统根目录。',
+  );
+}
+
+function assertRequireDirectRejectsMissingHealthPatrolEnvFile() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时必须提供 --direct-health-patrol-env-file 或 GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE',
+    '--require-direct 缺少 health patrol env 文件时必须失败。',
+  );
+}
+
+function assertRequireDirectRejectsRelativeHealthPatrolEnvFile() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--direct-health-patrol-env-file',
+    'health-patrol.env',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--direct-health-patrol-env-file 必须是绝对路径',
+    '--require-direct 的 health patrol env 文件不能接受相对路径。',
+  );
+}
+
+function assertRequireDirectRejectsFilesystemRootHealthPatrolEnvFile() {
+  const result = runReadinessExpectFailure([
+    '--require-direct',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+    '--direct-health-patrol-env-file',
+    '/',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--direct-health-patrol-env-file 不能是文件系统根目录',
+    '--require-direct 的 health patrol env 文件不能指向文件系统根目录。',
+  );
+}
+
+function assertRequireDirectRejectsSkipWss() {
+  const result = runReadinessExpectFailure([
+    ...requireDirectBaseArgs,
+    '--direct-skip-wss',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时不能使用 --direct-skip-wss 或 GENARRATIVE_PINGORA_DIRECT_SKIP_WSS=true',
+    '--require-direct 不能允许跳过 WSS subscribe。',
+  );
+}
+
+function assertRequireDirectRejectsInsecureTls() {
+  const result = runReadinessExpectFailure([
+    ...requireDirectBaseArgs,
+    '--direct-insecure-tls',
+    '--dry-run-plan',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --require-direct 时不能使用 --direct-insecure-tls 或 GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS=true',
+    '--require-direct 不能允许 insecure TLS。',
+  );
+}
+
+function assertDryRunCutoverRejectsMissingRequireDirect() {
+  const result = runReadinessExpectFailure([
+    '--dry-run-cutover',
+    '--direct-https-base-url',
+    'https://127.0.0.1',
+    '--direct-http-base-url',
+    'http://127.0.0.1',
+    '--direct-host',
+    'example.com',
+    '--direct-redirect-host',
+    'example.com',
+    '--direct-pingora-access-log',
+    '/var/log/genarrative/pingora-gateway.access.log',
+    '--direct-preflight-env-file',
+    '/tmp/pingora-gateway.env',
+    '--direct-preflight-systemd',
+    '--direct-preflight-check-cert-readable',
+    '--direct-preflight-check-service-env-file',
+    '--direct-preflight-check-service-user-cert-readable',
+    '--direct-preflight-check-service-binary-executable',
+    '--direct-preflight-check-ports-free',
+    '--direct-spacetime-database',
+    'genarrative-prod',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --dry-run-cutover 时必须同时提供 --require-direct',
+    'dry-run cutover 缺少 --require-direct 时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsRelativeEvidenceOutputRoot() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(),
+    '--cutover-evidence-output-root',
+    'relative-evidence',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--cutover-evidence-output-root 必须是绝对路径',
+    'dry-run cutover 证据输出根目录使用相对路径时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsFilesystemRootReleaseRoot() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(),
+    '--cutover-release-root',
+    '/',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--cutover-release-root 不能是文件系统根目录',
+    'dry-run cutover current release 根目录使用 / 时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsFilesystemRootEvidenceOutputRoot() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(),
+    '--cutover-evidence-output-root',
+    '/',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--cutover-evidence-output-root 不能是文件系统根目录',
+    'dry-run cutover 证据输出根目录使用 / 时必须失败。',
+  );
+}
+
+function assertUsageCutoverExampleIncludesExplicitEvidenceOutputRoot() {
+  const usage = readUsage();
+  assertIncludes(
+    usage,
+    '--cutover-evidence-output-root /var/log/genarrative/pingora-cutover-evidence',
+    '只生成直连切换 runbook 的 usage 示例必须显式传证据输出根目录。',
+  );
+}
+
+function assertUsageExamplesIncludeDirectPingoraAccessLog() {
+  const usage = readUsage();
+  assertIncludes(
+    usage,
+    'Pingora 直连入口切换窗口追加：',
+    'usage 必须包含正式直连入口示例。',
+  );
+  assertIncludes(
+    usage,
+    '只生成直连切换 runbook：',
+    'usage 必须包含只生成直连切换 runbook 示例。',
+  );
+  const directExample = usage.slice(
+    usage.indexOf('Pingora 直连入口切换窗口追加：'),
+    usage.indexOf('只生成直连切换 runbook：'),
+  );
+  const cutoverExample = usage.slice(
+    usage.indexOf('只生成直连切换 runbook：'),
+  );
+  assertIncludes(
+    directExample,
+    '--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log',
+    '正式直连入口 usage 示例必须显式传 Pingora access log 路径。',
+  );
+  assertIncludes(
+    cutoverExample,
+    '--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log',
+    '只生成直连切换 runbook 的 usage 示例必须显式传 Pingora access log 路径。',
+  );
+}
+
+function assertDryRunCutoverRejectsMissingRollbackHealthPatrolPublicBaseUrl() {
+  const result = runReadinessExpectFailure([
+    ...requireDirectBaseArgs,
+    '--dry-run-cutover',
+    '--direct-preflight-check-ports-free',
+    '--rollback-nginx-smoke-url',
+    'https://example.com/',
+    '--rollback-nginx-smoke-expect-body',
+    '<!doctype html>',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --dry-run-cutover 时必须提供 --rollback-health-patrol-public-base-url',
+    'dry-run cutover 缺少回退后 health patrol public base URL 时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsMissingRollbackSmokeBody() {
+  const result = runReadinessExpectFailure([
+    ...requireDirectBaseArgs,
+    '--dry-run-cutover',
+    '--direct-preflight-check-ports-free',
+    '--rollback-nginx-smoke-url',
+    'https://example.com/',
+    '--rollback-health-patrol-public-base-url',
+    'http://127.0.0.1',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --dry-run-cutover 时必须提供 --rollback-nginx-smoke-expect-body',
+    'dry-run cutover 缺少回退 Nginx smoke body 证据片段时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicBaseUrl() {
+  const result = runReadinessExpectFailure([
+    ...requireDirectBaseArgs,
+    '--dry-run-cutover',
+    '--direct-preflight-check-ports-free',
+    '--rollback-nginx-smoke-url',
+    'https://example.com/',
+    '--rollback-nginx-smoke-expect-body',
+    '<!doctype html>',
+    '--rollback-health-patrol-public-base-url',
+    'ftp://127.0.0.1',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--rollback-health-patrol-public-base-url 必须是 http(s) URL',
+    'dry-run cutover 回退 health patrol public base URL 非 http(s) 时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicHost() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(),
+    '--rollback-health-patrol-public-host',
+    'https://example.com',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--rollback-health-patrol-public-host 只能是 host 或 host:port',
+    'dry-run cutover 回退 health patrol public Host 非 host 格式时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsRedirectHostMismatch() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(
+    '--direct-redirect-host',
+    'redirect.example.com',
+    ),
+  ]);
+  assertFailureIncludes(
+    result,
+    '--direct-redirect-host 必须与 --direct-host 使用同一正式 hostname',
+    'dry-run cutover redirect Host 与 direct Host 不一致时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsRollbackHostMismatch() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(),
+    '--rollback-nginx-smoke-host',
+    'nginx.example.com',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--rollback-nginx-smoke-host 必须与 --direct-host 使用同一正式 hostname',
+    'dry-run cutover rollback smoke Host 与 direct Host 不一致时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsIncompleteRollbackShadowProbe() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(),
+    '--rollback-pingora-shadow-probe-url',
+    'http://127.0.0.1:18081/__genarrative_pingora/healthz',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--rollback-pingora-shadow-probe-url 必须同时提供 --rollback-pingora-shadow-probe-token',
+    'dry-run cutover rollback shadow probe URL 缺少 token 时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsInvalidRollbackShadowProbeUrl() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(),
+    '--rollback-pingora-shadow-probe-url',
+    'ftp://127.0.0.1/probe',
+    '--rollback-pingora-shadow-probe-token',
+    'probe-secret-token',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--rollback-pingora-shadow-probe-url 必须是 http(s) URL',
+    'dry-run cutover rollback shadow probe URL 非 http(s) 时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsInvalidEvidenceTimelineMaxSpan() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(),
+    '--cutover-evidence-timeline-max-span-ms',
+    '0',
+  ]);
+  assertFailureIncludes(
+    result,
+    '--cutover-evidence-timeline-max-span-ms 必须是正整数',
+    'dry-run cutover 标准切换时间线最大跨度非正整数时必须失败。',
+  );
+}
+
+function assertDryRunCutoverRejectsInvalidCutoverRunId() {
+  const result = runReadinessExpectFailure([
+    ...cutoverPlanArgs(
+    '--cutover-run-id',
+    'cutover 1',
+    ),
+  ]);
+  assertFailureIncludes(
+    result,
+    '--cutover-run-id 只能包含 ASCII 字母、数字、点、下划线或短横线',
+    'dry-run cutover 必须拒绝不安全 cutoverRunId。',
+  );
+}
+
+function runReadinessExpectFailure(args) {
+  const result = spawnSync(
+    'node',
+    ['scripts/check-pingora-release-readiness.mjs', ...args],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: readinessPlanEnv(),
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('release readiness 缺少硬门禁参数时必须失败。');
+  }
+  return result;
+}
+
+function assertLiveSmokeScriptsRejectInvalidTimeout() {
+  const cases = [
+    {
+      script: 'scripts/check-pingora-canary-live.mjs',
+      args: ['--base-url', 'http://127.0.0.1', '--timeout-ms', '0'],
+      expected: '--timeout-ms 必须是正整数',
+      reason: 'canary live smoke 必须拒绝非正数 --timeout-ms。',
+    },
+    {
+      script: 'scripts/check-pingora-canary-live.mjs',
+      args: ['--base-url', 'http://127.0.0.1'],
+      env: {
+        GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS: 'abc',
+      },
+      expected: 'GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS 必须是正整数',
+      reason: 'canary live smoke 必须拒绝非法 env timeout。',
+    },
+    {
+      script: 'scripts/check-pingora-direct-live.mjs',
+      args: ['--https-base-url', 'https://127.0.0.1', '--timeout-ms', '0'],
+      expected: '--timeout-ms 必须是正整数',
+      reason: 'direct live smoke 必须拒绝非正数 --timeout-ms。',
+    },
+    {
+      script: 'scripts/check-pingora-direct-live.mjs',
+      args: ['--https-base-url', 'https://127.0.0.1'],
+      env: {
+        GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS: 'abc',
+      },
+      expected: 'GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS 必须是正整数',
+      reason: 'direct live smoke 必须拒绝非法 env timeout。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = spawnSync('node', [testCase.script, ...testCase.args], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...readinessPlanEnv(),
+        ...(testCase.env || {}),
+      },
+    });
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertFailureIncludes(
+      result,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function assertDirectLiveRejectsInvalidBoolEnv() {
+  const cases = [
+    {
+      env: {
+        GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE: 'ture',
+      },
+      expected: 'GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE 必须是布尔值',
+      reason: 'direct live smoke 必须拒绝拼写错误的 require WSS env。',
+    },
+    {
+      env: {
+        GENARRATIVE_PINGORA_DIRECT_SKIP_WSS: 'maybe',
+      },
+      expected: 'GENARRATIVE_PINGORA_DIRECT_SKIP_WSS 必须是布尔值',
+      reason: 'direct live smoke 必须拒绝非法 skip WSS env。',
+    },
+    {
+      env: {
+        GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS: 'enabled',
+      },
+      expected: 'GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS 必须是布尔值',
+      reason: 'direct live smoke 必须拒绝非法 insecure TLS env。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = spawnSync(
+      'node',
+      ['scripts/check-pingora-direct-live.mjs', '--https-base-url', 'https://127.0.0.1'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: {
+          ...readinessPlanEnv(),
+          ...testCase.env,
+        },
+      },
+    );
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertFailureIncludes(
+      result,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function assertDirectLiveRejectsFilesystemRootAccessLog() {
+  const result = spawnSync(
+    'node',
+    [
+      'scripts/check-pingora-direct-live.mjs',
+      '--https-base-url',
+      'https://127.0.0.1',
+      '--pingora-access-log',
+      '/',
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: readinessPlanEnv(),
+    },
+  );
+  if ((result.status ?? 0) === 0) {
+    failures.push('direct live smoke 必须拒绝 Pingora access log 指向文件系统根目录。');
+  }
+  assertFailureIncludes(
+    result,
+    '--pingora-access-log 不能是文件系统根目录',
+    'direct live smoke 的 Pingora access log 不能指向文件系统根目录。',
+  );
+}
+
+function assertReleaseReadinessRejectsInvalidDirectBoolEnv() {
+  const cases = [
+    {
+      env: {
+        GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT: 'ture',
+      },
+      expected:
+        'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT 必须是布尔值',
+      reason: 'release readiness 必须拒绝拼写错误的 preflight systemd env。',
+    },
+    {
+      env: {
+        GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE: 'definitely',
+      },
+      expected: 'GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE 必须是布尔值',
+      reason: 'release readiness 必须拒绝非法 require WSS env。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = spawnSync(
+      'node',
+      ['scripts/check-pingora-release-readiness.mjs', '--dry-run-plan'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: {
+          ...readinessPlanEnv(),
+          ...testCase.env,
+        },
+      },
+    );
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertFailureIncludes(
+      result,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function assertDirectPreflightRejectsInvalidBoolEnv() {
+  const cases = [
+    {
+      env: {
+        GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_REQUIRE_LIVE_ENV: 'ture',
+      },
+      expected:
+        'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_REQUIRE_LIVE_ENV 必须是布尔值',
+      reason: 'direct preflight 必须拒绝拼写错误的 require live env。',
+    },
+    {
+      env: {
+        GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE: 'maybe',
+      },
+      expected:
+        'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE 必须是布尔值',
+      reason: 'direct preflight 必须拒绝非法 check ports free env。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = spawnSync(
+      'node',
+      ['scripts/check-pingora-direct-preflight.mjs'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: {
+          ...readinessPlanEnv(),
+          ...testCase.env,
+        },
+      },
+    );
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertFailureIncludes(
+      result,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function assertDirectPreflightRejectsUnconfirmedMultiInstanceProtection() {
+  const root = mkdtempSync(path.join(tmpdir(), 'genarrative-direct-preflight-'));
+  try {
+    const envFile = path.join(root, 'pingora-gateway.env');
+    writeFileSync(
+      envFile,
+      [
+        'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=0.0.0.0:18443',
+        'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=0.0.0.0:18080',
+        'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/tmp/cert.pem',
+        'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/tmp/key.pem',
+        'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+        'GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true',
+        'GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT=2',
+        'GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=false',
+        '',
+      ].join('\n'),
+    );
+
+    const result = spawnSync(
+      'node',
+      [
+        'scripts/check-pingora-direct-preflight.mjs',
+        '--env-file',
+        envFile,
+        '--require-live-env',
+      ],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: readinessPlanEnv(),
+      },
+    );
+    if ((result.status ?? 0) === 0) {
+      failures.push(
+        'direct preflight 必须拒绝未确认共享保护的多实例 Pingora 配置。',
+      );
+    }
+    assertFailureIncludes(
+      result,
+      'GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1',
+      'direct preflight 多实例保护失败必须给出明确错误。',
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function assertCutoverEvidenceScriptsRejectInvalidBoolEnv() {
+  const cases = [
+    {
+      script: 'scripts/ops/pingora-current-release-audit.mjs',
+      env: {
+        GENARRATIVE_PINGORA_CURRENT_RELEASE_REQUIRE_GATEWAY: 'ture',
+      },
+      expected:
+        'GENARRATIVE_PINGORA_CURRENT_RELEASE_REQUIRE_GATEWAY 必须是布尔值',
+      reason:
+        'current release 自审 smoke 必须覆盖非法 require gateway 布尔 env。',
+    },
+    {
+      script: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+      env: {
+        GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL: 'maybe',
+      },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL 必须是布尔值',
+      reason:
+        'cutover 状态快照 smoke 必须覆盖非法 run health patrol 布尔 env。',
+    },
+    {
+      script: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+      env: {
+        GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL: 'enabled',
+      },
+      expected:
+        'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL 必须是布尔值',
+      reason:
+        'cutover 证据包 smoke 必须覆盖非法 fail on critical 布尔 env。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = spawnSync('node', [testCase.script], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...readinessPlanEnv(),
+        ...testCase.env,
+      },
+    });
+    if ((result.status ?? 0) === 0) {
+      failures.push(
+        `${testCase.reason} 脚本本体必须失败。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      );
+    }
+    assertFailureIncludes(
+      result,
+      testCase.expected,
+      `${testCase.reason} 必须能在输出中看到明确错误。`,
+    );
+  }
+}
+
+function assertFailureIncludes(result, expected, reason) {
+  const output = `${result.stdout}\n${result.stderr}`;
+  if (!output.includes(expected)) {
+    failures.push(reason);
+  }
+}
+
+function readPlan(args) {
+  const result = spawnSync(
+    'node',
+    ['scripts/check-pingora-release-readiness.mjs', ...args],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: readinessPlanEnv(),
+    },
+  );
+  if ((result.status ?? 0) !== 0) {
+    failures.push(
+      `读取 release readiness dry-run plan 失败，退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+    return [];
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch (error) {
+    failures.push(
+      `release readiness dry-run plan 不是合法 JSON: ${error.message}`,
+    );
+    return [];
+  }
+}
+
+function readUsage() {
+  const result = spawnSync(
+    'node',
+    ['scripts/check-pingora-release-readiness.mjs', '--help'],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: readinessPlanEnv(),
+    },
+  );
+  if ((result.status ?? 0) !== 0) {
+    failures.push(
+      `读取 release readiness usage 失败，退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+    return '';
+  }
+  return result.stdout;
+}
+
+function readinessPlanEnv() {
+  return {
+    ...process.env,
+    GENARRATIVE_PINGORA_CANARY_HOST: '',
+    GENARRATIVE_PINGORA_CANARY_BASE_URL: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_HOST: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_BASE_URL: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_NGINX_ACCESS_LOG: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_PINGORA_ACCESS_LOG: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_ACCESS_LOG_SINCE_LINES: '',
+    GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL: '',
+    GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL: '',
+    GENARRATIVE_PINGORA_DIRECT_HOST: '',
+    GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST: '',
+    GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE: '',
+    GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT: '',
+    GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE: '',
+    GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE: '',
+    GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE: '',
+    GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE: '',
+    GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE: '',
+    GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE: '',
+    GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE: '',
+    GENARRATIVE_HEALTH_PATROL_ENV_FILE: '',
+    GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE: '',
+    GENARRATIVE_PINGORA_DIRECT_SKIP_WSS: '',
+    GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS: '',
+    GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_URL: '',
+    GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_HOST: '',
+    GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY: '',
+    GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_PUBLIC_BASE_URL: '',
+    GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_PUBLIC_HOST: '',
+    GENARRATIVE_PINGORA_ROLLBACK_SHADOW_PROBE_URL: '',
+    GENARRATIVE_PINGORA_ROLLBACK_SHADOW_PROBE_TOKEN: '',
+    GENARRATIVE_PINGORA_CUTOVER_RUN_ID: '',
+  };
+}
+
+function findStep(plan, name) {
+  return plan.find((step) => step.name === name);
+}
+
+function assertIncludes(values, expected, reason) {
+  if (!values.includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
+
+function assertAbsoluteScriptArg(values, expectedSuffix, reason) {
+  const normalizedSuffix = expectedSuffix.replace(/\\/g, '/');
+  const matched = values.some((value) => {
+    const text = String(value).replace(/\\/g, '/');
+    return text.startsWith('/') && text.endsWith(normalizedSuffix);
+  });
+  if (!matched) {
+    failures.push(`${reason} 缺少绝对脚本路径后缀: ${expectedSuffix}`);
+  }
+}
+
+function assertNotIncludes(values, forbidden, reason) {
+  if (values.includes(forbidden)) {
+    failures.push(reason);
+  }
+}
+
+function assertStepBefore(plan, firstName, secondName, reason) {
+  const firstIndex = plan.findIndex((step) => step.name === firstName);
+  const secondIndex = plan.findIndex((step) => step.name === secondName);
+  if (firstIndex < 0 || secondIndex < 0) {
+    return;
+  }
+  if (firstIndex >= secondIndex) {
+    failures.push(reason);
+  }
+}
diff --git a/scripts/check-pingora-release-readiness.mjs b/scripts/check-pingora-release-readiness.mjs
new file mode 100644
index 000000000..dd6dd1ff1
--- /dev/null
+++ b/scripts/check-pingora-release-readiness.mjs
@@ -0,0 +1,2222 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = process.cwd();
+const scriptDir = path.dirname(resolveInvokedScriptPath());
+const releaseRoot = path.resolve(scriptDir, '..');
+const DEFAULT_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_CUTOVER_RUN_ID_PREFIX = 'pingora-direct-';
+const SECRET_VALUE_FLAGS = new Set([
+  '--direct-probe-token',
+  '--probe-token',
+  '--pingora-shadow-probe-token',
+  '--rollback-pingora-shadow-probe-token',
+]);
+
+const config = parseArgs(process.argv.slice(2));
+const failures = [];
+
+if (config.dryRunPlan) {
+  printDryRunPlan(buildSteps(config));
+  process.exit(0);
+}
+if (config.dryRunCutover) {
+  printDryRunPlan(buildCutoverPlan(config));
+  process.exit(0);
+}
+
+for (const step of buildSteps(config)) {
+  const ok = await runStep(step);
+  if (!ok && !config.keepGoing) {
+    break;
+  }
+}
+
+if (failures.length > 0) {
+  console.error('\n[pingora-release-readiness] 未通过：');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('\n[pingora-release-readiness] 通过');
+
+function resolveInvokedScriptPath() {
+  const invoked = process.argv[1];
+  if (invoked) {
+    return path.resolve(invoked);
+  }
+  return fileURLToPath(import.meta.url);
+}
+
+function parseArgs(argv) {
+  const result = {
+    requireDocker: false,
+    pullDocker: false,
+    requireNginx: false,
+    requireLive: false,
+    requireRealpathLive: false,
+    requireDirect: false,
+    liveBaseUrl: process.env.GENARRATIVE_PINGORA_CANARY_BASE_URL || '',
+    liveHost: process.env.GENARRATIVE_PINGORA_CANARY_HOST || '',
+    liveAccessLogNginx:
+      process.env.GENARRATIVE_PINGORA_CANARY_NGINX_ACCESS_LOG ||
+      '/var/log/nginx/genarrative.access.log',
+    liveAccessLogPingora:
+      process.env.GENARRATIVE_PINGORA_CANARY_PINGORA_ACCESS_LOG ||
+      '/var/log/genarrative/pingora-gateway.access.log',
+    liveAccessLogSinceLines:
+      process.env.GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES || '2000',
+    realpathLiveBaseUrl:
+      process.env.GENARRATIVE_PINGORA_REALPATH_CANARY_BASE_URL || '',
+    realpathLiveHost:
+      process.env.GENARRATIVE_PINGORA_REALPATH_CANARY_HOST || '',
+    realpathLiveAccessLogNginx:
+      process.env.GENARRATIVE_PINGORA_REALPATH_CANARY_NGINX_ACCESS_LOG ||
+      '/var/log/nginx/genarrative-pingora-realpath-canary.access.log',
+    realpathLiveAccessLogPingora:
+      process.env.GENARRATIVE_PINGORA_REALPATH_CANARY_PINGORA_ACCESS_LOG ||
+      process.env.GENARRATIVE_PINGORA_CANARY_PINGORA_ACCESS_LOG ||
+      '/var/log/genarrative/pingora-gateway.access.log',
+    realpathLiveAccessLogSinceLines:
+      process.env.GENARRATIVE_PINGORA_REALPATH_CANARY_ACCESS_LOG_SINCE_LINES ||
+      process.env.GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES ||
+      '2000',
+    directHttpsBaseUrl:
+      process.env.GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL || '',
+    directHttpBaseUrl:
+      process.env.GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL || '',
+    directHost: process.env.GENARRATIVE_PINGORA_DIRECT_HOST || '',
+    directRedirectHost:
+      process.env.GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST || '',
+    directRedirectBaseUrl:
+      process.env.GENARRATIVE_PINGORA_DIRECT_REDIRECT_BASE_URL || '',
+    directProbeToken: process.env.GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN || '',
+    directPingoraAccessLog:
+      process.env.GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG || '',
+    directAccessLogSinceLines:
+      process.env.GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES || '2000',
+    directPreflightEnvFile:
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE || '',
+    directPreflightSystemd: readBoolEnv(
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT',
+    ),
+    directPreflightCheckCertReadable: readBoolEnv(
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE',
+    ),
+    directPreflightCheckServiceEnvFile: readBoolEnv(
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE',
+    ),
+    directPreflightCheckServiceUserCertReadable: readBoolEnv(
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE',
+    ),
+    directPreflightCheckServiceBinaryExecutable: readBoolEnv(
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE',
+    ),
+    directPreflightCheckPortsFree: readBoolEnv(
+      'GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE',
+    ),
+    directSpacetimeDatabase:
+      process.env.GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE || '',
+    directHealthPatrolEnvFile:
+      process.env.GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE ||
+      process.env.GENARRATIVE_HEALTH_PATROL_ENV_FILE ||
+      '',
+    directRequireWssUpgrade: readBoolEnv(
+      'GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE',
+    ),
+    directSkipWss: readBoolEnv('GENARRATIVE_PINGORA_DIRECT_SKIP_WSS'),
+    directInsecureTls: readBoolEnv(
+      'GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS',
+    ),
+    cutoverReleaseRoot:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_RELEASE_ROOT ||
+      '/opt/genarrative/current',
+    cutoverEvidenceOutputRoot:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_ROOT ||
+      '/var/log/genarrative/pingora-cutover-evidence',
+    cutoverEvidenceTimelineMaxSpanMs: parsePositiveIntEnv(
+      'GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS',
+      DEFAULT_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS,
+    ),
+    cutoverRunId: process.env.GENARRATIVE_PINGORA_CUTOVER_RUN_ID || '',
+    rollbackNginxSmokeUrl:
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_URL || '',
+    rollbackNginxSmokeHost:
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_HOST || '',
+    rollbackNginxSmokeExpectBody:
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY || '',
+    rollbackHealthPatrolPublicBaseUrl:
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_PUBLIC_BASE_URL ||
+      '',
+    rollbackHealthPatrolPublicHost:
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_PUBLIC_HOST || '',
+    rollbackPingoraShadowProbeUrl:
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_SHADOW_PROBE_URL || '',
+    rollbackPingoraShadowProbeToken:
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_SHADOW_PROBE_TOKEN || '',
+    dryRunPlan: false,
+    dryRunCutover: false,
+    releaseRuntimeOnly: readBoolEnv(
+      'GENARRATIVE_PINGORA_RELEASE_RUNTIME_ONLY',
+    ),
+    keepGoing: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--require-docker':
+        result.requireDocker = true;
+        break;
+      case '--pull-docker':
+        result.pullDocker = true;
+        break;
+      case '--require-nginx':
+        result.requireNginx = true;
+        break;
+      case '--require-live':
+        result.requireLive = true;
+        break;
+      case '--require-realpath-live':
+        result.requireRealpathLive = true;
+        break;
+      case '--require-direct':
+        result.requireDirect = true;
+        break;
+      case '--live-base-url':
+        result.liveBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--live-host':
+        result.liveHost = requireValue(argv, ++index, arg);
+        break;
+      case '--live-nginx-access-log':
+        result.liveAccessLogNginx = requireValue(argv, ++index, arg);
+        break;
+      case '--live-pingora-access-log':
+        result.liveAccessLogPingora = requireValue(argv, ++index, arg);
+        break;
+      case '--live-access-log-since-lines':
+        result.liveAccessLogSinceLines = requireValue(argv, ++index, arg);
+        break;
+      case '--realpath-live-base-url':
+        result.realpathLiveBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--realpath-live-host':
+        result.realpathLiveHost = requireValue(argv, ++index, arg);
+        break;
+      case '--realpath-live-nginx-access-log':
+        result.realpathLiveAccessLogNginx = requireValue(argv, ++index, arg);
+        break;
+      case '--realpath-live-pingora-access-log':
+        result.realpathLiveAccessLogPingora = requireValue(argv, ++index, arg);
+        break;
+      case '--realpath-live-access-log-since-lines':
+        result.realpathLiveAccessLogSinceLines = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-https-base-url':
+        result.directHttpsBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-http-base-url':
+        result.directHttpBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-host':
+        result.directHost = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-redirect-host':
+        result.directRedirectHost = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-redirect-base-url':
+        result.directRedirectBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-probe-token':
+        result.directProbeToken = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-pingora-access-log':
+        result.directPingoraAccessLog = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-access-log-since-lines':
+        result.directAccessLogSinceLines = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-preflight-env-file':
+        result.directPreflightEnvFile = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-preflight-systemd':
+        result.directPreflightSystemd = true;
+        break;
+      case '--direct-preflight-check-cert-readable':
+        result.directPreflightCheckCertReadable = true;
+        break;
+      case '--direct-preflight-check-service-env-file':
+        result.directPreflightCheckServiceEnvFile = true;
+        break;
+      case '--direct-preflight-check-service-user-cert-readable':
+        result.directPreflightCheckServiceUserCertReadable = true;
+        break;
+      case '--direct-preflight-check-service-binary-executable':
+        result.directPreflightCheckServiceBinaryExecutable = true;
+        break;
+      case '--direct-preflight-check-ports-free':
+        result.directPreflightCheckPortsFree = true;
+        break;
+      case '--direct-spacetime-database':
+        result.directSpacetimeDatabase = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-health-patrol-env-file':
+        result.directHealthPatrolEnvFile = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-require-wss-upgrade':
+        result.directRequireWssUpgrade = true;
+        break;
+      case '--direct-skip-wss':
+        result.directSkipWss = true;
+        break;
+      case '--direct-insecure-tls':
+        result.directInsecureTls = true;
+        break;
+      case '--cutover-release-root':
+        result.cutoverReleaseRoot = requireValue(argv, ++index, arg);
+        break;
+      case '--cutover-evidence-output-root':
+        result.cutoverEvidenceOutputRoot = requireValue(argv, ++index, arg);
+        break;
+      case '--cutover-evidence-timeline-max-span-ms':
+        result.cutoverEvidenceTimelineMaxSpanMs = parsePositiveInt(
+          requireValue(argv, ++index, arg),
+          '--cutover-evidence-timeline-max-span-ms',
+        );
+        break;
+      case '--cutover-run-id':
+        result.cutoverRunId = requireValue(argv, ++index, arg);
+        break;
+      case '--rollback-nginx-smoke-url':
+        result.rollbackNginxSmokeUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--rollback-nginx-smoke-host':
+        result.rollbackNginxSmokeHost = requireValue(argv, ++index, arg);
+        break;
+      case '--rollback-nginx-smoke-expect-body':
+        result.rollbackNginxSmokeExpectBody = requireValue(argv, ++index, arg);
+        break;
+      case '--rollback-health-patrol-public-base-url':
+        result.rollbackHealthPatrolPublicBaseUrl = requireValue(
+          argv,
+          ++index,
+          arg,
+        );
+        break;
+      case '--rollback-health-patrol-public-host':
+        result.rollbackHealthPatrolPublicHost = requireValue(
+          argv,
+          ++index,
+          arg,
+        );
+        break;
+      case '--rollback-pingora-shadow-probe-url':
+        result.rollbackPingoraShadowProbeUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--rollback-pingora-shadow-probe-token':
+        result.rollbackPingoraShadowProbeToken = requireValue(
+          argv,
+          ++index,
+          arg,
+        );
+        break;
+      case '--dry-run-plan':
+        result.dryRunPlan = true;
+        break;
+      case '--dry-run-cutover':
+        result.dryRunCutover = true;
+        break;
+      case '--release-runtime-only':
+        result.releaseRuntimeOnly = true;
+        break;
+      case '--keep-going':
+        result.keepGoing = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (result.requireLive && !result.liveBaseUrl) {
+    throw new Error(
+      '启用 --require-live 时必须提供 --live-base-url 或 GENARRATIVE_PINGORA_CANARY_BASE_URL',
+    );
+  }
+  if (result.requireLive && !result.liveHost) {
+    throw new Error(
+      '启用 --require-live 时必须提供 --live-host 或 GENARRATIVE_PINGORA_CANARY_HOST',
+    );
+  }
+  if (result.liveHost) {
+    validateHostOption(result.liveHost, '--live-host');
+  }
+  if (result.requireLive) {
+    for (const [label, filePath] of [
+      ['--live-nginx-access-log', result.liveAccessLogNginx],
+      ['--live-pingora-access-log', result.liveAccessLogPingora],
+    ]) {
+      validateSafeAbsoluteFilePath(filePath, label);
+    }
+    if (!isPositiveIntegerString(result.liveAccessLogSinceLines)) {
+      throw new Error('--live-access-log-since-lines 必须是正整数。');
+    }
+  }
+  if (result.requireRealpathLive && !result.realpathLiveBaseUrl) {
+    throw new Error(
+      '启用 --require-realpath-live 时必须提供 --realpath-live-base-url 或 GENARRATIVE_PINGORA_REALPATH_CANARY_BASE_URL',
+    );
+  }
+  if (result.requireRealpathLive && !result.realpathLiveHost) {
+    throw new Error(
+      '启用 --require-realpath-live 时必须提供 --realpath-live-host 或 GENARRATIVE_PINGORA_REALPATH_CANARY_HOST',
+    );
+  }
+  if (result.realpathLiveHost) {
+    validateHostOption(result.realpathLiveHost, '--realpath-live-host');
+  }
+  if (result.requireRealpathLive || result.realpathLiveBaseUrl) {
+    for (const [label, filePath] of [
+      ['--realpath-live-nginx-access-log', result.realpathLiveAccessLogNginx],
+      ['--realpath-live-pingora-access-log', result.realpathLiveAccessLogPingora],
+    ]) {
+      validateSafeAbsoluteFilePath(filePath, label);
+    }
+    if (!isPositiveIntegerString(result.realpathLiveAccessLogSinceLines)) {
+      throw new Error('--realpath-live-access-log-since-lines 必须是正整数。');
+    }
+  }
+  if (result.requireDirect && !result.directHttpsBaseUrl) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-https-base-url 或 GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL',
+    );
+  }
+  if (result.requireDirect && !result.directHttpBaseUrl) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-http-base-url 或 GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL',
+    );
+  }
+  if (result.requireDirect && !result.directHost) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-host 或 GENARRATIVE_PINGORA_DIRECT_HOST',
+    );
+  }
+  if (result.directHost) {
+    validateHostOption(result.directHost, '--direct-host');
+  }
+  if (result.requireDirect && !result.directRedirectHost) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-redirect-host 或 GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST',
+    );
+  }
+  if (result.directRedirectHost) {
+    validateHostOption(result.directRedirectHost, '--direct-redirect-host');
+  }
+  if (result.directRedirectBaseUrl) {
+    validateHttpUrl(result.directRedirectBaseUrl, '--direct-redirect-base-url');
+    const parsed = new URL(result.directRedirectBaseUrl);
+    if (parsed.protocol !== 'https:') {
+      throw new Error('--direct-redirect-base-url 必须使用 https://。');
+    }
+    if (
+      parsed.pathname !== '/' ||
+      parsed.search ||
+      parsed.hash ||
+      parsed.username ||
+      parsed.password
+    ) {
+      throw new Error(
+        '--direct-redirect-base-url 只能是 HTTPS base URL，不能包含路径、查询、片段或认证信息。',
+      );
+    }
+  }
+  if (result.requireDirect && !result.directPingoraAccessLog) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-pingora-access-log 或 GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG',
+    );
+  }
+  if (result.directPingoraAccessLog) {
+    validateSafeAbsoluteFilePath(
+      result.directPingoraAccessLog,
+      '--direct-pingora-access-log',
+    );
+  }
+  if (
+    result.directPingoraAccessLog &&
+    !isPositiveIntegerString(result.directAccessLogSinceLines)
+  ) {
+    throw new Error('--direct-access-log-since-lines 必须是正整数。');
+  }
+  if (result.requireDirect && !result.directPreflightEnvFile) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-preflight-env-file 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE',
+    );
+  }
+  if (result.directPreflightEnvFile) {
+    validateSafeAbsoluteFilePath(
+      result.directPreflightEnvFile,
+      '--direct-preflight-env-file',
+    );
+  }
+  if (result.requireDirect && !result.directPreflightSystemd) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-preflight-systemd 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT=true',
+    );
+  }
+  if (result.requireDirect && !result.directPreflightCheckCertReadable) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-preflight-check-cert-readable 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE=true',
+    );
+  }
+  if (result.requireDirect && !result.directPreflightCheckServiceEnvFile) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-preflight-check-service-env-file 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE=true',
+    );
+  }
+  if (
+    result.requireDirect &&
+    !result.directPreflightCheckServiceUserCertReadable
+  ) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-preflight-check-service-user-cert-readable 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE=true',
+    );
+  }
+  if (
+    result.requireDirect &&
+    !result.directPreflightCheckServiceBinaryExecutable
+  ) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-preflight-check-service-binary-executable 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE=true',
+    );
+  }
+  if (result.dryRunCutover && !result.directPreflightCheckPortsFree) {
+    throw new Error(
+      '启用 --dry-run-cutover 时必须提供 --direct-preflight-check-ports-free 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE=true，用于切换前证明 Nginx 和其它进程已释放 80/443。',
+    );
+  }
+  if (result.requireDirect && result.directSkipWss) {
+    throw new Error(
+      '启用 --require-direct 时不能使用 --direct-skip-wss 或 GENARRATIVE_PINGORA_DIRECT_SKIP_WSS=true',
+    );
+  }
+  if (result.requireDirect && !result.directSpacetimeDatabase) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-spacetime-database 或 GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE',
+    );
+  }
+  if (result.requireDirect && !result.directHealthPatrolEnvFile) {
+    throw new Error(
+      '启用 --require-direct 时必须提供 --direct-health-patrol-env-file 或 GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE',
+    );
+  }
+  if (result.directHealthPatrolEnvFile) {
+    validateSafeAbsoluteFilePath(
+      result.directHealthPatrolEnvFile,
+      '--direct-health-patrol-env-file',
+    );
+  }
+  if (result.requireDirect && result.directInsecureTls) {
+    throw new Error(
+      '启用 --require-direct 时不能使用 --direct-insecure-tls 或 GENARRATIVE_PINGORA_DIRECT_INSECURE_TLS=true',
+    );
+  }
+  if (result.requireDirect && !result.directSkipWss) {
+    result.directRequireWssUpgrade = true;
+  }
+  if (result.dryRunCutover && !result.requireDirect) {
+    throw new Error(
+      '启用 --dry-run-cutover 时必须同时提供 --require-direct，避免生成缺少直连硬门禁的切换计划。',
+    );
+  }
+  if (result.dryRunCutover && !path.isAbsolute(result.cutoverReleaseRoot)) {
+    throw new Error('--cutover-release-root 必须是绝对路径。');
+  }
+  if (
+    result.dryRunCutover &&
+    isFilesystemRootPath(result.cutoverReleaseRoot)
+  ) {
+    throw new Error('--cutover-release-root 不能是文件系统根目录。');
+  }
+  if (
+    result.dryRunCutover &&
+    !path.isAbsolute(result.cutoverEvidenceOutputRoot)
+  ) {
+    throw new Error('--cutover-evidence-output-root 必须是绝对路径。');
+  }
+  if (
+    result.dryRunCutover &&
+    isFilesystemRootPath(result.cutoverEvidenceOutputRoot)
+  ) {
+    throw new Error('--cutover-evidence-output-root 不能是文件系统根目录。');
+  }
+  if (result.dryRunCutover && !result.rollbackNginxSmokeUrl) {
+    throw new Error(
+      '启用 --dry-run-cutover 时必须提供 --rollback-nginx-smoke-url 或 GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_URL。',
+    );
+  }
+  if (result.dryRunCutover && !result.rollbackNginxSmokeExpectBody) {
+    throw new Error(
+      '启用 --dry-run-cutover 时必须提供 --rollback-nginx-smoke-expect-body 或 GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY，且该片段必须来自切换前真实 Nginx 入口。',
+    );
+  }
+  if (result.dryRunCutover && !result.rollbackNginxSmokeHost) {
+    result.rollbackNginxSmokeHost = result.directHost || result.liveHost;
+  }
+  if (result.rollbackNginxSmokeHost) {
+    validateHostOption(
+      result.rollbackNginxSmokeHost,
+      '--rollback-nginx-smoke-host',
+    );
+  }
+  if (
+    result.dryRunCutover &&
+    !result.rollbackHealthPatrolPublicBaseUrl
+  ) {
+    throw new Error(
+      '启用 --dry-run-cutover 时必须提供 --rollback-health-patrol-public-base-url 或 GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_PUBLIC_BASE_URL，避免回退 runbook 覆盖现场原有 Nginx 巡检入口。',
+    );
+  }
+  if (result.rollbackHealthPatrolPublicBaseUrl) {
+    validateHttpUrl(
+      result.rollbackHealthPatrolPublicBaseUrl,
+      '--rollback-health-patrol-public-base-url',
+    );
+  }
+  if (result.rollbackHealthPatrolPublicHost) {
+    validateHostOption(
+      result.rollbackHealthPatrolPublicHost,
+      '--rollback-health-patrol-public-host',
+    );
+  }
+  if (
+    result.rollbackPingoraShadowProbeUrl &&
+    !result.rollbackPingoraShadowProbeToken
+  ) {
+    throw new Error(
+      '--rollback-pingora-shadow-probe-url 必须同时提供 --rollback-pingora-shadow-probe-token。',
+    );
+  }
+  if (
+    result.rollbackPingoraShadowProbeToken &&
+    !result.rollbackPingoraShadowProbeUrl
+  ) {
+    throw new Error(
+      '--rollback-pingora-shadow-probe-token 必须同时提供 --rollback-pingora-shadow-probe-url。',
+    );
+  }
+  if (result.rollbackPingoraShadowProbeUrl) {
+    validateHttpUrl(
+      result.rollbackPingoraShadowProbeUrl,
+      '--rollback-pingora-shadow-probe-url',
+    );
+  }
+  if (result.dryRunCutover) {
+    assertSameCutoverHostname(
+      result.directRedirectHost,
+      result.directHost,
+      '--direct-redirect-host',
+      '--direct-host',
+    );
+    assertSameCutoverHostname(
+      result.rollbackNginxSmokeHost,
+      result.directHost,
+      '--rollback-nginx-smoke-host',
+      '--direct-host',
+    );
+    if (result.liveHost) {
+      assertSameCutoverHostname(
+        result.liveHost,
+        result.directHost,
+        '--live-host',
+        '--direct-host',
+      );
+    }
+  }
+  if (result.dryRunCutover && !result.cutoverRunId) {
+    result.cutoverRunId = generateCutoverRunId();
+  }
+  if (result.cutoverRunId) {
+    validateSafeName(result.cutoverRunId, '--cutover-run-id');
+  }
+  if (
+    result.releaseRuntimeOnly &&
+    (result.requireDocker || result.pullDocker || result.requireNginx)
+  ) {
+    throw new Error(
+      '--release-runtime-only 只执行 current release 包内运行时复核，不能同时使用 --require-docker / --pull-docker / --require-nginx；源码全量门禁请在构建环境运行默认模式。',
+    );
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/check-pingora-release-readiness.mjs [options]
+
+Options:
+  --require-docker      Docker Nginx handoff smoke 必须执行通过，不允许跳过。
+  --pull-docker         Docker 镜像缺失时允许拉取；通常和 --require-docker 一起用于 CI。
+  --require-nginx       本机 Nginx snippet 校验必须执行 nginx -t。
+  --require-live        目标 Nginx 已启用 canary 后，强制执行 live canary smoke。
+  --require-realpath-live
+                        目标 Nginx 已启用真实路径 canary 后，强制执行 realpath live canary smoke。
+  --require-direct      目标 Pingora 已配置直连 HTTPS / HTTP redirect 后，强制执行 direct preflight 和 direct live smoke。
+  --live-base-url <url> live canary base URL；也可用 GENARRATIVE_PINGORA_CANARY_BASE_URL。
+  --live-host <host>    live canary Host header；也可用 GENARRATIVE_PINGORA_CANARY_HOST。--require-live 时必须显式提供。
+  --live-nginx-access-log <path>
+                         live canary 后 Nginx access log 对账路径，默认 /var/log/nginx/genarrative.access.log。
+  --live-pingora-access-log <path>
+                         live canary 后 Pingora access log 对账路径，默认 /var/log/genarrative/pingora-gateway.access.log。
+  --live-access-log-since-lines <count>
+                         live canary 后只读取日志尾部行数，默认 2000。
+  --realpath-live-base-url <url>
+                         真实路径 canary base URL；也可用 GENARRATIVE_PINGORA_REALPATH_CANARY_BASE_URL。
+  --realpath-live-host <host>
+                         真实路径 canary Host header；也可用 GENARRATIVE_PINGORA_REALPATH_CANARY_HOST。--require-realpath-live 时必须显式提供。
+  --realpath-live-nginx-access-log <path>
+                         真实路径 canary 独立 Nginx access log，默认 /var/log/nginx/genarrative-pingora-realpath-canary.access.log。
+  --realpath-live-pingora-access-log <path>
+                         真实路径 canary 后 Pingora access log 对账路径，默认 /var/log/genarrative/pingora-gateway.access.log。
+  --realpath-live-access-log-since-lines <count>
+                         真实路径 canary 后只读取日志尾部行数，默认 2000。
+  --direct-https-base-url <url> direct HTTPS base URL；也可用 GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL。
+  --direct-http-base-url <url>  direct HTTP redirect base URL；也可用 GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL。
+  --direct-host <host>          direct live Host header 和 TLS SNI；也可用 GENARRATIVE_PINGORA_DIRECT_HOST。--require-direct 时必须显式提供。
+  --direct-redirect-host <host> direct redirect Location host；也可用 GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST。--require-direct 时必须显式提供，cutover runbook 中必须和 --direct-host 使用同一 hostname。
+  --direct-redirect-base-url <url>
+                              可选 direct redirect Location HTTPS base URL；用于高端口 rehearsal 访问 127.0.0.1:18443 但期望 Location 指向正式 HTTPS 入口。
+  --direct-probe-token <token>  direct live shadow probe token；也可用 GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN。
+  --direct-pingora-access-log <path>
+                              direct live 后 Pingora access log 落盘校验路径；--require-direct 时必须显式提供。
+  --direct-access-log-since-lines <count>
+                              direct live 后只读取 Pingora access log 尾部行数，默认 2000。
+  --direct-preflight-env-file <path>
+                              direct entry 预检使用的 pingora-gateway.env；也可用 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE。
+  --direct-preflight-systemd   direct entry 预检要求 systemctl cat 已包含低端口 capability drop-in。
+  --direct-preflight-check-cert-readable
+                              direct entry 预检要求当前用户可读 cert/key。
+  --direct-preflight-check-service-env-file
+                              direct entry 预检要求 service EnvironmentFile 包含本次 env 文件；--require-direct 时必须显式提供。
+  --direct-preflight-check-service-user-cert-readable
+                              direct entry 预检要求 systemd 服务用户可读 cert/key；--require-direct 时必须显式提供。
+  --direct-preflight-check-service-binary-executable
+                              direct entry 预检要求 service ExecStart 指向的 pingora-gateway 已存在且可执行；--require-direct 时必须显式提供。
+  --direct-preflight-check-ports-free
+                              direct entry 预检要求 TLS/HTTP redirect 端口当前可绑定；--dry-run-cutover / direct enable apply 前必须显式提供，启用后 --require-direct 复核不要求端口空闲。
+  --direct-spacetime-database <name>
+                              direct live WSS subscribe 使用的数据库名；也可用 GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE。--require-direct 时必须显式提供。
+  --direct-health-patrol-env-file <path>
+                              目标机 health-patrol env 文件；--require-direct 时必须显式提供，并复核 gateway mode / public base URL / Host。
+  --direct-require-wss-upgrade
+                              要求 direct live WSS subscribe 必须返回 101；--require-direct 时会自动启用。
+  --direct-skip-wss            跳过 direct live WSS subscribe 握手；只允许单独 direct live 临时排障，--require-direct 会拒绝。
+  --direct-insecure-tls         direct live 允许自签证书；仅本机 smoke 使用。
+  --cutover-release-root <path>
+                              生成切换 runbook 时使用的 current release 根目录，默认 /opt/genarrative/current。
+  --cutover-evidence-output-root <path>
+                              生成切换 runbook 时传给证据包脚本的输出根目录，默认 /var/log/genarrative/pingora-cutover-evidence。
+  --cutover-evidence-timeline-max-span-ms <ms>
+                              生成切换 runbook 时传给证据根目录总审计的标准五段时间线最大跨度，默认 ${DEFAULT_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS}ms。
+  --cutover-run-id <id>       生成切换 runbook 时写入所有证据 manifest 的本次切换批次 ID；不传则自动生成 ${DEFAULT_CUTOVER_RUN_ID_PREFIX}<UTC时间>。
+  --rollback-nginx-smoke-url <url>
+                              生成切换 runbook 时传给回退脚本的 Nginx smoke URL；必须显式填写切换前真实 Nginx 入口。
+  --rollback-nginx-smoke-host <host>
+                              生成切换 runbook 时传给回退脚本的 Host header；默认复用 --direct-host，显式传入时必须和 --direct-host 使用同一 hostname。
+  --rollback-nginx-smoke-expect-body <text>
+                              生成切换 runbook 时传给回退脚本的 Nginx smoke 响应体预期片段；必须显式来自切换前真实响应，例如首页 <!doctype html>。
+  --rollback-health-patrol-public-base-url <url>
+                              生成切换 runbook 时回退后恢复的 Nginx public base URL；应填切换前 health-patrol env 的原值。
+  --rollback-health-patrol-public-host <host>
+                              生成切换 runbook 时回退后恢复的 public Host；不传则要求清空 Host 覆盖。
+  --rollback-pingora-shadow-probe-url <url>
+                              生成切换 runbook 时传给回退脚本的可选 Pingora shadow 探针 URL；必须和 token 成对出现。
+  --rollback-pingora-shadow-probe-token <token>
+                              生成切换 runbook 时传给回退脚本的可选 Pingora shadow 探针 token；JSON 输出会隐藏 token 值。
+  --dry-run-plan        只打印将执行的检查计划，不启动检查命令。
+  --dry-run-cutover     只打印直连切换 runbook，不启动检查或修改系统。
+  --release-runtime-only
+                        只执行 current release 包内运行时复核：current release 自审、live canary、access log 对账、direct preflight、health patrol env 和 direct live；不运行 npm/cargo 源码门禁。
+  --keep-going          单项失败后继续执行后续检查。
+
+默认模式用于本机提交前检查；正式切换窗口建议：
+  node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名>
+
+Pingora 直连入口切换窗口追加：
+  node scripts/check-pingora-release-readiness.mjs --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable
+
+只生成直连切换 runbook：
+  node scripts/check-pingora-release-readiness.mjs --dry-run-cutover --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free --cutover-evidence-output-root /var/log/genarrative/pingora-cutover-evidence --rollback-nginx-smoke-url https://<域名>/ --rollback-nginx-smoke-expect-body '<!doctype html>' --rollback-health-patrol-public-base-url http://127.0.0.1
+`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function readBoolEnv(name, fallback = false) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  const normalized = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${name} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function parsePositiveIntEnv(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parsePositiveInt(raw, name);
+}
+
+function parsePositiveInt(value, label) {
+  const text = String(value || '').trim();
+  if (!/^[1-9]\d*$/u.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`${label} 超出 JavaScript 安全整数范围。`);
+  }
+  return parsed;
+}
+
+function validateHostOption(value, flag) {
+  const raw = String(value);
+  if (raw !== raw.trim() || raw.includes('://') || /[\s/?#@]/.test(raw)) {
+    throw new Error(
+      `${flag} 只能是 host 或 host:port，不能包含 scheme、路径、查询、片段或空白字符`,
+    );
+  }
+  try {
+    const parsed = new URL(`https://${raw}`);
+    if (
+      !parsed.hostname ||
+      parsed.pathname !== '/' ||
+      parsed.search ||
+      parsed.hash ||
+      parsed.username ||
+      parsed.password
+    ) {
+      throw new Error('invalid host');
+    }
+  } catch {
+    throw new Error(`${flag} 不是合法的 host 或 host:port`);
+  }
+}
+
+function validateHttpUrl(value, flag) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`${flag} 必须是 http(s) URL: ${value}`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`${flag} 必须是 http(s) URL: ${value}`);
+  }
+}
+
+function isPositiveIntegerString(value) {
+  return /^[1-9]\d*$/u.test(String(value));
+}
+
+function validateSafeAbsoluteFilePath(value, flag) {
+  if (!path.isAbsolute(value)) {
+    throw new Error(`${flag} 必须是绝对路径。`);
+  }
+  if (isFilesystemRootPath(value)) {
+    throw new Error(`${flag} 不能是文件系统根目录。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function hostnameForIdentity(value, flag) {
+  validateHostOption(value, flag);
+  const parsed = new URL(`https://${String(value).trim()}`);
+  return parsed.hostname.replace(/\.$/u, '').toLowerCase();
+}
+
+function assertSameCutoverHostname(actual, expected, actualFlag, expectedFlag) {
+  const actualHostname = hostnameForIdentity(actual, actualFlag);
+  const expectedHostname = hostnameForIdentity(expected, expectedFlag);
+  if (actualHostname !== expectedHostname) {
+    throw new Error(
+      `${actualFlag} 必须与 ${expectedFlag} 使用同一正式 hostname；当前 ${actualHostname} != ${expectedHostname}`,
+    );
+  }
+}
+
+function validateSafeName(value, flag) {
+  if (!/^[0-9A-Za-z._-]+$/u.test(String(value || ''))) {
+    throw new Error(
+      `${flag} 只能包含 ASCII 字母、数字、点、下划线或短横线。`,
+    );
+  }
+}
+
+function generateCutoverRunId(now = new Date()) {
+  const timestamp = now
+    .toISOString()
+    .replace(/[-:.]/gu, '')
+    .replace(/\d{3}Z$/u, 'Z');
+  return `${DEFAULT_CUTOVER_RUN_ID_PREFIX}${timestamp}`;
+}
+
+function printDryRunPlan(steps) {
+  console.log(
+    JSON.stringify(
+      steps.map((step) => {
+        const output = {
+          name: step.name,
+          command: step.command,
+          args: redactSecretArgs(step.args),
+        };
+        if (step.phase) {
+          output.phase = step.phase;
+        }
+        if (step.when) {
+          output.when = step.when;
+        }
+        return output;
+      }),
+      null,
+      2,
+    ),
+  );
+}
+
+function redactSecretArgs(args) {
+  return args.map((arg, index) =>
+    index > 0 && SECRET_VALUE_FLAGS.has(args[index - 1])
+      ? '<redacted>'
+      : arg,
+  );
+}
+
+function buildCutoverPlan(config) {
+  const releaseRoot = config.cutoverReleaseRoot.replace(/\/+$/u, '');
+  const enableScript = path.join(
+    releaseRoot,
+    'scripts/deploy/pingora-direct-enable.sh',
+  );
+  const rollbackScript = path.join(
+    releaseRoot,
+    'scripts/deploy/pingora-direct-rollback.sh',
+  );
+  const gatewayEnvShadowSwitchScript = path.join(
+    releaseRoot,
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+  );
+  const healthPatrolEnvSwitchScript = path.join(
+    releaseRoot,
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+  );
+  const statusSnapshotScript = path.join(
+    releaseRoot,
+    'scripts/ops/pingora-cutover-status-snapshot.mjs',
+  );
+  const evidenceBundleScript = path.join(
+    releaseRoot,
+    'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+  );
+  const commandEvidenceScript = path.join(
+    releaseRoot,
+    'scripts/ops/pingora-cutover-command-evidence.mjs',
+  );
+  const evidenceVerifyScript = path.join(
+    releaseRoot,
+    'scripts/ops/pingora-cutover-evidence-verify.mjs',
+  );
+  const evidenceAuditScript = path.join(
+    releaseRoot,
+    'scripts/ops/pingora-cutover-evidence-audit.mjs',
+  );
+  const currentReleaseAuditScript = path.join(
+    releaseRoot,
+    'scripts/ops/pingora-current-release-audit.mjs',
+  );
+  const releaseReadinessScript = path.join(
+    releaseRoot,
+    'scripts/check-pingora-release-readiness.mjs',
+  );
+  const releasePreflightScript = path.join(
+    releaseRoot,
+    'scripts/check-pingora-direct-preflight.mjs',
+  );
+  const releaseLiveScript = path.join(
+    releaseRoot,
+    'scripts/check-pingora-direct-live.mjs',
+  );
+  const preEnablePreflightArgs = [
+    releasePreflightScript,
+    '--env-file',
+    config.directPreflightEnvFile,
+    '--require-live-env',
+    ...(config.directPreflightSystemd ? ['--systemd-cat'] : []),
+    '--check-cert-readable',
+    '--check-service-env-file',
+    '--check-service-user-cert-readable',
+    '--check-service-binary-executable',
+    '--check-ports-free',
+  ];
+  const enableBaseArgs = [
+    '--current-release-audit-script',
+    currentReleaseAuditScript,
+    '--current-release-root',
+    releaseRoot,
+    '--preflight-script',
+    releasePreflightScript,
+    '--preflight-env-file',
+    config.directPreflightEnvFile,
+    '--preflight-check-cert-readable',
+    '--preflight-check-service-env-file',
+    '--preflight-check-service-user-cert-readable',
+    '--preflight-check-service-binary-executable',
+    '--preflight-check-ports-free',
+    '--direct-live-script',
+    releaseLiveScript,
+    '--direct-https-base-url',
+    config.directHttpsBaseUrl,
+    '--direct-http-base-url',
+    config.directHttpBaseUrl,
+    '--direct-host',
+    config.directHost,
+    '--direct-redirect-host',
+    config.directRedirectHost,
+    ...(config.directRedirectBaseUrl
+      ? ['--direct-redirect-base-url', config.directRedirectBaseUrl]
+      : []),
+    '--direct-spacetime-database',
+    config.directSpacetimeDatabase,
+    '--direct-pingora-access-log',
+    config.directPingoraAccessLog,
+    '--direct-access-log-since-lines',
+    config.directAccessLogSinceLines,
+    '--no-status',
+  ];
+  if (config.directProbeToken) {
+    enableBaseArgs.push('--direct-probe-token', config.directProbeToken);
+  }
+  const rollbackBaseArgs = [
+    '--reload-nginx',
+    '--nginx-smoke-url',
+    config.rollbackNginxSmokeUrl,
+    '--nginx-smoke-expect-body',
+    config.rollbackNginxSmokeExpectBody,
+    '--health-patrol-env-file',
+    config.directHealthPatrolEnvFile,
+    '--health-patrol-expected-public-base-url',
+    config.rollbackHealthPatrolPublicBaseUrl,
+  ];
+  if (config.rollbackNginxSmokeHost) {
+    rollbackBaseArgs.push('--nginx-smoke-host', config.rollbackNginxSmokeHost);
+  }
+  if (config.rollbackHealthPatrolPublicHost) {
+    rollbackBaseArgs.push(
+      '--health-patrol-expected-public-host',
+      config.rollbackHealthPatrolPublicHost,
+    );
+  } else {
+    rollbackBaseArgs.push('--health-patrol-require-empty-public-host');
+  }
+  if (config.rollbackPingoraShadowProbeUrl) {
+    rollbackBaseArgs.push(
+      '--pingora-shadow-probe-url',
+      config.rollbackPingoraShadowProbeUrl,
+      '--pingora-shadow-probe-token',
+      config.rollbackPingoraShadowProbeToken,
+    );
+  }
+  const healthPatrolDirectSwitchArgs = [
+    '--apply',
+    '--env-file',
+    config.directHealthPatrolEnvFile,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    config.directHttpsBaseUrl,
+    '--public-host',
+    config.directHost,
+  ];
+  const pingoraGatewayShadowSwitchArgs = [
+    '--apply',
+    '--env-file',
+    config.directPreflightEnvFile,
+  ];
+  const healthPatrolNginxSwitchArgs = [
+    '--apply',
+    '--env-file',
+    config.directHealthPatrolEnvFile,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    config.rollbackHealthPatrolPublicBaseUrl,
+    ...(config.rollbackHealthPatrolPublicHost
+      ? ['--public-host', config.rollbackHealthPatrolPublicHost]
+      : ['--clear-public-host']),
+  ];
+
+  return [
+    {
+      phase: 'preflight',
+      name: '切换 Host 一致性确认',
+      command: 'operator-action',
+      args: [
+        'confirm',
+        `cutover-run-id=${config.cutoverRunId}`,
+        `direct-host=${config.directHost}`,
+        `direct-redirect-host=${config.directRedirectHost}`,
+        `direct-redirect-base-url=${config.directRedirectBaseUrl || '-'}`,
+        `health-patrol-public-host=${config.directHost}`,
+        `rollback-nginx-smoke-host=${config.rollbackNginxSmokeHost}`,
+        `rollback-nginx-smoke-expect-body=${config.rollbackNginxSmokeExpectBody}`,
+        `rollback-health-patrol-public-base-url=${config.rollbackHealthPatrolPublicBaseUrl}`,
+        `rollback-health-patrol-public-host=${config.rollbackHealthPatrolPublicHost}`,
+      ],
+      when: 'runbook 生成时已拒绝 hostname 漂移；切换窗口继续人工确认直连、回退 smoke 和回退巡检入口都指向预期目标。',
+    },
+    {
+      phase: 'preflight',
+      name: '切换前 current release 自包含自审',
+      command: 'node',
+      args: [
+        '--',
+        currentReleaseAuditScript,
+        '--release-root',
+        releaseRoot,
+        ...(config.requireDirect ? ['--require-pingora-gateway'] : []),
+        '--systemd-show',
+      ],
+      when: '正式启用前执行，只读确认 current release 已携带 Pingora 切换依赖；直连切换时要求 pingora-gateway 存在且 systemd ExecStart 指向 current release。',
+    },
+    {
+      phase: 'preflight',
+      name: '切换前状态快照证据包',
+      command: 'node',
+      args: [
+        '--',
+        evidenceBundleScript,
+        '--phase',
+        'pre-cutover',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--release-root',
+        releaseRoot,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--snapshot-script',
+        statusSnapshotScript,
+        '--health-patrol-env-file',
+        config.directHealthPatrolEnvFile,
+        '--pingora-env-file',
+        config.directPreflightEnvFile,
+        '--expected-gateway-mode',
+        'nginx',
+        '--expected-public-base-url',
+        config.rollbackHealthPatrolPublicBaseUrl,
+        ...(config.rollbackHealthPatrolPublicHost
+          ? ['--expected-public-host', config.rollbackHealthPatrolPublicHost]
+          : ['--require-empty-public-host']),
+        ...(config.requireDirect ? ['--require-pingora-gateway'] : []),
+        '--run-health-patrol',
+        '--fail-on-critical',
+      ],
+      when: '正式启用前执行，只读采集 current release、health patrol env 和 systemd 最终配置，并把 JSON / stdout / stderr / manifest 归档为 Nginx 接流基线证据。',
+    },
+    {
+      phase: 'preflight',
+      name: '切换前证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<pre-cutover-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: '切换前状态快照证据包生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认 manifest.files 中的 sizeBytes / sha256 与实际归档文件一致，且 manifest.summary.status 为 OK。',
+    },
+    {
+      phase: 'preflight',
+      name: '切换前 current release 直连 env / 证书 / 端口预检',
+      command: 'node',
+      args: ['--', ...preEnablePreflightArgs],
+    },
+    {
+      phase: 'preflight',
+      name: '切换前 release readiness 基础门禁',
+      command: 'node',
+      args: [
+        '--',
+        releaseReadinessScript,
+        ...readinessArgs(config, { includeDirect: false }),
+      ],
+    },
+    {
+      phase: 'enable-dry-run',
+      name: 'Pingora direct enable dry-run',
+      command: enableScript,
+      args: enableBaseArgs,
+    },
+    {
+      phase: 'enable-apply',
+      name: 'Pingora direct enable apply',
+      command: 'node',
+      args: [
+        '--',
+        commandEvidenceScript,
+        '--phase',
+        'enable-apply',
+        '--command-name',
+        'pingora-direct-enable-apply',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--expected-executable',
+        enableScript,
+        '--require-arg',
+        '--apply',
+        '--',
+        enableScript,
+        '--apply',
+        ...enableBaseArgs,
+      ],
+      when: '执行真实 direct enable apply，并把 stdout / stderr / 退出码和脱敏命令记录归档到切换证据目录。',
+    },
+    {
+      phase: 'enable-apply',
+      name: '启用命令证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<enable-apply-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: 'enable apply 命令证据生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认命令 stdout / stderr / command-record 与 manifest 元数据一致，且 manifest.summary.status 为 OK。',
+    },
+    {
+      phase: 'post-enable',
+      name: '切换后 health patrol 切到 Pingora direct',
+      command: 'node',
+      args: [
+        '--',
+        commandEvidenceScript,
+        '--phase',
+        'post-enable',
+        '--command-name',
+        'pingora-health-patrol-direct-env-switch',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--expected-executable',
+        healthPatrolEnvSwitchScript,
+        '--require-arg',
+        '--apply',
+        '--require-arg',
+        'pingora-direct',
+        '--',
+        healthPatrolEnvSwitchScript,
+        ...healthPatrolDirectSwitchArgs,
+      ],
+      when: 'direct enable apply 成功后执行，并用命令证据归档 health patrol env 从 nginx 切到 pingora-direct 的真实 stdout / stderr / 退出码，避免巡检继续要求 nginx.service active。',
+    },
+    {
+      phase: 'post-enable',
+      name: '切换后 health patrol direct 命令证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<health-patrol-direct-env-switch-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: 'health patrol direct env switch 命令证据生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认 env 切换命令 stdout / stderr / command-record 与 manifest 元数据一致，且 manifest.summary.status 为 OK。',
+    },
+    {
+      phase: 'post-enable',
+      name: '启用后 health patrol env 直连复核',
+      command: 'node',
+      args: [
+        '--',
+        path.join(releaseRoot, 'scripts/check-production-health-patrol-env.mjs'),
+        '--env-file',
+        config.directHealthPatrolEnvFile,
+        '--expected-gateway-mode',
+        'pingora-direct',
+        '--expected-public-base-url',
+        config.directHttpsBaseUrl,
+        '--expected-public-host',
+        config.directHost,
+      ],
+    },
+    {
+      phase: 'post-enable',
+      name: '启用后状态快照证据包',
+      command: 'node',
+      args: [
+        '--',
+        evidenceBundleScript,
+        '--phase',
+        'post-enable',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--release-root',
+        releaseRoot,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--snapshot-script',
+        statusSnapshotScript,
+        '--direct-live-script',
+        releaseLiveScript,
+        '--health-patrol-env-file',
+        config.directHealthPatrolEnvFile,
+        '--pingora-env-file',
+        config.directPreflightEnvFile,
+        '--expected-gateway-mode',
+        'pingora-direct',
+        '--expected-pingora-env-mode',
+        'direct',
+        '--expected-public-base-url',
+        config.directHttpsBaseUrl,
+        '--expected-public-host',
+        config.directHost,
+        ...(config.requireDirect ? ['--require-pingora-gateway'] : []),
+        '--run-health-patrol',
+        '--run-direct-live',
+        '--direct-https-base-url',
+        config.directHttpsBaseUrl,
+        '--direct-http-base-url',
+        config.directHttpBaseUrl,
+        '--direct-host',
+        config.directHost,
+        '--direct-redirect-host',
+        config.directRedirectHost,
+        ...(config.directRedirectBaseUrl
+          ? ['--direct-redirect-base-url', config.directRedirectBaseUrl]
+          : []),
+        ...(config.directProbeToken
+          ? ['--direct-probe-token', config.directProbeToken]
+          : []),
+        '--direct-spacetime-database',
+        config.directSpacetimeDatabase,
+        '--direct-pingora-access-log',
+        config.directPingoraAccessLog,
+        '--direct-access-log-since-lines',
+        config.directAccessLogSinceLines,
+        '--fail-on-critical',
+      ],
+      when: 'health patrol env 已切到 pingora-direct 且 env 复核通过后执行，归档 direct 接流状态、direct live 和 Pingora access log request_id 证据包。',
+    },
+    {
+      phase: 'post-enable',
+      name: '启用后证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<post-enable-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: '启用后状态快照证据包生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认 snapshot / direct live / stdout / stderr / 命令记录未在归档过程中漂移，且 manifest.summary.status 为 OK。',
+    },
+    {
+      phase: 'post-enable',
+      name: '启用后 release readiness 直连复核',
+      command: 'node',
+      args: [
+        '--',
+        releaseReadinessScript,
+        ...readinessArgs(config, {
+          includeDirect: true,
+          includeDirectPortsFree: false,
+        }),
+      ],
+      when: 'Pingora 已接管 80/443 后执行；此阶段不再检查端口空闲，因为端口应由 Pingora 直连入口占用。',
+    },
+    {
+      phase: 'rollback-dry-run',
+      name: 'Pingora direct rollback dry-run',
+      command: rollbackScript,
+      args: rollbackBaseArgs,
+      when: '启用失败、direct live smoke 失败或业务验证失败时先执行。',
+    },
+    {
+      phase: 'rollback-prep',
+      name: '回退前 Pingora env 预置回 shadow',
+      command: 'node',
+      args: [
+        '--',
+        commandEvidenceScript,
+        '--phase',
+        'rollback-prep',
+        '--command-name',
+        'pingora-gateway-shadow-env-switch',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--expected-executable',
+        gatewayEnvShadowSwitchScript,
+        '--require-arg',
+        '--apply',
+        '--',
+        gatewayEnvShadowSwitchScript,
+        ...pingoraGatewayShadowSwitchArgs,
+      ],
+      when: 'rollback apply 前执行，并用命令证据归档 Pingora gateway env 从 80/443 direct 配置恢复为 shadow 高端口配置；否则回退脚本移除低端口 capability 后重启 Pingora 可能仍按 80/443 配置启动失败。',
+    },
+    {
+      phase: 'rollback-prep',
+      name: '回退前 Pingora env shadow 命令证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<pingora-gateway-shadow-env-switch-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: 'Pingora gateway shadow env switch 命令证据生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认 env 切换命令 stdout / stderr / command-record 与 manifest 元数据一致，且 manifest.summary.status 为 OK。',
+    },
+    {
+      phase: 'rollback-prep',
+      name: '回退前 health patrol 预置回 Nginx',
+      command: 'node',
+      args: [
+        '--',
+        commandEvidenceScript,
+        '--phase',
+        'rollback-prep',
+        '--command-name',
+        'pingora-health-patrol-nginx-env-switch',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--expected-executable',
+        healthPatrolEnvSwitchScript,
+        '--require-arg',
+        '--apply',
+        '--require-arg',
+        'nginx',
+        '--',
+        healthPatrolEnvSwitchScript,
+        ...healthPatrolNginxSwitchArgs,
+      ],
+      when: 'rollback apply 前执行，并用命令证据归档 health patrol env 从 pingora-direct 预置回 nginx，确保回退脚本内置 health patrol env 复核能校验切换前 public base URL / Host。',
+    },
+    {
+      phase: 'rollback-prep',
+      name: '回退前 health patrol nginx 命令证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<health-patrol-nginx-env-switch-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: 'health patrol nginx env switch 命令证据生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认 env 切换命令 stdout / stderr / command-record 与 manifest 元数据一致，且 manifest.summary.status 为 OK。',
+    },
+    {
+      phase: 'rollback-apply',
+      name: 'Pingora direct rollback apply',
+      command: 'node',
+      args: [
+        '--',
+        commandEvidenceScript,
+        '--phase',
+        'rollback-apply',
+        '--command-name',
+        'pingora-direct-rollback-apply',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--expected-executable',
+        rollbackScript,
+        '--require-arg',
+        '--apply',
+        '--',
+        rollbackScript,
+        '--apply',
+        ...rollbackBaseArgs,
+      ],
+      when: 'health patrol env 预置回 Nginx 且 dry-run 确认后执行，用于回到 Nginx / shadow 入口，并把回退命令 stdout / stderr / 退出码归档。',
+    },
+    {
+      phase: 'rollback-apply',
+      name: '回退命令证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<rollback-apply-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: 'rollback apply 命令证据生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认回退命令 stdout / stderr / command-record 与 manifest 元数据一致，且 manifest.summary.status 为 OK。',
+    },
+    {
+      phase: 'post-rollback',
+      name: '回退后 health patrol env Nginx 模式复核',
+      command: 'node',
+      args: [
+        '--',
+        path.join(releaseRoot, 'scripts/check-production-health-patrol-env.mjs'),
+        '--env-file',
+        config.directHealthPatrolEnvFile,
+        '--expected-gateway-mode',
+        'nginx',
+        ...(config.rollbackHealthPatrolPublicBaseUrl
+          ? [
+              '--expected-public-base-url',
+              config.rollbackHealthPatrolPublicBaseUrl,
+            ]
+          : []),
+        ...(config.rollbackHealthPatrolPublicHost
+          ? [
+              '--expected-public-host',
+              config.rollbackHealthPatrolPublicHost,
+            ]
+          : ['--require-empty-public-host']),
+      ],
+      when: 'health patrol env 已切回 nginx 后执行，阻断 pingora-direct 模式或回退目标漂移。',
+    },
+    {
+      phase: 'post-rollback',
+      name: '回退后状态快照证据包',
+      command: 'node',
+      args: [
+        '--',
+        evidenceBundleScript,
+        '--phase',
+        'post-rollback',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--release-root',
+        releaseRoot,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--snapshot-script',
+        statusSnapshotScript,
+        '--health-patrol-env-file',
+        config.directHealthPatrolEnvFile,
+        '--pingora-env-file',
+        config.directPreflightEnvFile,
+        '--expected-gateway-mode',
+        'nginx',
+        '--expected-pingora-env-mode',
+        'shadow',
+        '--expected-public-base-url',
+        config.rollbackHealthPatrolPublicBaseUrl,
+        ...(config.rollbackHealthPatrolPublicHost
+          ? ['--expected-public-host', config.rollbackHealthPatrolPublicHost]
+          : ['--require-empty-public-host']),
+        ...(config.requireDirect ? ['--require-pingora-gateway'] : []),
+        '--run-health-patrol',
+        '--fail-on-critical',
+      ],
+      when: 'rollback apply 和回退后 env 复核通过后执行，归档 Nginx 接流状态证据包。',
+    },
+    {
+      phase: 'post-rollback',
+      name: '回退后证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<post-rollback-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: '回退后状态快照证据包生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认回退证据 manifest 和文件内容一致，且 manifest.summary.status 为 OK。',
+    },
+    {
+      phase: 'post-rollback',
+      name: '切换证据根目录三阶段总审计',
+      command: 'node',
+      args: [
+        '--',
+        evidenceAuditScript,
+        '--evidence-root',
+        config.cutoverEvidenceOutputRoot,
+        '--verify-script',
+        evidenceVerifyScript,
+        '--require-phase',
+        'pre-cutover',
+        '--require-phase',
+        'post-enable',
+        '--require-phase',
+        'post-rollback',
+        '--require-phase-direct-live-access-log',
+        'post-enable',
+        '--require-phase-direct-live-static-headers',
+        'post-enable',
+        '--require-phase-pingora-env-shadow',
+        'post-rollback',
+        '--require-command',
+        'enable-apply:pingora-direct-enable-apply',
+        '--require-command',
+        'post-enable:pingora-health-patrol-direct-env-switch',
+        '--require-command',
+        'rollback-prep:pingora-gateway-shadow-env-switch',
+        '--require-command',
+        'rollback-prep:pingora-health-patrol-nginx-env-switch',
+        '--require-command',
+        'rollback-apply:pingora-direct-rollback-apply',
+        '--require-command-executable',
+        `enable-apply:pingora-direct-enable-apply:${enableScript}`,
+        '--require-command-executable',
+        `post-enable:pingora-health-patrol-direct-env-switch:${healthPatrolEnvSwitchScript}`,
+        '--require-command-executable',
+        `rollback-prep:pingora-gateway-shadow-env-switch:${gatewayEnvShadowSwitchScript}`,
+        '--require-command-executable',
+        `rollback-prep:pingora-health-patrol-nginx-env-switch:${healthPatrolEnvSwitchScript}`,
+        '--require-command-executable',
+        `rollback-apply:pingora-direct-rollback-apply:${rollbackScript}`,
+        '--require-command-arg',
+        'enable-apply:pingora-direct-enable-apply:--apply',
+        '--require-command-arg',
+        'post-enable:pingora-health-patrol-direct-env-switch:--apply',
+        '--require-command-arg',
+        'post-enable:pingora-health-patrol-direct-env-switch:pingora-direct',
+        '--require-command-arg',
+        'rollback-prep:pingora-gateway-shadow-env-switch:--apply',
+        '--require-command-arg',
+        'rollback-prep:pingora-health-patrol-nginx-env-switch:--apply',
+        '--require-command-arg',
+        'rollback-prep:pingora-health-patrol-nginx-env-switch:nginx',
+        '--require-command-arg',
+        'rollback-apply:pingora-direct-rollback-apply:--apply',
+        '--require-cutover-run-id',
+        config.cutoverRunId,
+        '--timeline-max-span-ms',
+        String(config.cutoverEvidenceTimelineMaxSpanMs),
+      ],
+      when: '三阶段证据包、enable / rollback apply 命令证据和三条 env 变更命令证据都生成并分别验真后执行，自动找每个 phase 与命令的最新 bundleDir 并再次做只读 manifest 验真，且要求 post-enable manifest.summary.directLiveAccessLog 和 directLiveStaticHeaders 可直接复盘 request_id 对账、静态缓存、校验器、Range 和 304 证据，同时要求 post-rollback manifest.summary.pingoraEnvShadow 证明 Pingora env 已恢复 shadow 高端口。',
+    },
+  ];
+}
+
+function readinessArgs(config, { includeDirect, includeDirectPortsFree = true }) {
+  return [
+    '--release-runtime-only',
+    ...(config.requireLive
+      ? [
+          '--require-live',
+          '--live-base-url',
+          config.liveBaseUrl,
+          '--live-host',
+          config.liveHost,
+        ]
+      : []),
+    ...(config.requireRealpathLive
+      ? [
+          '--require-realpath-live',
+          '--realpath-live-base-url',
+          config.realpathLiveBaseUrl,
+          '--realpath-live-host',
+          config.realpathLiveHost,
+          '--realpath-live-nginx-access-log',
+          config.realpathLiveAccessLogNginx,
+          '--realpath-live-pingora-access-log',
+          config.realpathLiveAccessLogPingora,
+          '--realpath-live-access-log-since-lines',
+          String(config.realpathLiveAccessLogSinceLines),
+        ]
+      : []),
+    ...(includeDirect
+      ? [
+          '--require-direct',
+          '--direct-https-base-url',
+          config.directHttpsBaseUrl,
+          '--direct-http-base-url',
+          config.directHttpBaseUrl,
+          '--direct-host',
+          config.directHost,
+          '--direct-redirect-host',
+          config.directRedirectHost,
+          ...(config.directRedirectBaseUrl
+            ? ['--direct-redirect-base-url', config.directRedirectBaseUrl]
+            : []),
+          ...(config.directProbeToken
+            ? ['--direct-probe-token', config.directProbeToken]
+            : []),
+          '--direct-pingora-access-log',
+          config.directPingoraAccessLog,
+          '--direct-access-log-since-lines',
+          config.directAccessLogSinceLines,
+          '--direct-spacetime-database',
+          config.directSpacetimeDatabase,
+          '--direct-health-patrol-env-file',
+          config.directHealthPatrolEnvFile,
+          '--direct-preflight-env-file',
+          config.directPreflightEnvFile,
+          '--direct-preflight-systemd',
+          '--direct-preflight-check-cert-readable',
+          '--direct-preflight-check-service-env-file',
+          '--direct-preflight-check-service-user-cert-readable',
+          '--direct-preflight-check-service-binary-executable',
+          ...(includeDirectPortsFree
+            ? ['--direct-preflight-check-ports-free']
+            : []),
+        ]
+      : []),
+  ];
+}
+
+function buildSteps(config) {
+  if (config.releaseRuntimeOnly) {
+    return buildReleaseRuntimeSteps(config);
+  }
+
+  const steps = [
+    {
+      name: 'Rust 路由与保护单测',
+      command: 'cargo',
+      args: [
+        'test',
+        '-p',
+        'pingora-gateway',
+        '--manifest-path',
+        'server-rs/Cargo.toml',
+      ],
+    },
+    {
+      name: 'Pingora mock 上游 smoke',
+      command: 'npm',
+      args: ['run', 'check:pingora-gateway-smoke'],
+    },
+    {
+      name: 'Nginx/Pingora 路由矩阵 parity',
+      command: 'npm',
+      args: ['run', 'check:pingora-route-parity'],
+    },
+    {
+      name: 'Nginx canary snippet 校验',
+      command: 'node',
+      args: [
+        'scripts/check-nginx-pingora-canary.mjs',
+        ...(config.requireNginx ? ['--require-nginx'] : []),
+      ],
+    },
+    {
+      name: 'Docker Nginx handoff smoke',
+      command: 'node',
+      args: [
+        'scripts/check-pingora-canary-docker.mjs',
+        ...(config.requireDocker ? ['--require-docker'] : []),
+        ...(config.pullDocker ? ['--pull'] : []),
+      ],
+    },
+    {
+      name: 'Pingora canary access log 对账烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-canary-access-log-parity'],
+    },
+    {
+      name: 'Pingora realpath canary 启停烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-realpath-canary-toggle'],
+    },
+    {
+      name: 'Pingora canary live 参数护栏',
+      command: 'node',
+      args: ['scripts/check-pingora-canary-live-guard.mjs'],
+    },
+    {
+      name: 'Pingora direct entry 静态预检',
+      command: 'npm',
+      args: ['run', 'check:pingora-direct-preflight'],
+    },
+    {
+      name: 'Pingora direct live 参数护栏',
+      command: 'node',
+      args: ['scripts/check-pingora-direct-live-guard.mjs'],
+    },
+    {
+      name: 'Pingora direct rollback dry-run',
+      command: 'npm',
+      args: ['run', 'check:pingora-direct-rollback'],
+    },
+    {
+      name: 'Pingora direct enable dry-run',
+      command: 'npm',
+      args: ['run', 'check:pingora-direct-enable'],
+    },
+    {
+      name: 'Pingora release readiness plan',
+      command: 'npm',
+      args: ['run', 'check:pingora-release-readiness-plan'],
+    },
+    {
+      name: '生产运维护栏',
+      command: 'npm',
+      args: ['run', 'check:production-ops'],
+    },
+    {
+      name: '生产健康巡检烟测',
+      command: 'npm',
+      args: ['run', 'check:production-health-patrol'],
+    },
+    {
+      name: '生产健康巡检 env 复核烟测',
+      command: 'npm',
+      args: ['run', 'check:production-health-patrol-env'],
+    },
+    {
+      name: 'Pingora health patrol env 切换烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-health-patrol-env-switch'],
+    },
+    {
+      name: 'Pingora gateway env shadow 切换烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-gateway-env-shadow-switch'],
+    },
+    {
+      name: 'Pingora current release 自审烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-current-release-audit'],
+    },
+    {
+      name: 'Pingora direct rehearsal 状态烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-direct-rehearsal-status'],
+    },
+    {
+      name: 'Pingora cutover 状态快照烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-cutover-status-snapshot'],
+    },
+    {
+      name: 'Pingora cutover 证据包烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-cutover-evidence-bundle'],
+    },
+    {
+      name: 'Pingora cutover 命令证据烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-cutover-command-evidence'],
+    },
+    {
+      name: 'Pingora cutover 证据 manifest 验真烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-cutover-evidence-verify'],
+    },
+    {
+      name: 'Pingora cutover 证据根目录审计烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-cutover-evidence-audit'],
+    },
+    {
+      name: 'API release build 烟测',
+      command: 'npm',
+      args: ['run', 'check:production-api-release'],
+    },
+    {
+      name: 'Pingora production release 真实构建烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-production-release-build'],
+    },
+    {
+      name: 'API deploy release 烟测',
+      command: 'npm',
+      args: ['run', 'check:production-api-deploy'],
+    },
+  ];
+
+  if (config.requireLive || config.liveBaseUrl) {
+    appendTargetLiveSteps(steps, config, scriptPath);
+  }
+  appendTargetRealpathLiveSteps(steps, config, scriptPath);
+
+  if (config.requireDirect || config.directHttpsBaseUrl) {
+    steps.push({
+      name: '目标 Pingora direct entry preflight',
+      command: 'node',
+      args: [
+        '--',
+        'scripts/check-pingora-direct-preflight.mjs',
+        ...(config.directPreflightEnvFile
+          ? ['--env-file', config.directPreflightEnvFile, '--require-live-env']
+          : []),
+        ...(config.directPreflightSystemd ? ['--systemd-cat'] : []),
+        ...(config.directPreflightCheckCertReadable
+          ? ['--check-cert-readable']
+          : []),
+        ...(config.directPreflightCheckServiceEnvFile
+          ? ['--check-service-env-file']
+          : []),
+        ...(config.directPreflightCheckServiceUserCertReadable
+          ? ['--check-service-user-cert-readable']
+          : []),
+        ...(config.directPreflightCheckServiceBinaryExecutable
+          ? ['--check-service-binary-executable']
+          : []),
+        ...(config.directPreflightCheckPortsFree ? ['--check-ports-free'] : []),
+      ],
+    });
+    if (config.requireDirect || config.directHealthPatrolEnvFile) {
+      steps.push({
+        name: '目标 health patrol env 直连模式复核',
+        command: 'node',
+        args: [
+          '--',
+          'scripts/check-production-health-patrol-env.mjs',
+          '--env-file',
+          config.directHealthPatrolEnvFile,
+          '--expected-gateway-mode',
+          'pingora-direct',
+          '--expected-public-base-url',
+          config.directHttpsBaseUrl,
+          '--expected-public-host',
+          config.directHost,
+        ],
+      });
+    }
+    steps.push({
+      name: '目标 Pingora direct live smoke',
+      command: 'node',
+      args: [
+        'scripts/check-pingora-direct-live.mjs',
+        '--https-base-url',
+        config.directHttpsBaseUrl,
+        ...(config.directHttpBaseUrl
+          ? ['--http-base-url', config.directHttpBaseUrl]
+          : []),
+        ...(config.directHost ? ['--host', config.directHost] : []),
+        ...(config.directRedirectHost
+          ? ['--redirect-host', config.directRedirectHost]
+          : []),
+        ...(config.directRedirectBaseUrl
+          ? ['--redirect-base-url', config.directRedirectBaseUrl]
+          : []),
+        ...(config.directProbeToken
+          ? ['--probe-token', config.directProbeToken]
+          : []),
+        ...(config.directPingoraAccessLog
+          ? [
+              '--pingora-access-log',
+              config.directPingoraAccessLog,
+              '--access-log-since-lines',
+              config.directAccessLogSinceLines,
+            ]
+          : []),
+        ...(config.directSpacetimeDatabase
+          ? ['--spacetime-database', config.directSpacetimeDatabase]
+          : []),
+        ...(config.directRequireWssUpgrade ? ['--require-wss-upgrade'] : []),
+        ...(config.directSkipWss ? ['--skip-wss'] : []),
+        ...(config.directInsecureTls ? ['--insecure-tls'] : []),
+      ],
+    });
+  }
+
+  return steps;
+}
+
+function buildReleaseRuntimeSteps(config) {
+  const steps = [
+    {
+      name: 'current release 自包含自审',
+      command: 'node',
+      args: [
+        '--',
+        releaseScriptPath('scripts/ops/pingora-current-release-audit.mjs'),
+        '--release-root',
+        releaseRoot,
+        ...(config.requireDirect ? ['--require-pingora-gateway'] : []),
+        ...(config.requireDirect ? ['--systemd-show'] : []),
+      ],
+      cwd: releaseRoot,
+    },
+  ];
+
+  if (!config.requireDirect) {
+    steps.push({
+      name: '目标 Pingora direct rehearsal 状态复核',
+      command: 'node',
+      args: [
+        '--',
+        releaseScriptPath('scripts/ops/pingora-direct-rehearsal-status.mjs'),
+        '--release-root',
+        releaseRoot,
+        '--expect-public-gateway',
+        'nginx',
+        '--require-pingora-shadow',
+        '--require-realpath-canary',
+        '--require-current-release-gateway',
+        '--fail-on-critical',
+      ],
+      cwd: releaseRoot,
+    });
+  }
+
+  appendTargetLiveSteps(steps, config, releaseScriptPath);
+  appendTargetRealpathLiveSteps(steps, config, releaseScriptPath);
+  appendTargetDirectSteps(steps, config, releaseScriptPath);
+
+  return steps;
+}
+
+function appendTargetLiveSteps(steps, config, scriptPath) {
+  if (!config.requireLive && !config.liveBaseUrl) {
+    return;
+  }
+  steps.push({
+    name: '目标 Nginx live canary smoke',
+    command: 'node',
+    args: [
+      '--',
+      scriptPath('scripts/check-pingora-canary-live.mjs'),
+      '--base-url',
+      config.liveBaseUrl,
+      ...(config.liveHost ? ['--host', config.liveHost] : []),
+    ],
+    cwd: releaseRoot,
+  });
+  steps.push({
+    name: '目标 Nginx live canary access log 对账',
+    command: 'node',
+    args: [
+      '--',
+      scriptPath('scripts/check-pingora-canary-access-log-parity.mjs'),
+      '--nginx-log-file',
+      config.liveAccessLogNginx,
+      '--pingora-log-file',
+      config.liveAccessLogPingora,
+      '--since-lines',
+      String(config.liveAccessLogSinceLines),
+      '--path',
+      '/__genarrative_pingora_canary/healthz',
+      '--path',
+      '/__genarrative_pingora_canary/api/creation-entry/config',
+    ],
+    cwd: releaseRoot,
+  });
+}
+
+function appendTargetRealpathLiveSteps(steps, config, scriptPath) {
+  if (!config.requireRealpathLive && !config.realpathLiveBaseUrl) {
+    return;
+  }
+  steps.push({
+    name: '目标 Nginx realpath canary smoke',
+    command: 'node',
+    args: [
+      '--',
+      scriptPath('scripts/check-pingora-canary-live.mjs'),
+      '--realpath',
+      '--base-url',
+      config.realpathLiveBaseUrl,
+      ...(config.realpathLiveHost ? ['--host', config.realpathLiveHost] : []),
+    ],
+    cwd: releaseRoot,
+  });
+  steps.push({
+    name: '目标 Nginx realpath canary access log 对账',
+    command: 'node',
+    args: [
+      '--',
+      scriptPath('scripts/check-pingora-canary-access-log-parity.mjs'),
+      '--realpath',
+      '--nginx-log-file',
+      config.realpathLiveAccessLogNginx,
+      '--pingora-log-file',
+      config.realpathLiveAccessLogPingora,
+      '--since-lines',
+      String(config.realpathLiveAccessLogSinceLines),
+      '--path',
+      '/__genarrative_pingora_realpath_canary/healthz',
+      '--path',
+      '/api/creation-entry/config',
+      '--path',
+      '/v1/identity',
+      '--path',
+      '/assets/app.js',
+    ],
+    cwd: releaseRoot,
+  });
+}
+
+function appendTargetDirectSteps(steps, config, scriptPath) {
+  if (!config.requireDirect && !config.directHttpsBaseUrl) {
+    return;
+  }
+  steps.push({
+    name: '目标 Pingora direct entry preflight',
+    command: 'node',
+    args: [
+      '--',
+      scriptPath('scripts/check-pingora-direct-preflight.mjs'),
+      ...(config.directPreflightEnvFile
+        ? ['--env-file', config.directPreflightEnvFile, '--require-live-env']
+        : []),
+      ...(config.directPreflightSystemd ? ['--systemd-cat'] : []),
+      ...(config.directPreflightCheckCertReadable
+        ? ['--check-cert-readable']
+        : []),
+      ...(config.directPreflightCheckServiceEnvFile
+        ? ['--check-service-env-file']
+        : []),
+      ...(config.directPreflightCheckServiceUserCertReadable
+        ? ['--check-service-user-cert-readable']
+        : []),
+      ...(config.directPreflightCheckServiceBinaryExecutable
+        ? ['--check-service-binary-executable']
+        : []),
+      ...(config.directPreflightCheckPortsFree ? ['--check-ports-free'] : []),
+    ],
+    cwd: releaseRoot,
+  });
+  if (config.requireDirect || config.directHealthPatrolEnvFile) {
+    steps.push({
+      name: '目标 health patrol env 直连模式复核',
+      command: 'node',
+      args: [
+        '--',
+        scriptPath('scripts/check-production-health-patrol-env.mjs'),
+        '--env-file',
+        config.directHealthPatrolEnvFile,
+        '--expected-gateway-mode',
+        'pingora-direct',
+        '--expected-public-base-url',
+        config.directHttpsBaseUrl,
+        '--expected-public-host',
+        config.directHost,
+      ],
+      cwd: releaseRoot,
+    });
+  }
+  steps.push({
+    name: '目标 Pingora direct live smoke',
+    command: 'node',
+    args: [
+      '--',
+      scriptPath('scripts/check-pingora-direct-live.mjs'),
+      '--https-base-url',
+      config.directHttpsBaseUrl,
+      ...(config.directHttpBaseUrl
+        ? ['--http-base-url', config.directHttpBaseUrl]
+        : []),
+      ...(config.directHost ? ['--host', config.directHost] : []),
+      ...(config.directRedirectHost
+        ? ['--redirect-host', config.directRedirectHost]
+        : []),
+      ...(config.directRedirectBaseUrl
+        ? ['--redirect-base-url', config.directRedirectBaseUrl]
+        : []),
+      ...(config.directProbeToken
+        ? ['--probe-token', config.directProbeToken]
+        : []),
+      ...(config.directPingoraAccessLog
+        ? [
+            '--pingora-access-log',
+            config.directPingoraAccessLog,
+            '--access-log-since-lines',
+            config.directAccessLogSinceLines,
+          ]
+        : []),
+      ...(config.directSpacetimeDatabase
+        ? ['--spacetime-database', config.directSpacetimeDatabase]
+        : []),
+      ...(config.directRequireWssUpgrade ? ['--require-wss-upgrade'] : []),
+      ...(config.directSkipWss ? ['--skip-wss'] : []),
+      ...(config.directInsecureTls ? ['--insecure-tls'] : []),
+    ],
+    cwd: releaseRoot,
+  });
+}
+
+function releaseScriptPath(relativePath) {
+  return path.join(releaseRoot, relativePath);
+}
+
+function scriptPath(relativePath) {
+  return relativePath;
+}
+
+function runStep(step) {
+  const args = commandArgsForSpawn(step);
+  console.log(`\n[pingora-release-readiness] ${step.name}`);
+  console.log(
+    `[pingora-release-readiness] ${step.command} ${redactSecretArgs(args).join(' ')}`,
+  );
+
+  return new Promise((resolve) => {
+    const child = spawn(step.command, args, {
+      cwd: step.cwd || repoRoot,
+      env: smokeEnv(),
+      shell: false,
+      stdio: 'inherit',
+    });
+
+    child.on('error', (error) => {
+      failures.push(`${step.name}: ${step.command} 启动失败：${error.message}`);
+      resolve(false);
+    });
+    child.on('exit', (status, signal) => {
+      if (signal) {
+        failures.push(`${step.name}: 被信号终止：${signal}`);
+        resolve(false);
+        return;
+      }
+      if ((status ?? 0) !== 0) {
+        failures.push(`${step.name}: 退出码 ${status}`);
+        resolve(false);
+        return;
+      }
+      resolve(true);
+    });
+  });
+}
+
+function commandArgsForSpawn(step) {
+  if (step.command === 'node' && step.args[0] !== '--') {
+    return ['--', ...step.args];
+  }
+  return step.args;
+}
+
+function smokeEnv() {
+  return {
+    ...process.env,
+    PATH: `${path.join(os.homedir(), '.local', 'bin')}:${process.env.PATH || ''}`,
+  };
+}
diff --git a/scripts/check-pingora-route-parity.mjs b/scripts/check-pingora-route-parity.mjs
new file mode 100644
index 000000000..78372e43b
--- /dev/null
+++ b/scripts/check-pingora-route-parity.mjs
@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+
+const MATRIX_PATH = 'deploy/pingora/nginx-route-parity.matrix.json';
+const PRODUCTION_NGINX_PATH = 'deploy/nginx/genarrative.conf';
+const DEVELOPMENT_NGINX_PATH = 'deploy/nginx/genarrative-dev-http.conf';
+const PINGORA_DOC_PATH =
+  'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md';
+const PINGORA_GATEWAY_SOURCE = 'server-rs/crates/pingora-gateway/src/main.rs';
+
+const VALID_KINDS = new Set([
+  'proxy',
+  'static',
+  'redirect_permanent',
+  'shadow_probe',
+  'not_found',
+]);
+const VALID_PROXY_TARGETS = new Set(['api', 'spacetime']);
+const VALID_STATIC_ROOTS = new Set(['web', 'acme']);
+const VALID_STATIC_MODES = new Set(['exact', 'spa_fallback']);
+const VALID_PROTECTION_CLASSES = new Set([
+  'admin_api',
+  'gallery_list',
+  'gallery_detail',
+  'api',
+  'spacetime',
+]);
+const REQUIRED_ROUTE_IDS = [
+  'acme_challenge',
+  'shadow_probe',
+  'admin_redirect',
+  'admin_api_proxy',
+  'admin_assets',
+  'admin_spa_fallback',
+  'web_assets',
+  'puzzle_gallery_list',
+  'custom_world_gallery_list',
+  'puzzle_gallery_detail',
+  'custom_world_gallery_detail',
+  'generic_api_proxy',
+  'spacetime_subscribe',
+  'spacetime_identity',
+  'v1_forbidden',
+  'healthz_forbidden',
+  'readyz_forbidden',
+  'generated_assets_forbidden',
+  'web_spa_fallback',
+];
+
+const files = {
+  production: readFileSync(PRODUCTION_NGINX_PATH, 'utf8'),
+  development: readFileSync(DEVELOPMENT_NGINX_PATH, 'utf8'),
+};
+const docs = readFileSync(PINGORA_DOC_PATH, 'utf8');
+const pingoraGatewaySource = readFileSync(PINGORA_GATEWAY_SOURCE, 'utf8');
+const matrix = JSON.parse(readFileSync(MATRIX_PATH, 'utf8'));
+const failures = [];
+
+function fail(message) {
+  failures.push(message);
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function requireString(value, context) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    fail(`${context} 必须是非空字符串。`);
+    return false;
+  }
+  return true;
+}
+
+function validateExpectation(route) {
+  const context = `${MATRIX_PATH} route ${route.id}`;
+  const expect = route.expect;
+  if (!expect || typeof expect !== 'object' || Array.isArray(expect)) {
+    fail(`${context} 缺少 expect 对象。`);
+    return;
+  }
+
+  if (!VALID_KINDS.has(expect.kind)) {
+    fail(`${context} expect.kind 不支持: ${expect.kind}`);
+    return;
+  }
+
+  if (expect.kind === 'proxy') {
+    if (!VALID_PROXY_TARGETS.has(expect.target)) {
+      fail(`${context} proxy target 不支持: ${expect.target}`);
+    }
+    if (
+      hasOwn(expect, 'bodyLimit') &&
+      expect.bodyLimit !== null &&
+      expect.bodyLimit !== 'default' &&
+      (!Number.isInteger(expect.bodyLimit) || expect.bodyLimit < 1)
+    ) {
+      fail(`${context} bodyLimit 必须是 null、default 或正整数。`);
+    }
+    if (!VALID_PROTECTION_CLASSES.has(expect.protectionClass)) {
+      fail(
+        `${context} proxy protectionClass 不支持: ${expect.protectionClass}`,
+      );
+    }
+    return;
+  }
+
+  if (hasOwn(expect, 'protectionClass')) {
+    fail(`${context} 非 proxy 路由不能配置 protectionClass。`);
+  }
+
+  if (expect.kind === 'static') {
+    if (!VALID_STATIC_ROOTS.has(expect.root)) {
+      fail(`${context} static root 不支持: ${expect.root}`);
+    }
+    if (!VALID_STATIC_MODES.has(expect.mode)) {
+      fail(`${context} static mode 不支持: ${expect.mode}`);
+    }
+  }
+
+  if (
+    expect.kind === 'redirect_permanent' &&
+    !requireString(expect.location, `${context} redirect location`)
+  ) {
+    fail(`${context} redirect_permanent 必须配置 location。`);
+  }
+}
+
+function validateNginxFragments(route) {
+  for (const environment of ['production', 'development']) {
+    const fragments = route.nginx?.[environment];
+    if (fragments === undefined) {
+      if (environment === 'production' && route.id !== 'shadow_probe') {
+        fail(`${MATRIX_PATH} route ${route.id} 缺少 production Nginx 片段。`);
+      }
+      continue;
+    }
+    if (!Array.isArray(fragments) || fragments.length === 0) {
+      fail(
+        `${MATRIX_PATH} route ${route.id} 的 ${environment} Nginx 片段不能为空。`,
+      );
+      continue;
+    }
+
+    for (const fragment of fragments) {
+      if (!requireString(fragment, `${route.id} ${environment} Nginx 片段`)) {
+        continue;
+      }
+      if (!files[environment].includes(fragment)) {
+        fail(
+          `${environment} Nginx 模板缺少 route ${route.id} 片段: ${fragment}`,
+        );
+      }
+    }
+  }
+}
+
+function validateDocFragments(route) {
+  if (!Array.isArray(route.docs) || route.docs.length === 0) {
+    fail(`${MATRIX_PATH} route ${route.id} 缺少 docs 片段。`);
+    return;
+  }
+
+  for (const fragment of route.docs) {
+    if (!requireString(fragment, `${route.id} docs 片段`)) {
+      continue;
+    }
+    if (!docs.includes(fragment)) {
+      fail(`Pingora 试点文档缺少 route ${route.id} 片段: ${fragment}`);
+    }
+  }
+}
+
+function validateMatrixShape() {
+  if (matrix.version !== 1) {
+    fail(`${MATRIX_PATH} version 必须为 1。`);
+  }
+  if (!Array.isArray(matrix.routes) || matrix.routes.length === 0) {
+    fail(`${MATRIX_PATH} routes 不能为空。`);
+    return;
+  }
+
+  const ids = new Set();
+  const samplePaths = new Set();
+  for (const route of matrix.routes) {
+    if (!requireString(route.id, `${MATRIX_PATH} route.id`)) {
+      continue;
+    }
+    if (ids.has(route.id)) {
+      fail(`${MATRIX_PATH} route id 重复: ${route.id}`);
+    }
+    ids.add(route.id);
+
+    if (!requireString(route.samplePath, `${route.id} samplePath`)) {
+      continue;
+    }
+    if (!route.samplePath.startsWith('/')) {
+      fail(`${MATRIX_PATH} route ${route.id} samplePath 必须以 / 开头。`);
+    }
+    if (samplePaths.has(route.samplePath)) {
+      fail(`${MATRIX_PATH} samplePath 重复: ${route.samplePath}`);
+    }
+    samplePaths.add(route.samplePath);
+
+    validateExpectation(route);
+    validateNginxFragments(route);
+    validateDocFragments(route);
+  }
+
+  for (const routeId of REQUIRED_ROUTE_IDS) {
+    if (!ids.has(routeId)) {
+      fail(`${MATRIX_PATH} 缺少必需 route id: ${routeId}`);
+    }
+  }
+}
+
+function validateRustTestUsesMatrix() {
+  for (const fragment of [
+    'include_str!("../../../../deploy/pingora/nginx-route-parity.matrix.json")',
+    'serde_json::from_str(ROUTE_PARITY_MATRIX_JSON)',
+    'protection_class_for_route(&route, &case.sample_path)',
+    'fn matches_nginx_route_parity_matrix()',
+  ]) {
+    if (!pingoraGatewaySource.includes(fragment)) {
+      fail(`Pingora Rust 路由 parity 测试缺少矩阵接入片段: ${fragment}`);
+    }
+  }
+}
+
+validateMatrixShape();
+validateRustTestUsesMatrix();
+
+if (failures.length > 0) {
+  console.error('[check:pingora-route-parity] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log(`[check:pingora-route-parity] OK (${matrix.routes.length} routes)`);
diff --git a/scripts/check-pingora-tls-cert-sync.mjs b/scripts/check-pingora-tls-cert-sync.mjs
new file mode 100644
index 000000000..a3578fe2c
--- /dev/null
+++ b/scripts/check-pingora-tls-cert-sync.mjs
@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const SCRIPT = 'scripts/deploy/pingora-tls-cert-sync.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-tls-cert-sync-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-tls-cert-sync] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-tls-cert-sync] OK');
+
+function main() {
+  assertDryRunAcceptsCertbotLiveSymlinks();
+  assertApplyCopiesToPrivateTarget();
+  assertRejectsRelativeAndRootPaths();
+  assertRejectsControlCharactersBeforeApply();
+  assertRejectsSymlinkTargetDirectory();
+  assertRejectsSymlinkTargetFiles();
+  assertRejectsWorldReadableModes();
+}
+
+function assertDryRunAcceptsCertbotLiveSymlinks() {
+  const fixture = prepareFixture('dry-run-live-symlink');
+  const result = runSync(fixture, []);
+  assertStatus(result, 0, 'dry-run 应接受 Certbot live symlink 源。');
+  if (existsSync(fixture.targetCert) || existsSync(fixture.targetKey)) {
+    failures.push('dry-run 不应写入目标证书文件。');
+  }
+  const payload = parseJson(result.stdout, 'dry-run JSON 输出');
+  assertEqual(payload.mode, 'dry-run', 'dry-run JSON mode 应为 dry-run。');
+  assertEqual(
+    payload.files?.[0]?.source?.sourceIsSymlink,
+    true,
+    'dry-run JSON 应标记源证书来自 symlink。',
+  );
+}
+
+function assertApplyCopiesToPrivateTarget() {
+  const fixture = prepareFixture('apply-copy', { symlinkSources: false });
+  const result = runSync(fixture, ['--apply'], {
+    serviceUser: `#${process.getuid?.() ?? 0}`,
+    serviceGroup: `#${process.getgid?.() ?? 0}`,
+    targetUser: `#${process.getuid?.() ?? 0}`,
+  });
+  assertStatus(result, 0, 'apply 应复制证书到目标目录。');
+  assertFileContent(fixture.targetCert, 'fixture fullchain\n');
+  assertFileContent(fixture.targetKey, 'fixture private key\n');
+  assertMode(fixture.targetDir, 0o750, '目标目录权限应为 0750。');
+  assertMode(fixture.targetCert, 0o640, '目标证书权限应为 0640。');
+  assertMode(fixture.targetKey, 0o640, '目标私钥权限应为 0640。');
+}
+
+function assertRejectsRelativeAndRootPaths() {
+  const fixture = prepareFixture('reject-paths');
+  const relative = runRaw([
+    '--source-cert-file',
+    'relative/fullchain.pem',
+    '--source-key-file',
+    fixture.sourceKey,
+    '--target-dir',
+    fixture.targetDir,
+  ]);
+  assertNonZero(relative, '相对源证书路径必须失败。');
+  assertIncludes(
+    `${relative.stdout}\n${relative.stderr}`,
+    '--source-cert-file 必须是绝对路径',
+    '相对路径必须给出明确错误。',
+  );
+
+  const root = runRaw([
+    '--source-cert-file',
+    fixture.sourceCert,
+    '--source-key-file',
+    fixture.sourceKey,
+    '--target-dir',
+    '/',
+  ]);
+  assertNonZero(root, 'target-dir 指向文件系统根目录必须失败。');
+  assertIncludes(
+    `${root.stdout}\n${root.stderr}`,
+    '--target-dir 不能是文件系统根目录',
+    '根目录目标必须给出明确错误。',
+  );
+}
+
+function assertRejectsControlCharactersBeforeApply() {
+  const fixture = prepareFixture('reject-control');
+  const result = runRaw([
+    '--source-cert-file',
+    `${fixture.sourceCert}\n--apply`,
+    '--source-key-file',
+    fixture.sourceKey,
+    '--target-dir',
+    fixture.targetDir,
+  ]);
+  assertNonZero(result, '带换行的源证书路径必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--source-cert-file 不能包含换行或 NUL 字符',
+    '控制字符路径必须给出明确错误。',
+  );
+  if (existsSync(fixture.targetCert) || existsSync(fixture.targetKey)) {
+    failures.push('控制字符参数失败时不应写入目标证书。');
+  }
+}
+
+function assertRejectsSymlinkTargetDirectory() {
+  const fixture = prepareFixture('reject-target-dir-symlink');
+  const realTarget = path.join(fixture.root, 'real-target');
+  mkdirSync(realTarget, { recursive: true });
+  rmSync(fixture.targetDir, { recursive: true, force: true });
+  symlinkSync(realTarget, fixture.targetDir);
+  const result = runSync(fixture, []);
+  assertNonZero(result, 'target-dir 是 symlink 时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--target-dir 已存在路径不能包含符号链接',
+    'target-dir symlink 必须给出明确错误。',
+  );
+}
+
+function assertRejectsSymlinkTargetFiles() {
+  const fixture = prepareFixture('reject-target-file-symlink');
+  mkdirSync(fixture.targetDir, { recursive: true });
+  const outside = path.join(fixture.root, 'outside-fullchain.pem');
+  writeFileSync(outside, 'outside\n', 'utf8');
+  symlinkSync(outside, fixture.targetCert);
+  const result = runSync(fixture, []);
+  assertNonZero(result, '目标证书是 symlink 时必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '目标 fullchain.pem 不能是符号链接',
+    '目标文件 symlink 必须给出明确错误。',
+  );
+}
+
+function assertRejectsWorldReadableModes() {
+  const fixture = prepareFixture('reject-world-readable-mode');
+  const result = runSync(fixture, ['--file-mode', '0644']);
+  assertNonZero(result, 'world-readable file mode 必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--file-mode 不能允许 other 读取证书或私钥',
+    'world-readable file mode 必须给出明确错误。',
+  );
+}
+
+function prepareFixture(name, options = {}) {
+  const root = path.join(tmpRoot, name);
+  const archiveDir = path.join(root, 'archive');
+  const liveDir = path.join(root, 'live');
+  const targetDir = path.join(root, 'target');
+  mkdirSync(archiveDir, { recursive: true });
+  mkdirSync(liveDir, { recursive: true });
+  writeFileSync(path.join(archiveDir, 'fullchain1.pem'), 'fixture fullchain\n', 'utf8');
+  writeFileSync(path.join(archiveDir, 'privkey1.pem'), 'fixture private key\n', 'utf8');
+
+  const symlinkSources = options.symlinkSources !== false;
+  const sourceCert = symlinkSources
+    ? path.join(liveDir, 'fullchain.pem')
+    : path.join(archiveDir, 'fullchain1.pem');
+  const sourceKey = symlinkSources
+    ? path.join(liveDir, 'privkey.pem')
+    : path.join(archiveDir, 'privkey1.pem');
+  if (symlinkSources) {
+    symlinkSync('../archive/fullchain1.pem', sourceCert);
+    symlinkSync('../archive/privkey1.pem', sourceKey);
+  }
+
+  return {
+    root,
+    sourceCert,
+    sourceKey,
+    targetDir,
+    targetCert: path.join(targetDir, 'fullchain.pem'),
+    targetKey: path.join(targetDir, 'privkey.pem'),
+  };
+}
+
+function runSync(fixture, args = [], options = {}) {
+  return runRaw([
+    '--source-cert-file',
+    fixture.sourceCert,
+    '--source-key-file',
+    fixture.sourceKey,
+    '--target-dir',
+    fixture.targetDir,
+    '--service-user',
+    options.serviceUser || `#${process.getuid?.() ?? 0}`,
+    '--service-group',
+    options.serviceGroup || `#${process.getgid?.() ?? 0}`,
+    '--target-user',
+    options.targetUser || `#${process.getuid?.() ?? 0}`,
+    '--json',
+    ...args,
+  ]);
+}
+
+function runRaw(args) {
+  return spawnSync('node', [SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    failures.push(`${label} 不是合法 JSON: ${error.message}\n${text}`);
+    return {};
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  if ((result.status ?? 0) !== expected) {
+    failures.push(
+      `${reason} 实际退出码 ${result.status}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertNonZero(result, reason) {
+  if ((result.status ?? 0) === 0) {
+    failures.push(`${reason}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  }
+}
+
+function assertIncludes(value, expected, reason) {
+  if (!String(value).includes(expected)) {
+    failures.push(`${reason} 缺少: ${expected}`);
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 实际 ${JSON.stringify(actual)}，预期 ${JSON.stringify(expected)}`);
+  }
+}
+
+function assertFileContent(filePath, expected) {
+  if (!existsSync(filePath)) {
+    failures.push(`缺少文件: ${filePath}`);
+    return;
+  }
+  const actual = readFileSync(filePath, 'utf8');
+  if (actual !== expected) {
+    failures.push(`${filePath} 内容不符合预期。`);
+  }
+}
+
+function assertMode(filePath, expected, reason) {
+  const mode = statSync(filePath).mode & 0o777;
+  if (mode !== expected) {
+    failures.push(`${reason} 实际 0${mode.toString(8)}，预期 0${expected.toString(8)}。`);
+  }
+}
diff --git a/scripts/check-production-api-deploy.mjs b/scripts/check-production-api-deploy.mjs
new file mode 100644
index 000000000..3d6d5cc7a
--- /dev/null
+++ b/scripts/check-production-api-deploy.mjs
@@ -0,0 +1,1612 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-production-api-deploy-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:production-api-deploy] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:production-api-deploy] OK');
+
+function main() {
+  assertDeployCopiesPingoraDirectReleaseDependencies();
+  assertDeployRestartsActivePingoraWhenArtifactIncluded();
+  assertDeployStartsInactivePingoraWhenArtifactIncluded();
+  assertDeployRejectsPingoraDirectEntryWhenArtifactIncluded();
+  assertDeployRejectsPingoraPublicListenWhenArtifactIncluded();
+  assertDeployRejectsPingoraArtifactMissingManifestEntry();
+  assertMissingReleaseManifestFails();
+  assertReleaseManifestMissingApiArtifactFails();
+  assertDeployRejectsDotVersion();
+  assertDeployRejectsDotDotVersion();
+  assertDeployRejectsVersionStartingWithDot();
+  assertDeployRejectsExistingReleaseDirectory();
+  assertDeployRejectsDirectoryCurrentLink();
+  assertDeployRejectsRelativeReleaseRoot();
+  assertDeployRejectsRelativeCurrentLink();
+  assertDeployRejectsRelativeApiEnvFile();
+  assertDeployCleansStagingReleaseOnFailure();
+  assertDeployRejectsFinalReleaseRaceAndCleansStaging();
+  assertMissingBackupScriptFails();
+  assertMissingHealthPatrolScriptFails();
+  assertMissingPingoraCurrentReleaseAuditFails();
+  assertMissingPingoraDirectRehearsalStatusFails();
+  assertMissingPingoraCutoverStatusSnapshotFails();
+  assertMissingPingoraCutoverEvidenceBundleFails();
+  assertMissingPingoraCutoverCommandEvidenceFails();
+  assertMissingPingoraCutoverEvidenceVerifyFails();
+  assertMissingPingoraCutoverEvidenceAuditFails();
+  assertMissingHealthPatrolEnvCheckFails();
+  assertMissingPingoraReleaseReadinessFails();
+  assertMissingPingoraRealpathCanaryEnableFails();
+  assertMissingPingoraRealpathCanaryDisableFails();
+  assertMissingPingoraHealthPatrolEnvSwitchFails();
+  assertMissingPingoraGatewayEnvShadowSwitchFails();
+  assertMissingPingoraTlsCertSyncFails();
+  assertMissingEnvExamplesFails();
+  assertMissingPingoraDirectCheckFails();
+  assertMissingPingoraCanaryLiveFails();
+  assertMissingPingoraCanaryAccessLogParityFails();
+}
+
+function assertDeployCopiesPingoraDirectReleaseDependencies() {
+  const fixture = prepareFixture('with-direct-checks');
+  const result = runDeploy(fixture);
+
+  assertStatus(result, 0, '完整 fixture 应部署成功。');
+  if (result.status !== 0) {
+    return;
+  }
+  assertIncludes(
+    result.stdout,
+    '[production-api-deploy] 完成:',
+    '部署成功时必须输出完成信息。',
+  );
+
+  const releaseDir = path.join(fixture.releaseRoot, fixture.version);
+  const currentTarget = readlinkSync(fixture.currentLink);
+  if (currentTarget !== releaseDir) {
+    failures.push(
+      `current link 应指向新 release。实际 ${currentTarget}，预期 ${releaseDir}`,
+    );
+  }
+
+  assertFileExists(
+    path.join(releaseDir, 'scripts/deploy/pingora-direct-enable.sh'),
+    'current release 必须包含 Pingora 直连启用脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/deploy/pingora-direct-rollback.sh'),
+    'current release 必须包含 Pingora 直连回退脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/deploy/pingora-realpath-canary-enable.sh'),
+    'current release 必须包含 Pingora realpath canary 启用脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/deploy/pingora-realpath-canary-disable.sh'),
+    'current release 必须包含 Pingora realpath canary 关闭脚本。',
+  );
+  assertFileExists(
+    path.join(
+      releaseDir,
+      'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    ),
+    'current release 必须包含 Pingora health patrol env 切换脚本。',
+  );
+  assertFileExists(
+    path.join(
+      releaseDir,
+      'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    ),
+    'current release 必须包含 Pingora gateway env shadow 切换脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/deploy/pingora-tls-cert-sync.mjs'),
+    'current release 必须包含 Pingora TLS 证书同步脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/check-pingora-direct-preflight.mjs'),
+    'current release 必须包含 Pingora 直连预检脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/check-production-health-patrol-env.mjs'),
+    'current release 必须包含健康巡检 env 复核脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/check-pingora-release-readiness.mjs'),
+    'current release 必须包含 Pingora release readiness 聚合门禁脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/ops/pingora-current-release-audit.mjs'),
+    'current release 必须包含 Pingora current release 自审脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/ops/pingora-direct-rehearsal-status.mjs'),
+    'current release 必须包含 Pingora 直连彩排状态脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/ops/pingora-cutover-status-snapshot.mjs'),
+    'current release 必须包含 Pingora 直连切换状态快照脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/ops/pingora-cutover-evidence-bundle.mjs'),
+    'current release 必须包含 Pingora 直连切换证据包脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/ops/pingora-cutover-command-evidence.mjs'),
+    'current release 必须包含 Pingora 直连切换命令证据脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/ops/pingora-cutover-evidence-verify.mjs'),
+    'current release 必须包含 Pingora 直连切换证据验真脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/ops/pingora-cutover-evidence-audit.mjs'),
+    'current release 必须包含 Pingora 直连切换证据根目录审计脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/check-pingora-direct-live.mjs'),
+    'current release 必须包含 Pingora 直连 live smoke 脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/check-pingora-canary-live.mjs'),
+    'current release 必须包含 Pingora canary live smoke 脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'scripts/check-pingora-canary-access-log-parity.mjs'),
+    'current release 必须包含 Pingora canary access log 对账脚本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'release-manifest.api-server.json'),
+    'current release 必须包含 API release manifest 副本。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'api-server.sha256'),
+    'current release 必须包含 api-server checksum，供随包 current release 自审校验。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'deploy/systemd/genarrative-pingora-gateway.service'),
+    'current release 必须包含 systemd 主 service 模板。',
+  );
+  assertFileExists(
+    path.join(
+      releaseDir,
+      'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    ),
+    'current release 必须包含 Pingora 直连 drop-in 模板。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'deploy/pingora/pingora-gateway.env.example'),
+    'current release 必须包含 Pingora env 示例。',
+  );
+  assertFileExists(
+    path.join(
+      releaseDir,
+      'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    ),
+    'current release 必须包含 Pingora 真实路径 canary Nginx snippet。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'deploy/env/health-patrol.env.example'),
+    'current release 必须包含健康巡检 env 示例。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'deploy/env/pingora-direct-live.env.example'),
+    'current release 必须包含 Pingora direct live env 示例。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'deploy/env/pingora-canary-live.env.example'),
+    'current release 必须包含 Pingora canary live env 示例。',
+  );
+  assertPingoraEnvProductionDefaults(
+    path.join(releaseDir, 'deploy/pingora/pingora-gateway.env.example'),
+    'current release 内 Pingora env 示例',
+  );
+
+  const copiedPreflight = readFileSync(
+    path.join(releaseDir, 'scripts/check-pingora-direct-preflight.mjs'),
+    'utf8',
+  );
+  assertIncludes(
+    copiedPreflight,
+    'deploy/pingora/pingora-gateway.env.example',
+    '复制后的 preflight 脚本必须仍能从 release root 推导 Pingora 配置。',
+  );
+
+  const apiEnv = readFileSync(fixture.apiEnvFile, 'utf8');
+  assertIncludes(
+    apiEnv,
+    'GENARRATIVE_SPACETIME_DATABASE=genarrative-prod',
+    '部署脚本必须写入 SpacetimeDB database。',
+  );
+  assertIncludes(
+    apiEnv,
+    'GENARRATIVE_SPACETIME_SERVER_URL=http://127.0.0.1:3101',
+    '部署脚本必须写入 SpacetimeDB server URL。',
+  );
+
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  assertIncludes(
+    commandsLog,
+    'systemctl restart genarrative-api.service',
+    '部署脚本必须重启 API service。',
+  );
+  assertIncludes(
+    commandsLog,
+    'curl -fsS http://127.0.0.1:18082/readyz',
+    '部署脚本必须执行 readiness curl。',
+  );
+
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('部署成功后应退出维护模式。');
+  }
+}
+
+function assertDeployRestartsActivePingoraWhenArtifactIncluded() {
+  const fixture = prepareFixture('with-active-pingora-artifact');
+  addPingoraGatewayArtifact(fixture);
+  const result = runDeploy(fixture);
+
+  assertStatus(
+    result,
+    0,
+    '包含 Pingora 且 shadow service active 时应部署成功。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+
+  const releaseDir = path.join(fixture.releaseRoot, fixture.version);
+  assertFileExists(
+    path.join(releaseDir, 'pingora-gateway'),
+    '包含 Pingora 的发布包部署后 current release 必须包含网关二进制。',
+  );
+  assertFileExists(
+    path.join(releaseDir, 'pingora-gateway.sha256'),
+    '包含 Pingora 的发布包部署后 current release 必须包含网关 checksum。',
+  );
+
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  assertIncludes(
+    commandsLog,
+    'systemctl cat genarrative-pingora-gateway.service',
+    '部署脚本看到 Pingora 产物后必须先读取 systemd 最终配置。',
+  );
+  assertIncludes(
+    commandsLog,
+    'systemctl restart genarrative-pingora-gateway.service',
+    'Pingora shadow service 已 active 时必须随 current release 切换 restart。',
+  );
+  assertIncludes(
+    result.stdout,
+    '发布包包含 Pingora，启动或重启 shadow 影子服务',
+    'Pingora shadow service 自动重启时必须输出明确提示。',
+  );
+}
+
+function assertDeployStartsInactivePingoraWhenArtifactIncluded() {
+  const fixture = prepareFixture('with-inactive-pingora-artifact');
+  addPingoraGatewayArtifact(fixture);
+  const result = runDeploy(fixture, { pingoraActive: false });
+
+  assertStatus(
+    result,
+    0,
+    '包含 Pingora 且 shadow service inactive 但仍是安全 shadow 配置时应部署成功。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  assertIncludes(
+    commandsLog,
+    'systemctl cat genarrative-pingora-gateway.service',
+    '部署脚本看到 Pingora 产物后必须先读取 systemd 最终配置。',
+  );
+  assertIncludes(
+    commandsLog,
+    'systemctl restart genarrative-pingora-gateway.service',
+    'Pingora shadow service inactive 且 shadow 配置安全时必须随 current release 启动。',
+  );
+  assertIncludes(
+    commandsLog,
+    'systemctl is-active --quiet genarrative-pingora-gateway.service',
+    '启动或重启 Pingora shadow 后必须复核 active。',
+  );
+  assertIncludes(
+    result.stdout,
+    '发布包包含 Pingora，启动或重启 shadow 影子服务',
+    'Pingora shadow service 自动启动时必须输出明确提示。',
+  );
+}
+
+function assertDeployRejectsPingoraDirectEntryWhenArtifactIncluded() {
+  const fixture = prepareFixture('with-direct-entry-pingora-artifact');
+  addPingoraGatewayArtifact(fixture);
+  const result = runDeploy(fixture, { pingoraDirectEntry: true });
+
+  if (result.status === 0) {
+    failures.push('包含 Pingora 但 systemd 已启用 direct-entry capability 时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'Pingora systemd 已包含 CAP_NET_BIND_SERVICE',
+    'direct-entry capability 存在时必须给出明确错误。',
+  );
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  if (
+    commandsLog.includes(
+      'systemctl restart genarrative-pingora-gateway.service',
+    )
+  ) {
+    failures.push('direct-entry capability 存在时不能自动 restart Pingora。');
+  }
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('direct-entry capability 导致部署失败时必须保持维护模式。');
+  }
+  assertNoReleasePromoted(
+    fixture,
+    'direct-entry capability 导致部署失败时不能提升正式 release。',
+  );
+}
+
+function assertDeployRejectsPingoraPublicListenWhenArtifactIncluded() {
+  const fixture = prepareFixture('with-public-listen-pingora-artifact');
+  addPingoraGatewayArtifact(fixture);
+  writePingoraEnv(fixture, {
+    listen: '0.0.0.0:443',
+  });
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('包含 Pingora 但 env 已配置公网监听时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'Pingora 自动启动只允许 shadow 监听 127.0.0.1:18081',
+    '公网监听 env 存在时必须给出明确错误。',
+  );
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  if (
+    commandsLog.includes(
+      'systemctl restart genarrative-pingora-gateway.service',
+    )
+  ) {
+    failures.push('公网监听 env 存在时不能自动 restart Pingora。');
+  }
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('公网监听 env 导致部署失败时必须保持维护模式。');
+  }
+  assertNoReleasePromoted(
+    fixture,
+    '公网监听 env 导致部署失败时不能提升正式 release。',
+  );
+}
+
+function assertDeployRejectsPingoraArtifactMissingManifestEntry() {
+  const fixture = prepareFixture('pingora-artifact-missing-manifest-entry');
+  addPingoraGatewayArtifact(fixture, { registerInManifest: false });
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布包包含 Pingora 但 manifest 未登记时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'release-manifest.json 缺少 pingora-gateway artifact',
+    'manifest 未登记 Pingora 时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('manifest 未登记 Pingora 导致部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingReleaseManifestFails() {
+  const fixture = prepareFixture('missing-release-manifest');
+  rmSync(path.join(fixture.sourceDir, 'release-manifest.json'));
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 release-manifest.json 时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 release-manifest.json',
+    '缺少 release-manifest.json 时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('缺少 release-manifest.json 导致部署失败时必须保持维护模式。');
+  }
+}
+
+function assertReleaseManifestMissingApiArtifactFails() {
+  const fixture = prepareFixture('release-manifest-missing-api-artifact');
+  writeFileSync(
+    path.join(fixture.sourceDir, 'release-manifest.json'),
+    `${JSON.stringify({ version: fixture.version, artifacts: [] }, null, 2)}\n`,
+    'utf8',
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('release manifest 缺少 api-server artifact 时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'release-manifest.json 缺少 api-server artifact',
+    'manifest 缺少 api-server artifact 时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('manifest 缺少 api-server artifact 导致部署失败时必须保持维护模式。');
+  }
+}
+
+function assertDeployRejectsDotVersion() {
+  const fixture = prepareFixture('dot-version');
+  const result = runDeploy(fixture, { version: '.' });
+
+  if (result.status === 0) {
+    failures.push('--version=. 时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--version 必须以数字或字母开头',
+    '--version=. 时必须给出明确错误。',
+  );
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('--version=. 且未进入部署阶段时不应开启维护模式。');
+  }
+}
+
+function assertDeployRejectsDotDotVersion() {
+  const fixture = prepareFixture('dot-dot-version');
+  const result = runDeploy(fixture, { version: '..' });
+
+  if (result.status === 0) {
+    failures.push('--version=.. 时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--version 必须以数字或字母开头',
+    '--version=.. 时必须给出明确错误。',
+  );
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('--version=.. 且未进入部署阶段时不应开启维护模式。');
+  }
+}
+
+function assertDeployRejectsVersionStartingWithDot() {
+  const fixture = prepareFixture('dot-prefix-version');
+  const result = runDeploy(fixture, { version: '.hidden-release' });
+
+  if (result.status === 0) {
+    failures.push('--version 以点开头时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--version 必须以数字或字母开头',
+    '--version 以点开头时必须给出明确错误。',
+  );
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('--version 以点开头且未进入部署阶段时不应开启维护模式。');
+  }
+}
+
+function assertDeployRejectsExistingReleaseDirectory() {
+  const fixture = prepareFixture('existing-release-directory');
+  const releaseDir = path.join(fixture.releaseRoot, fixture.version);
+  mkdirSync(releaseDir, { recursive: true });
+  writeFileSync(path.join(releaseDir, 'old-file'), 'old\n', 'utf8');
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('目标 release 目录已存在时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '目标 release 已存在，拒绝覆盖或合并旧文件',
+    '目标 release 目录已存在时必须给出明确错误。',
+  );
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('目标 release 目录已存在且未进入部署阶段时不应开启维护模式。');
+  }
+  assertFileExists(
+    path.join(releaseDir, 'old-file'),
+    '拒绝覆盖既有 release 时必须保留原目录。',
+  );
+}
+
+function assertDeployRejectsDirectoryCurrentLink() {
+  const fixture = prepareFixture('directory-current-link');
+  mkdirSync(fixture.currentLink, { recursive: true });
+  writeFileSync(path.join(fixture.currentLink, 'old-file'), 'old\n', 'utf8');
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('current 路径已存在但不是符号链接时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    'current 链接路径已存在但不是符号链接，拒绝覆盖',
+    'current 路径不是符号链接时必须给出明确错误。',
+  );
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('current 路径不是符号链接且未进入部署阶段时不应开启维护模式。');
+  }
+  assertFileExists(
+    path.join(fixture.currentLink, 'old-file'),
+    '拒绝覆盖目录型 current 时必须保留原目录内容。',
+  );
+}
+
+function assertDeployRejectsRelativeReleaseRoot() {
+  const fixture = prepareFixture('relative-release-root');
+  const result = runDeploy(fixture, { releaseRoot: 'relative/releases' });
+
+  if (result.status === 0) {
+    failures.push('--release-root 使用相对路径时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--release-root 必须使用绝对路径',
+    '--release-root 使用相对路径时必须给出明确错误。',
+  );
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('--release-root 相对路径且未进入部署阶段时不应开启维护模式。');
+  }
+}
+
+function assertDeployRejectsRelativeCurrentLink() {
+  const fixture = prepareFixture('relative-current-link');
+  const result = runDeploy(fixture, { currentLink: 'relative/current' });
+
+  if (result.status === 0) {
+    failures.push('--current-link 使用相对路径时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--current-link 必须使用绝对路径',
+    '--current-link 使用相对路径时必须给出明确错误。',
+  );
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('--current-link 相对路径且未进入部署阶段时不应开启维护模式。');
+  }
+}
+
+function assertDeployRejectsRelativeApiEnvFile() {
+  const fixture = prepareFixture('relative-api-env-file');
+  const result = runDeploy(fixture, { apiEnvFile: 'relative/api-server.env' });
+
+  if (result.status === 0) {
+    failures.push('--api-env-file 使用相对路径时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '--api-env-file 必须使用绝对路径',
+    '--api-env-file 使用相对路径时必须给出明确错误。',
+  );
+  if (existsSync(fixture.maintenanceFile)) {
+    failures.push('--api-env-file 相对路径且未进入部署阶段时不应开启维护模式。');
+  }
+}
+
+function assertDeployCleansStagingReleaseOnFailure() {
+  const fixture = prepareFixture('cleans-staging-on-failure');
+  rmSync(path.join(fixture.sourceDir, 'scripts/database-backup-to-oss.mjs'));
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('缺少数据库备份脚本时部署必须失败。');
+  }
+  const releaseDir = path.join(fixture.releaseRoot, fixture.version);
+  if (existsSync(releaseDir)) {
+    failures.push('部署失败时不应留下正式 release 目录。');
+  }
+  const entries = existsSync(fixture.releaseRoot)
+    ? readDirNames(fixture.releaseRoot)
+    : [];
+  const stagingEntries = entries.filter((entry) =>
+    entry.includes(`${fixture.version}.staging`),
+  );
+  if (stagingEntries.length > 0) {
+    failures.push(`部署失败时不应留下 staging release: ${stagingEntries.join(', ')}`);
+  }
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertDeployRejectsFinalReleaseRaceAndCleansStaging() {
+  const fixture = prepareFixture('final-release-race');
+  const result = runDeploy(fixture, { createReleaseDuringCopy: true });
+
+  if (result.status === 0) {
+    failures.push('最终提升前目标 release 目录被外部创建时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '目标 release 在发布过程中出现，拒绝合并 staging',
+    '最终提升前目标 release 目录被外部创建时必须给出明确错误。',
+  );
+
+  const releaseDir = path.join(fixture.releaseRoot, fixture.version);
+  assertFileExists(
+    path.join(releaseDir, 'raced-file'),
+    '部署脚本拒绝竞态目标 release 时必须保留外部创建的目录。',
+  );
+  if (existsSync(path.join(releaseDir, 'api-server'))) {
+    failures.push('目标 release 竞态出现后不应把 staging 内容合并进去。');
+  }
+  const entries = existsSync(fixture.releaseRoot)
+    ? readDirNames(fixture.releaseRoot)
+    : [];
+  const stagingEntries = entries.filter((entry) =>
+    entry.includes(`${fixture.version}.staging`),
+  );
+  if (stagingEntries.length > 0) {
+    failures.push(`目标 release 竞态失败后不应留下 staging release: ${stagingEntries.join(', ')}`);
+  }
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('目标 release 竞态失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraDirectCheckFails() {
+  const fixture = prepareFixture('missing-direct-live');
+  rmSync(path.join(fixture.sourceDir, 'scripts/check-pingora-direct-live.mjs'));
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 direct live smoke 脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora 直连 live smoke 脚本',
+    '缺少 direct live smoke 脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraCanaryLiveFails() {
+  const fixture = prepareFixture('missing-canary-live');
+  rmSync(path.join(fixture.sourceDir, 'scripts/check-pingora-canary-live.mjs'));
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 canary live smoke 脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora canary live smoke 脚本',
+    '缺少 canary live smoke 脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraCanaryAccessLogParityFails() {
+  const fixture = prepareFixture('missing-canary-log-parity');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/check-pingora-canary-access-log-parity.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 canary access log 对账脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora canary access log 对账脚本',
+    '缺少 canary access log 对账脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingBackupScriptFails() {
+  const fixture = prepareFixture('missing-backup-script');
+  rmSync(path.join(fixture.sourceDir, 'scripts/database-backup-to-oss.mjs'));
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少数据库备份脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少数据库备份脚本',
+    '缺少数据库备份脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingHealthPatrolScriptFails() {
+  const fixture = prepareFixture('missing-health-patrol-script');
+  rmSync(
+    path.join(fixture.sourceDir, 'scripts/ops/production-health-patrol.mjs'),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少生产健康巡检脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少生产健康巡检脚本',
+    '缺少生产健康巡检脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraCurrentReleaseAuditFails() {
+  const fixture = prepareFixture('missing-pingora-current-release-audit');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/ops/pingora-current-release-audit.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora current release 自审脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora current release 自审脚本',
+    '缺少 Pingora current release 自审脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraDirectRehearsalStatusFails() {
+  const fixture = prepareFixture('missing-pingora-direct-rehearsal-status');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora 直连彩排状态脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora 直连彩排状态脚本',
+    '缺少 Pingora 直连彩排状态脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraCutoverStatusSnapshotFails() {
+  const fixture = prepareFixture('missing-pingora-cutover-status-snapshot');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora 直连切换状态快照脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora 直连切换状态快照脚本',
+    '缺少 Pingora 直连切换状态快照脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraCutoverEvidenceBundleFails() {
+  const fixture = prepareFixture('missing-pingora-cutover-evidence-bundle');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora 直连切换证据包脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora 直连切换证据包脚本',
+    '缺少 Pingora 直连切换证据包脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraCutoverCommandEvidenceFails() {
+  const fixture = prepareFixture('missing-pingora-cutover-command-evidence');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/ops/pingora-cutover-command-evidence.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora 直连切换命令证据脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora 直连切换命令证据脚本',
+    '缺少 Pingora 直连切换命令证据脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraCutoverEvidenceVerifyFails() {
+  const fixture = prepareFixture('missing-pingora-cutover-evidence-verify');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora 直连切换证据验真脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora 直连切换证据验真脚本',
+    '缺少 Pingora 直连切换证据验真脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraCutoverEvidenceAuditFails() {
+  const fixture = prepareFixture('missing-pingora-cutover-evidence-audit');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push(
+      '发布产物缺少 Pingora 直连切换证据根目录审计脚本时部署必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora 直连切换证据根目录审计脚本',
+    '缺少 Pingora 直连切换证据根目录审计脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingHealthPatrolEnvCheckFails() {
+  const fixture = prepareFixture('missing-health-patrol-env-check');
+  rmSync(
+    path.join(fixture.sourceDir, 'scripts/check-production-health-patrol-env.mjs'),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少生产健康巡检 env 复核脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少生产健康巡检 env 复核脚本',
+    '缺少生产健康巡检 env 复核脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraReleaseReadinessFails() {
+  const fixture = prepareFixture('missing-pingora-release-readiness');
+  rmSync(
+    path.join(fixture.sourceDir, 'scripts/check-pingora-release-readiness.mjs'),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push(
+      '发布产物缺少 Pingora release readiness 聚合门禁脚本时部署必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora release readiness 聚合门禁脚本',
+    '缺少 Pingora release readiness 聚合门禁脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraHealthPatrolEnvSwitchFails() {
+  const fixture = prepareFixture('missing-pingora-health-patrol-env-switch');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora health patrol env 切换脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora health patrol env 切换脚本',
+    '缺少 Pingora health patrol env 切换脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraGatewayEnvShadowSwitchFails() {
+  const fixture = prepareFixture('missing-pingora-gateway-env-shadow-switch');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push(
+      '发布产物缺少 Pingora gateway env shadow 切换脚本时部署必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora gateway env shadow 切换脚本',
+    '缺少 Pingora gateway env shadow 切换脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraRealpathCanaryEnableFails() {
+  const fixture = prepareFixture('missing-pingora-realpath-canary-enable');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/deploy/pingora-realpath-canary-enable.sh',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora realpath canary 启用脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora realpath canary 启用脚本',
+    '缺少 Pingora realpath canary 启用脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraRealpathCanaryDisableFails() {
+  const fixture = prepareFixture('missing-pingora-realpath-canary-disable');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/deploy/pingora-realpath-canary-disable.sh',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora realpath canary 关闭脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora realpath canary 关闭脚本',
+    '缺少 Pingora realpath canary 关闭脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingPingoraTlsCertSyncFails() {
+  const fixture = prepareFixture('missing-pingora-tls-cert-sync');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/deploy/pingora-tls-cert-sync.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少 Pingora TLS 证书同步脚本时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora TLS 证书同步脚本',
+    '缺少 Pingora TLS 证书同步脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function assertMissingEnvExamplesFails() {
+  const fixture = prepareFixture('missing-env-examples');
+  rmSync(path.join(fixture.sourceDir, 'deploy/env'), {
+    recursive: true,
+    force: true,
+  });
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push('发布产物缺少环境变量示例目录时部署必须失败。');
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少环境变量示例目录',
+    '缺少环境变量示例目录时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
+function prepareFixture(name) {
+  const root = path.join(tmpRoot, name);
+  const sourceDir = path.join(root, 'source');
+  const releaseRoot = path.join(root, 'releases');
+  const currentLink = path.join(root, 'current');
+  const apiEnvFile = path.join(root, 'etc', 'api-server.env');
+  const pingoraEnvFile = path.join(root, 'etc', 'pingora-gateway.env');
+  const maintenanceFile = path.join(root, 'maintenance', 'enabled');
+  const fakeBin = path.join(root, 'bin');
+  const commandsLog = path.join(root, 'commands.log');
+  const workerStateFile = path.join(root, 'worker-service-enabled');
+  const pingoraStateFile = path.join(root, 'pingora-service-active');
+  const version = `20260614-${name}`;
+
+  mkdirSync(sourceDir, { recursive: true });
+  mkdirSync(fakeBin, { recursive: true });
+  mkdirSync(path.dirname(apiEnvFile), { recursive: true });
+  mkdirSync(path.join(sourceDir, 'scripts/deploy'), { recursive: true });
+  mkdirSync(path.join(sourceDir, 'scripts/ops'), { recursive: true });
+  mkdirSync(path.join(sourceDir, 'deploy/systemd'), { recursive: true });
+  mkdirSync(path.join(sourceDir, 'deploy/pingora'), { recursive: true });
+  mkdirSync(path.join(sourceDir, 'deploy/env'), { recursive: true });
+  mkdirSync(path.join(sourceDir, 'deploy/nginx/snippets'), { recursive: true });
+
+  writeFileSync(
+    path.join(sourceDir, 'api-server'),
+    '#!/usr/bin/env bash\n',
+    'utf8',
+  );
+  writeFileSync(
+    apiEnvFile,
+    [
+      'GENARRATIVE_TRACKING_OUTBOX_ENABLED=false',
+      'GENARRATIVE_API_SHUTDOWN_OUTBOX_FLUSH_TIMEOUT_MS=5000',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writePingoraEnv({ pingoraEnvFile });
+  chmodExecutable(path.join(sourceDir, 'api-server'));
+  writeSha256(sourceDir, 'api-server');
+  writeFileSync(
+    path.join(sourceDir, 'release-manifest.json'),
+    `${JSON.stringify(
+      {
+        version,
+        artifacts: [
+          {
+            component: 'api-server',
+            path: 'api-server',
+            checksum_path: 'api-server.sha256',
+          },
+        ],
+      },
+      null,
+      2,
+    )}\n`,
+    'utf8',
+  );
+  writeFileSync(
+    path.join(sourceDir, 'scripts/database-backup-to-oss.mjs'),
+    'console.log("backup");\n',
+    'utf8',
+  );
+  writeFileSync(
+    path.join(sourceDir, 'scripts/ops/production-health-patrol.mjs'),
+    'console.log("patrol");\n',
+    'utf8',
+  );
+  copyFile(
+    'scripts/ops/pingora-current-release-audit.mjs',
+    path.join(sourceDir, 'scripts/ops/pingora-current-release-audit.mjs'),
+  );
+  copyFile(
+    'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    path.join(sourceDir, 'scripts/ops/pingora-direct-rehearsal-status.mjs'),
+  );
+  copyFile(
+    'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    path.join(sourceDir, 'scripts/ops/pingora-cutover-status-snapshot.mjs'),
+  );
+  copyFile(
+    'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    path.join(sourceDir, 'scripts/ops/pingora-cutover-evidence-bundle.mjs'),
+  );
+  copyFile(
+    'scripts/ops/pingora-cutover-command-evidence.mjs',
+    path.join(sourceDir, 'scripts/ops/pingora-cutover-command-evidence.mjs'),
+  );
+  copyFile(
+    'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    path.join(sourceDir, 'scripts/ops/pingora-cutover-evidence-verify.mjs'),
+  );
+  copyFile(
+    'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    path.join(sourceDir, 'scripts/ops/pingora-cutover-evidence-audit.mjs'),
+  );
+  copyFile(
+    'scripts/deploy/production-api-deploy.sh',
+    path.join(sourceDir, 'scripts/deploy/production-api-deploy.sh'),
+  );
+  copyFile(
+    'scripts/deploy/maintenance-on.sh',
+    path.join(sourceDir, 'scripts/deploy/maintenance-on.sh'),
+  );
+  copyFile(
+    'scripts/deploy/maintenance-off.sh',
+    path.join(sourceDir, 'scripts/deploy/maintenance-off.sh'),
+  );
+  copyFile(
+    'scripts/deploy/pingora-direct-enable.sh',
+    path.join(sourceDir, 'scripts/deploy/pingora-direct-enable.sh'),
+  );
+  copyFile(
+    'scripts/deploy/pingora-direct-rollback.sh',
+    path.join(sourceDir, 'scripts/deploy/pingora-direct-rollback.sh'),
+  );
+  copyFile(
+    'scripts/deploy/pingora-realpath-canary-enable.sh',
+    path.join(sourceDir, 'scripts/deploy/pingora-realpath-canary-enable.sh'),
+  );
+  copyFile(
+    'scripts/deploy/pingora-realpath-canary-disable.sh',
+    path.join(sourceDir, 'scripts/deploy/pingora-realpath-canary-disable.sh'),
+  );
+  copyFile(
+    'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    path.join(sourceDir, 'scripts/deploy/pingora-health-patrol-env-switch.mjs'),
+  );
+  copyFile(
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    path.join(sourceDir, 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs'),
+  );
+  copyFile(
+    'scripts/deploy/pingora-tls-cert-sync.mjs',
+    path.join(sourceDir, 'scripts/deploy/pingora-tls-cert-sync.mjs'),
+  );
+  copyFile(
+    'scripts/check-production-health-patrol-env.mjs',
+    path.join(sourceDir, 'scripts/check-production-health-patrol-env.mjs'),
+  );
+  copyFile(
+    'scripts/check-pingora-release-readiness.mjs',
+    path.join(sourceDir, 'scripts/check-pingora-release-readiness.mjs'),
+  );
+  copyFile(
+    'scripts/check-pingora-direct-preflight.mjs',
+    path.join(sourceDir, 'scripts/check-pingora-direct-preflight.mjs'),
+  );
+  copyFile(
+    'scripts/check-pingora-direct-live.mjs',
+    path.join(sourceDir, 'scripts/check-pingora-direct-live.mjs'),
+  );
+  copyFile(
+    'scripts/check-pingora-canary-live.mjs',
+    path.join(sourceDir, 'scripts/check-pingora-canary-live.mjs'),
+  );
+  copyFile(
+    'scripts/check-pingora-canary-access-log-parity.mjs',
+    path.join(sourceDir, 'scripts/check-pingora-canary-access-log-parity.mjs'),
+  );
+  copyFile(
+    'deploy/systemd/genarrative-pingora-gateway.service',
+    path.join(sourceDir, 'deploy/systemd/genarrative-pingora-gateway.service'),
+  );
+  copyFile(
+    'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    path.join(
+      sourceDir,
+      'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    ),
+  );
+  copyFile(
+    'deploy/pingora/pingora-gateway.env.example',
+    path.join(sourceDir, 'deploy/pingora/pingora-gateway.env.example'),
+  );
+  copyFile(
+    'deploy/env/health-patrol.env.example',
+    path.join(sourceDir, 'deploy/env/health-patrol.env.example'),
+  );
+  copyFile(
+    'deploy/env/pingora-direct-live.env.example',
+    path.join(sourceDir, 'deploy/env/pingora-direct-live.env.example'),
+  );
+  copyFile(
+    'deploy/env/pingora-canary-live.env.example',
+    path.join(sourceDir, 'deploy/env/pingora-canary-live.env.example'),
+  );
+  copyFile(
+    'deploy/nginx/snippets/genarrative-pingora-canary.conf',
+    path.join(
+      sourceDir,
+      'deploy/nginx/snippets/genarrative-pingora-canary.conf',
+    ),
+  );
+  copyFile(
+    'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    path.join(
+      sourceDir,
+      'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    ),
+  );
+  chmodExecutable(
+    path.join(sourceDir, 'scripts/deploy/production-api-deploy.sh'),
+  );
+  chmodExecutable(path.join(sourceDir, 'scripts/deploy/maintenance-on.sh'));
+  chmodExecutable(path.join(sourceDir, 'scripts/deploy/maintenance-off.sh'));
+
+  writeFileSync(
+    path.join(fakeBin, 'systemctl'),
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      `printf 'systemctl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      'worker_state_file="${FAKE_WORKER_STATE_FILE}"',
+      'pingora_state_file="${FAKE_PINGORA_STATE_FILE}"',
+      'if [[ "$1" == "cat" && "${2:-}" == "genarrative-pingora-gateway.service" ]]; then',
+      '  printf "[Service]\\n"',
+      '  printf "EnvironmentFile=%s\\n" "${FAKE_PINGORA_ENV_FILE}"',
+      '  printf "ExecStart=/opt/genarrative/current/pingora-gateway\\n"',
+      '  if [[ "${FAKE_PINGORA_DIRECT_ENTRY:-false}" == "true" ]]; then',
+      '    printf "AmbientCapabilities=CAP_NET_BIND_SERVICE\\n"',
+      '    printf "CapabilityBoundingSet=CAP_NET_BIND_SERVICE\\n"',
+      '  fi',
+      '  exit 0',
+      'fi',
+      'if [[ "$1" == "list-units" ]]; then',
+      '  pattern="${@: -1}"',
+      '  if [[ "${pattern}" == "genarrative-external-generation-worker@*.service" && -f "${worker_state_file}" ]]; then',
+      '    printf "genarrative-external-generation-worker@1.service loaded active running Genarrative external generation worker\\n"',
+      '  fi',
+      '  exit 0',
+      'fi',
+      'if [[ "$1 $2" == "enable --now" && "${3:-}" == "genarrative-external-generation-worker@1.service" ]]; then',
+      '  printf "enabled\\n" > "${worker_state_file}"',
+      '  exit 0',
+      'fi',
+      'if [[ "$1 $2 ${3:-}" == "is-active --quiet genarrative-pingora-gateway.service" ]]; then',
+      '  if [[ "${FAKE_PINGORA_ACTIVE:-true}" == "true" || -f "${pingora_state_file}" ]]; then',
+      '    exit 0',
+      '  fi',
+      '  exit 3',
+      'fi',
+      'if [[ "$1" == "restart" && "${2:-}" == "genarrative-pingora-gateway.service" ]]; then',
+      '  printf "active\\n" > "${pingora_state_file}"',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(fakeBin, 'curl'),
+    [
+      '#!/usr/bin/env bash',
+      `printf 'curl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(fakeBin, 'cp'),
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      '/usr/bin/cp "$@"',
+      'if [[ "${FAKE_CREATE_RELEASE_DURING_COPY:-false}" == "true" ]]; then',
+      '  marker="${FAKE_RELEASE_ROOT}/.${FAKE_RELEASE_VERSION}.race-created"',
+      '  if [[ ! -e "${marker}" ]]; then',
+      '    mkdir -p "${FAKE_RELEASE_ROOT}/${FAKE_RELEASE_VERSION}"',
+      '    printf "race\\n" > "${FAKE_RELEASE_ROOT}/${FAKE_RELEASE_VERSION}/raced-file"',
+      '    printf "created\\n" > "${marker}"',
+      '  fi',
+      'fi',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(path.join(fakeBin, 'systemctl'));
+  chmodExecutable(path.join(fakeBin, 'curl'));
+  chmodExecutable(path.join(fakeBin, 'cp'));
+
+  return {
+    root,
+    sourceDir,
+    releaseRoot,
+    currentLink,
+    apiEnvFile,
+    pingoraEnvFile,
+    maintenanceFile,
+    fakeBin,
+    commandsLog,
+    workerStateFile,
+    pingoraStateFile,
+    version,
+  };
+}
+
+function writePingoraEnv(fixture, options = {}) {
+  const filePath = fixture.pingoraEnvFile;
+  const lines = [
+    `GENARRATIVE_PINGORA_GATEWAY_LISTEN=${options.listen ?? '127.0.0.1:18081'}`,
+  ];
+  if (options.tlsListen) {
+    lines.push(`GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${options.tlsListen}`);
+  }
+  if (options.redirectListen) {
+    lines.push(
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${options.redirectListen}`,
+    );
+  }
+  writeFileSync(filePath, `${lines.join('\n')}\n`, 'utf8');
+}
+
+function addPingoraGatewayArtifact(fixture, options = {}) {
+  writeFileSync(
+    path.join(fixture.sourceDir, 'pingora-gateway'),
+    '#!/usr/bin/env bash\n',
+    'utf8',
+  );
+  chmodExecutable(path.join(fixture.sourceDir, 'pingora-gateway'));
+  writeSha256(fixture.sourceDir, 'pingora-gateway');
+  if (options.registerInManifest === false) {
+    return;
+  }
+  const manifestPath = path.join(fixture.sourceDir, 'release-manifest.json');
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  manifest.artifacts = Array.isArray(manifest.artifacts)
+    ? manifest.artifacts
+    : [];
+  manifest.artifacts.push({
+    component: 'pingora-gateway',
+    path: 'pingora-gateway',
+    checksum_path: 'pingora-gateway.sha256',
+  });
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+
+function runDeploy(fixture, options = {}) {
+  const deployScript = path.join(
+    fixture.sourceDir,
+    'scripts/deploy/production-api-deploy.sh',
+  );
+  return spawnSync(
+    'bash',
+    [
+      deployScript,
+      '--source-dir',
+      fixture.sourceDir,
+      '--version',
+      options.version ?? fixture.version,
+      '--release-root',
+      options.releaseRoot ?? fixture.releaseRoot,
+      '--current-link',
+      options.currentLink ?? fixture.currentLink,
+      '--service',
+      'genarrative-api.service',
+      '--health-url',
+      'http://127.0.0.1:18082/readyz',
+      '--api-env-file',
+      options.apiEnvFile ?? fixture.apiEnvFile,
+      '--database',
+      'genarrative-prod',
+      '--spacetime-server-url',
+      'http://127.0.0.1:3101',
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        PATH: `${fixture.fakeBin}:${process.env.PATH || ''}`,
+        GENARRATIVE_MAINTENANCE_FILE: fixture.maintenanceFile,
+        FAKE_PINGORA_ACTIVE: options.pingoraActive === false ? 'false' : 'true',
+        FAKE_PINGORA_DIRECT_ENTRY:
+          options.pingoraDirectEntry === true ? 'true' : 'false',
+        FAKE_PINGORA_ENV_FILE: fixture.pingoraEnvFile,
+        FAKE_PINGORA_STATE_FILE: fixture.pingoraStateFile,
+        FAKE_CREATE_RELEASE_DURING_COPY:
+          options.createReleaseDuringCopy === true ? 'true' : 'false',
+        FAKE_RELEASE_ROOT: fixture.releaseRoot,
+        FAKE_RELEASE_VERSION: fixture.version,
+        FAKE_WORKER_STATE_FILE: fixture.workerStateFile,
+      },
+    },
+  );
+}
+
+function copyFile(source, target) {
+  writeFileSync(target, readFileSync(source, 'utf8'), 'utf8');
+}
+
+function writeSha256(directory, fileName) {
+  const result = spawnSync('sha256sum', [fileName], {
+    cwd: directory,
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `sha256sum failed for ${fileName}`);
+  }
+  writeFileSync(
+    path.join(directory, `${fileName}.sha256`),
+    result.stdout,
+    'utf8',
+  );
+}
+
+function chmodExecutable(filePath) {
+  spawnSync('chmod', ['0755', filePath], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function assertFileExists(filePath, reason) {
+  if (!existsSync(filePath)) {
+    failures.push(`${reason} 缺少: ${filePath}`);
+  }
+}
+
+function assertNoReleasePromoted(fixture, reason) {
+  const releaseDir = path.join(fixture.releaseRoot, fixture.version);
+  if (existsSync(releaseDir)) {
+    failures.push(`${reason} 已存在: ${releaseDir}`);
+  }
+  if (existsSync(fixture.currentLink)) {
+    failures.push(`${reason} 不应切换 current: ${fixture.currentLink}`);
+  }
+}
+
+function readDirNames(directory) {
+  return spawnSync('find', [directory, '-maxdepth', '1', '-mindepth', '1', '-printf', '%f\n'], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  })
+    .stdout.split('\n')
+    .filter(Boolean);
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!content.includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
+
+function assertPingoraEnvProductionDefaults(filePath, label) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  const content = readFileSync(filePath, 'utf8');
+  const requiredLines = [
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip',
+      '压缩算法必须保持 gzip-only，避免 Brotli 在未验证前进入 current release。',
+    ],
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=false',
+      '公网直连默认不能信任客户端可伪造的 X-Forwarded-For。',
+    ],
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=false',
+      '前置代理信任确认开关必须默认关闭。',
+    ],
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true',
+      '接流保护必须默认开启。',
+    ],
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN=',
+      '内部探针 token 示例必须保持空值，避免 current release 夹带真实 token。',
+    ],
+  ];
+  for (const [line, reason] of requiredLines) {
+    assertIncludes(content, line, `${label} ${reason}`);
+  }
+}
diff --git a/scripts/check-production-api-release.mjs b/scripts/check-production-api-release.mjs
new file mode 100644
index 000000000..652f09a32
--- /dev/null
+++ b/scripts/check-production-api-release.mjs
@@ -0,0 +1,591 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const BUILD_SCRIPT = 'scripts/build-production-release.sh';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-production-api-release-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:production-api-release] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:production-api-release] OK');
+
+function main() {
+  assertApiReleaseContainsPingoraDirectDependencies();
+  assertApiReleaseCanIncludePingoraGatewayArtifact();
+}
+
+function assertApiReleaseContainsPingoraDirectDependencies() {
+  const fixture = prepareFixture('api-direct-dependencies');
+  const result = runBuild(fixture);
+  assertStatus(result, 0, 'API release build 烟测应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+
+  const releaseDir = path.join(process.cwd(), 'build', fixture.version);
+  try {
+    assertFileExists(
+      path.join(releaseDir, 'api-server'),
+      'API release 必须包含 api-server。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'api-server'),
+      'api-server 必须保留可执行权限。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'api-server.sha256'),
+      'API release 必须包含 api-server checksum。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/deploy/production-api-deploy.sh'),
+      'API release 必须包含随产物执行的 API deploy 脚本。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'scripts/deploy/production-api-deploy.sh'),
+      '随产物执行的 API deploy 脚本必须可执行。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/deploy/maintenance-on.sh'),
+      'API release 必须在 deploy 脚本同目录包含 maintenance-on.sh。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'scripts/deploy/maintenance-on.sh'),
+      'deploy 同目录 maintenance-on.sh 必须可执行。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/deploy/maintenance-off.sh'),
+      'API release 必须在 deploy 脚本同目录包含 maintenance-off.sh。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'scripts/deploy/maintenance-off.sh'),
+      'deploy 同目录 maintenance-off.sh 必须可执行。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/deploy/pingora-direct-enable.sh'),
+      'API release 必须包含 Pingora 直连启用脚本。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'scripts/deploy/pingora-direct-enable.sh'),
+      'Pingora 直连启用脚本必须可执行。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/deploy/pingora-direct-rollback.sh'),
+      'API release 必须包含 Pingora 直连回退脚本。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'scripts/deploy/pingora-direct-rollback.sh'),
+      'Pingora 直连回退脚本必须可执行。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/deploy/pingora-realpath-canary-enable.sh'),
+      'API release 必须包含 Pingora realpath canary 启用脚本。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'scripts/deploy/pingora-realpath-canary-enable.sh'),
+      'Pingora realpath canary 启用脚本必须可执行。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/deploy/pingora-realpath-canary-disable.sh'),
+      'API release 必须包含 Pingora realpath canary 关闭脚本。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'scripts/deploy/pingora-realpath-canary-disable.sh'),
+      'Pingora realpath canary 关闭脚本必须可执行。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+      ),
+      'API release 必须包含 Pingora health patrol env 切换脚本。',
+    );
+    assertExecutable(
+      path.join(
+        releaseDir,
+        'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+      ),
+      'Pingora health patrol env 切换脚本必须可执行。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+      ),
+      'API release 必须包含 Pingora gateway env shadow 切换脚本。',
+    );
+    assertExecutable(
+      path.join(
+        releaseDir,
+        'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+      ),
+      'Pingora gateway env shadow 切换脚本必须可执行。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/deploy/pingora-tls-cert-sync.mjs'),
+      'API release 必须包含 Pingora TLS 证书同步脚本。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'scripts/deploy/pingora-tls-cert-sync.mjs'),
+      'Pingora TLS 证书同步脚本必须可执行。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/check-production-health-patrol-env.mjs'),
+      'API release 必须包含健康巡检 env 复核脚本。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/check-pingora-release-readiness.mjs'),
+      'API release 必须包含 Pingora release readiness 聚合门禁脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/ops/pingora-current-release-audit.mjs',
+      ),
+      'API release 必须包含 Pingora current release 自审脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/ops/pingora-direct-rehearsal-status.mjs',
+      ),
+      'API release 必须包含 Pingora 直连彩排状态脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/ops/pingora-cutover-status-snapshot.mjs',
+      ),
+      'API release 必须包含 Pingora 直连切换状态快照脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+      ),
+      'API release 必须包含 Pingora 直连切换证据包脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/ops/pingora-cutover-command-evidence.mjs',
+      ),
+      'API release 必须包含 Pingora 直连切换命令证据脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/ops/pingora-cutover-evidence-verify.mjs',
+      ),
+      'API release 必须包含 Pingora 直连切换证据验真脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/ops/pingora-cutover-evidence-audit.mjs',
+      ),
+      'API release 必须包含 Pingora 直连切换证据根目录审计脚本。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/check-pingora-direct-preflight.mjs'),
+      'API release 必须包含 Pingora 直连预检脚本。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/check-pingora-direct-live.mjs'),
+      'API release 必须包含 Pingora 直连 live smoke 脚本。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'scripts/check-pingora-canary-live.mjs'),
+      'API release 必须包含 Pingora canary live smoke 脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/check-pingora-canary-access-log-parity.mjs',
+      ),
+      'API release 必须包含 Pingora canary access log 对账脚本。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'deploy/systemd/genarrative-pingora-gateway.service',
+      ),
+      'API release 必须包含 Pingora systemd 主 service 模板。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+      ),
+      'API release 必须包含 Pingora 直连 drop-in 模板。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'deploy/pingora/pingora-gateway.env.example'),
+      'API release 必须包含 Pingora env 示例。',
+    );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+      ),
+      'API release 必须包含 Pingora 真实路径 canary Nginx snippet。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'deploy/env/health-patrol.env.example'),
+      'API release 必须包含健康巡检 env 示例。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'deploy/env/pingora-direct-live.env.example'),
+      'API release 必须包含 Pingora direct live env 示例。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'deploy/env/pingora-canary-live.env.example'),
+      'API release 必须包含 Pingora canary live env 示例。',
+    );
+    assertPingoraEnvProductionDefaults(
+      path.join(releaseDir, 'deploy/pingora/pingora-gateway.env.example'),
+      'API release 内 Pingora env 示例',
+    );
+
+    const manifest = readJson(path.join(releaseDir, 'release-manifest.json'));
+    if (manifest.component_type !== 'api-server') {
+      failures.push(
+        `release manifest component_type 应为 api-server，实际 ${manifest.component_type}`,
+      );
+    }
+    if (!manifest.artifacts?.some((item) => item.path === 'api-server')) {
+      failures.push('release manifest 必须登记 api-server artifact。');
+    }
+    if (manifest.artifacts?.some((item) => item.path === 'pingora-gateway')) {
+      failures.push('默认 API release 不应登记 pingora-gateway artifact。');
+    }
+
+    const releaseReadme = readFileSync(
+      path.join(releaseDir, 'README.md'),
+      'utf8',
+    );
+    assertIncludes(
+      releaseReadme,
+      'Pingora release readiness 聚合门禁、直连启用 / 回退',
+      'API release README 必须说明随包携带 Pingora 直连脚本。',
+    );
+    assertIncludes(
+      releaseReadme,
+      'realpath canary 启用 / 关闭',
+      'API release README 必须说明随包携带 Pingora realpath canary 启停脚本。',
+    );
+    assertIncludes(
+      releaseReadme,
+      'health patrol env 切换 / TLS 证书同步 / 预检 / direct live smoke / canary live smoke / canary access log 对账 / current release 自审 / 直连彩排状态',
+      'API release README 必须说明随包携带 Pingora 运行态复核脚本。',
+    );
+    assertIncludes(
+      releaseReadme,
+      '状态快照 / 证据包 / 命令证据 / 证据验真 / 证据根目录审计脚本',
+      'API release README 必须说明随包携带 Pingora 切换证据脚本。',
+    );
+    for (const executableArg of requiredCutoverAuditExecutableArgs()) {
+      assertIncludes(
+        releaseReadme,
+        `--require-command-executable ${executableArg}`,
+        'API release README 必须记录最终证据根目录总审计绑定 current release 切换脚本。',
+      );
+    }
+    assertIncludes(
+      releaseReadme,
+      'scripts/deploy/production-api-deploy.sh',
+      'API release README 必须说明随包携带 API Deploy 执行入口。',
+    );
+    assertIncludes(
+      releaseReadme,
+      '同目录的 `maintenance-on.sh` / `maintenance-off.sh` 必须来自同一发布包',
+      'API release README 必须说明 deploy 同目录维护脚本来自同一发布包。',
+    );
+    assertReleaseReadinessCutoverPlanBindsCurrentExecutables(releaseDir);
+  } finally {
+    rmSync(releaseDir, { recursive: true, force: true });
+  }
+}
+
+function assertApiReleaseCanIncludePingoraGatewayArtifact() {
+  const fixture = prepareFixture('api-with-pingora-artifact', {
+    includePingoraGateway: true,
+  });
+  const result = runBuild(fixture, {
+    includePingoraGateway: true,
+    skipPingoraGatewayBuild: true,
+  });
+  assertStatus(result, 0, '包含 Pingora 的 API release build 烟测应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+
+  const releaseDir = path.join(process.cwd(), 'build', fixture.version);
+  try {
+    assertFileExists(
+      path.join(releaseDir, 'pingora-gateway'),
+      '显式 include Pingora 时 API release 必须包含 pingora-gateway。',
+    );
+    assertExecutable(
+      path.join(releaseDir, 'pingora-gateway'),
+      'pingora-gateway 必须保留可执行权限。',
+    );
+    assertFileExists(
+      path.join(releaseDir, 'pingora-gateway.sha256'),
+      '显式 include Pingora 时 API release 必须包含 pingora-gateway checksum。',
+    );
+
+    const manifest = readJson(path.join(releaseDir, 'release-manifest.json'));
+    if (!manifest.artifacts?.some((item) => item.path === 'pingora-gateway')) {
+      failures.push(
+        '显式 include Pingora 时 release manifest 必须登记 pingora-gateway artifact。',
+      );
+    }
+  } finally {
+    rmSync(releaseDir, { recursive: true, force: true });
+  }
+}
+
+function prepareFixture(name, options = {}) {
+  const cargoTargetDir = path.join(tmpRoot, name, 'cargo-target');
+  const binaryDir = path.join(
+    cargoTargetDir,
+    'x86_64-unknown-linux-gnu/release',
+  );
+  const version = `check-production-api-release-${process.pid}-${Date.now()}`;
+  mkdirSync(binaryDir, { recursive: true });
+  const apiBinary = path.join(binaryDir, 'api-server');
+  writeFileSync(apiBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+  spawnSync('chmod', ['0755', apiBinary], { encoding: 'utf8' });
+  if (options.includePingoraGateway) {
+    const pingoraBinary = path.join(binaryDir, 'pingora-gateway');
+    writeFileSync(pingoraBinary, '#!/usr/bin/env bash\nexit 0\n', 'utf8');
+    spawnSync('chmod', ['0755', pingoraBinary], { encoding: 'utf8' });
+  }
+  return { cargoTargetDir, version };
+}
+
+function runBuild(fixture, options = {}) {
+  const args = [
+    BUILD_SCRIPT,
+    '--component',
+    'api-server',
+    '--name',
+    fixture.version,
+    '--skip-api-build',
+  ];
+  if (options.includePingoraGateway) {
+    args.push('--include-pingora-gateway');
+  }
+  if (options.skipPingoraGatewayBuild) {
+    args.push('--skip-pingora-gateway-build');
+  }
+
+  return spawnSync('bash', args, {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      CARGO_TARGET_DIR: fixture.cargoTargetDir,
+      SOURCE_BRANCH: 'test-branch',
+      SOURCE_COMMIT: 'test-commit',
+    },
+  });
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    failures.push(`${filePath} 不是合法 JSON: ${error.message}`);
+    return {};
+  }
+}
+
+function assertFileExists(filePath, reason) {
+  if (!existsSync(filePath)) {
+    failures.push(`${reason} 缺少: ${filePath}`);
+  }
+}
+
+function assertExecutable(filePath, reason) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  if ((statSync(filePath).mode & 0o111) === 0) {
+    failures.push(`${reason} 文件不可执行: ${filePath}`);
+  }
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!content.includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
+
+function assertReleaseReadinessCutoverPlanBindsCurrentExecutables(releaseDir) {
+  const readinessScript = path.join(
+    releaseDir,
+    'scripts/check-pingora-release-readiness.mjs',
+  );
+  const result = spawnSync(
+    'node',
+    [
+      readinessScript,
+      '--dry-run-cutover',
+      '--require-direct',
+      '--direct-https-base-url',
+      'https://127.0.0.1',
+      '--direct-http-base-url',
+      'http://127.0.0.1',
+      '--direct-host',
+      'example.com',
+      '--direct-redirect-host',
+      'example.com',
+      '--direct-spacetime-database',
+      'genarrative-prod',
+      '--direct-pingora-access-log',
+      '/var/log/genarrative/pingora-gateway.access.log',
+      '--direct-health-patrol-env-file',
+      '/etc/genarrative/health-patrol.env',
+      '--direct-preflight-env-file',
+      '/etc/genarrative/pingora-gateway.env',
+      '--direct-preflight-systemd',
+      '--direct-preflight-check-cert-readable',
+      '--direct-preflight-check-service-env-file',
+      '--direct-preflight-check-service-user-cert-readable',
+      '--direct-preflight-check-service-binary-executable',
+      '--direct-preflight-check-ports-free',
+      '--cutover-run-id',
+      'check-production-api-release',
+      '--rollback-nginx-smoke-url',
+      'https://example.com/',
+      '--rollback-nginx-smoke-expect-body',
+      '<!doctype html>',
+      '--rollback-health-patrol-public-base-url',
+      'http://127.0.0.1',
+    ],
+    {
+      cwd: releaseDir,
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        GENARRATIVE_PINGORA_CUTOVER_RELEASE_ROOT: '',
+      },
+    },
+  );
+  assertStatus(
+    result,
+    0,
+    'API release 随包 readiness 脚本必须能生成直连切换 dry-run runbook。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+
+  let plan;
+  try {
+    plan = JSON.parse(result.stdout);
+  } catch (error) {
+    failures.push(
+      `API release 随包 readiness dry-run cutover 输出不是合法 JSON: ${error.message}`,
+    );
+    return;
+  }
+
+  const auditStep = Array.isArray(plan)
+    ? plan.find((step) => step?.name === '切换证据根目录三阶段总审计')
+    : null;
+  if (!auditStep) {
+    failures.push(
+      'API release 随包 readiness dry-run cutover 必须包含切换证据根目录三阶段总审计步骤。',
+    );
+    return;
+  }
+
+  if (!auditStep.args?.includes('--require-command-executable')) {
+    failures.push(
+      'API release 随包 readiness 总审计步骤必须携带 --require-command-executable。',
+    );
+  }
+  for (const executableArg of requiredCutoverAuditExecutableArgs()) {
+    if (!auditStep.args?.includes(executableArg)) {
+      failures.push(
+        `API release 随包 readiness 总审计步骤必须绑定 current release 切换脚本，缺少: ${executableArg}`,
+      );
+    }
+  }
+}
+
+function requiredCutoverAuditExecutableArgs() {
+  return [
+    'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+    'rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
+  ];
+}
+
+function assertPingoraEnvProductionDefaults(filePath, label) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  const content = readFileSync(filePath, 'utf8');
+  const requiredLines = [
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip',
+      '压缩算法必须保持 gzip-only，避免 Brotli 在未验证前进入直连发布包。',
+    ],
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=false',
+      '公网直连默认不能信任客户端可伪造的 X-Forwarded-For。',
+    ],
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=false',
+      '前置代理信任确认开关必须默认关闭。',
+    ],
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true',
+      '接流保护必须默认开启。',
+    ],
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN=',
+      '内部探针 token 示例必须保持空值，避免发布包夹带真实 token。',
+    ],
+  ];
+  for (const [line, reason] of requiredLines) {
+    assertIncludes(content, line, `${label} ${reason}`);
+  }
+}
diff --git a/scripts/check-production-health-patrol-env-check.mjs b/scripts/check-production-health-patrol-env-check.mjs
new file mode 100644
index 000000000..e8c1c003b
--- /dev/null
+++ b/scripts/check-production-health-patrol-env-check.mjs
@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-health-patrol-env-check-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:production-health-patrol-env] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:production-health-patrol-env] OK');
+
+function main() {
+  assertAcceptsPingoraDirectLoopbackWithHost();
+  assertRejectsPingoraDirectLoopbackWithoutHost();
+  assertRejectsWrongGatewayMode();
+  assertAcceptsNginxWithEmptyPublicHost();
+  assertRejectsNginxWithStalePublicHost();
+  assertRejectsInvalidPublicHost();
+  assertRejectsInvalidEnvFilePaths();
+  assertRejectsInvalidBoolEnv();
+  assertExampleDocumentsDirectMode();
+}
+
+function assertAcceptsPingoraDirectLoopbackWithHost() {
+  const envFile = writeEnv('pingora-direct-ok.env', {
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'pingora-direct',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'https://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: 'genarrative.example',
+  });
+  const result = runCheck([
+    '--env-file',
+    envFile,
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'genarrative.example',
+  ]);
+  assertStatus(result, 0, 'Pingora direct loopback 配正式 Host 应通过。');
+}
+
+function assertRejectsPingoraDirectLoopbackWithoutHost() {
+  const envFile = writeEnv('pingora-direct-missing-host.env', {
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'pingora-direct',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'https://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const result = runCheck([
+    '--env-file',
+    envFile,
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+  ]);
+  assertStatus(
+    result,
+    1,
+    'Pingora direct loopback 缺 Host 必须失败。',
+  );
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'Pingora direct 模式使用本机 public base URL 时必须配置 GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST',
+    'Pingora direct loopback 缺 Host 必须给出明确错误。',
+  );
+}
+
+function assertRejectsWrongGatewayMode() {
+  const envFile = writeEnv('wrong-mode.env', {
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'https://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: 'genarrative.example',
+  });
+  const result = runCheck([
+    '--env-file',
+    envFile,
+    '--expected-gateway-mode',
+    'pingora-direct',
+  ]);
+  assertStatus(result, 1, 'gateway mode 与期望不一致必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE 应为 pingora-direct，实际 nginx',
+    'gateway mode mismatch 必须给出明确错误。',
+  );
+}
+
+function assertAcceptsNginxWithEmptyPublicHost() {
+  const envFile = writeEnv('nginx-empty-host.env', {
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const result = runCheck([
+    '--env-file',
+    envFile,
+    '--expected-gateway-mode',
+    'nginx',
+    '--expected-public-base-url',
+    'http://127.0.0.1',
+    '--require-empty-public-host',
+  ]);
+  assertStatus(result, 0, 'Nginx 模式回退且 Host 为空应通过。');
+}
+
+function assertRejectsNginxWithStalePublicHost() {
+  const envFile = writeEnv('nginx-stale-host.env', {
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: 'genarrative.example',
+  });
+  const result = runCheck([
+    '--env-file',
+    envFile,
+    '--expected-gateway-mode',
+    'nginx',
+    '--require-empty-public-host',
+  ]);
+  assertStatus(result, 1, 'Nginx 回退后残留 Host 覆盖必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 应为空',
+    'Nginx 回退后残留 Host 覆盖必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidPublicHost() {
+  const envFile = writeEnv('invalid-host.env', {
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'pingora-direct',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'https://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: 'https://genarrative.example',
+  });
+  const result = runCheck([
+    '--env-file',
+    envFile,
+    '--expected-gateway-mode',
+    'pingora-direct',
+  ]);
+  assertStatus(result, 1, '非法 public Host 必须失败。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 只能是 host 或 host:port',
+    '非法 public Host 必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidEnvFilePaths() {
+  const relativePath = runCheck([
+    '--env-file',
+    'health-patrol.env',
+    '--expected-gateway-mode',
+    'nginx',
+  ]);
+  assertStatus(relativePath, 1, 'health patrol env 复核必须拒绝相对 env 文件路径。');
+  assertIncludes(
+    `${relativePath.stdout}\n${relativePath.stderr}`,
+    '--env-file 必须是绝对路径',
+    '相对 env 文件路径必须给出明确错误。',
+  );
+
+  const rootPath = runCheck([
+    '--env-file',
+    '/',
+    '--expected-gateway-mode',
+    'nginx',
+  ]);
+  assertStatus(rootPath, 1, 'health patrol env 复核必须拒绝文件系统根目录。');
+  assertIncludes(
+    `${rootPath.stdout}\n${rootPath.stderr}`,
+    '--env-file 不能是文件系统根目录',
+    '文件系统根目录 env 文件路径必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidBoolEnv() {
+  const envFile = writeEnv('invalid-bool-env.env', {
+    GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: 'nginx',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: 'http://127.0.0.1',
+    GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: '',
+  });
+  const result = runCheck(
+    [
+      '--env-file',
+      envFile,
+      '--expected-gateway-mode',
+      'nginx',
+    ],
+    {
+      GENARRATIVE_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST: 'enabled',
+    },
+  );
+  assertStatus(result, 1, 'health patrol env 复核必须拒绝非法布尔 env。');
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    'GENARRATIVE_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST 必须是布尔值',
+    'health patrol env 复核非法布尔 env 必须给出明确错误。',
+  );
+}
+
+function assertExampleDocumentsDirectMode() {
+  const example = readFileSync('deploy/env/health-patrol.env.example', 'utf8');
+  assertIncludes(
+    example,
+    'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx',
+    'health patrol env 示例必须保留默认 nginx 模式。',
+  );
+  assertIncludes(
+    example,
+    'Pingora 直连切换后改为 pingora-direct',
+    'health patrol env 示例必须说明 Pingora direct 切换口径。',
+  );
+}
+
+function writeEnv(name, values) {
+  const filePath = path.join(tmpRoot, name);
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  const body = Object.entries(values)
+    .map(([key, value]) => `${key}=${value}`)
+    .join('\n');
+  writeFileSync(filePath, `${body}\n`, 'utf8');
+  return filePath;
+}
+
+function runCheck(args, extraEnv = {}) {
+  return spawnSync(
+    process.execPath,
+    ['--', 'scripts/check-production-health-patrol-env.mjs', ...args],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        GENARRATIVE_HEALTH_PATROL_ENV_FILE: '',
+        GENARRATIVE_HEALTH_PATROL_EXPECTED_GATEWAY_MODE: '',
+        GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL: '',
+        GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_HOST: '',
+        GENARRATIVE_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST: '',
+        ...extraEnv,
+      },
+    },
+  );
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!content.includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
diff --git a/scripts/check-production-health-patrol-env.mjs b/scripts/check-production-health-patrol-env.mjs
new file mode 100644
index 000000000..309908df0
--- /dev/null
+++ b/scripts/check-production-health-patrol-env.mjs
@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const GATEWAY_MODES = new Set(['nginx', 'pingora-direct']);
+
+const config = parseArgs(process.argv.slice(2));
+const failures = [];
+const envValues = readEnvFile(config.envFile);
+
+checkGatewayMode();
+checkPublicBaseUrl();
+checkPublicHost();
+
+if (failures.length > 0) {
+  console.error('[check:production-health-patrol-env] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:production-health-patrol-env] OK');
+
+function parseArgs(argv) {
+  const result = {
+    envFile:
+      process.env.GENARRATIVE_HEALTH_PATROL_ENV_FILE ||
+      '/etc/genarrative/health-patrol.env',
+    expectedGatewayMode:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_GATEWAY_MODE || '',
+    expectedPublicBaseUrl:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL || '',
+    expectedPublicHost:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_HOST || null,
+    requireEmptyPublicHost:
+      readBoolEnv('GENARRATIVE_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST'),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--env-file':
+        result.envFile = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-gateway-mode':
+        result.expectedGatewayMode = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-public-base-url':
+        result.expectedPublicBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-public-host':
+        result.expectedPublicHost = requireValue(argv, ++index, arg);
+        break;
+      case '--require-empty-public-host':
+        result.requireEmptyPublicHost = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (!result.expectedGatewayMode) {
+    throw new Error(
+      '必须提供 --expected-gateway-mode 或 GENARRATIVE_HEALTH_PATROL_EXPECTED_GATEWAY_MODE。',
+    );
+  }
+  if (!path.isAbsolute(result.envFile)) {
+    throw new Error(`--env-file 必须是绝对路径: ${result.envFile}`);
+  }
+  if (isFilesystemRootPath(result.envFile)) {
+    throw new Error('--env-file 不能是文件系统根目录。');
+  }
+  if (!GATEWAY_MODES.has(result.expectedGatewayMode)) {
+    throw new Error(
+      `--expected-gateway-mode 只支持 nginx 或 pingora-direct: ${result.expectedGatewayMode}`,
+    );
+  }
+  if (result.expectedPublicBaseUrl) {
+    normalizeBaseUrl(result.expectedPublicBaseUrl, '--expected-public-base-url');
+  }
+  if (result.expectedPublicHost !== null) {
+    validateHostOption(result.expectedPublicHost, '--expected-public-host');
+  }
+  if (result.expectedPublicHost !== null && result.requireEmptyPublicHost) {
+    throw new Error(
+      '--expected-public-host 和 --require-empty-public-host 不能同时使用。',
+    );
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node -- scripts/check-production-health-patrol-env.mjs --expected-gateway-mode <mode> [options]
+
+Options:
+  --env-file <path>                 health-patrol env 文件，默认 /etc/genarrative/health-patrol.env。
+  --expected-gateway-mode <mode>    nginx 或 pingora-direct。
+  --expected-public-base-url <url>  可选，要求 GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL 与该 URL 一致。
+  --expected-public-host <host>     可选，要求 GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 与该 Host 一致。
+  --require-empty-public-host       要求 GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 为空，适合回退到 Nginx 后复核。
+`);
+}
+
+function readBoolEnv(name) {
+  const value = process.env[name];
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return false;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${name} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function readEnvFile(filePath) {
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf8');
+  } catch (error) {
+    throw new Error(`无法读取 health patrol env 文件 ${filePath}: ${error.message}`);
+  }
+
+  const values = new Map();
+  for (const [index, rawLine] of text.split(/\r?\n/u).entries()) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    if (line.startsWith('export ')) {
+      line = line.slice('export '.length).trim();
+    }
+    const equalsIndex = line.indexOf('=');
+    if (equalsIndex <= 0) {
+      failures.push(`第 ${index + 1} 行不是 KEY=VALUE 格式: ${rawLine}`);
+      continue;
+    }
+    const key = line.slice(0, equalsIndex).trim();
+    const value = stripQuotes(line.slice(equalsIndex + 1).trim());
+    values.set(key, value);
+  }
+  return values;
+}
+
+function stripQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function envValue(name) {
+  return envValues.get(name) ?? '';
+}
+
+function checkGatewayMode() {
+  const actual = envValue('GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE');
+  if (!actual) {
+    failures.push(
+      'health patrol env 缺少 GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE。',
+    );
+    return;
+  }
+  if (actual !== config.expectedGatewayMode) {
+    failures.push(
+      `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE 应为 ${config.expectedGatewayMode}，实际 ${actual}。`,
+    );
+  }
+}
+
+function checkPublicBaseUrl() {
+  if (!config.expectedPublicBaseUrl) {
+    return;
+  }
+
+  const actual = envValue('GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL');
+  if (!actual) {
+    failures.push(
+      'health patrol env 缺少 GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL。',
+    );
+    return;
+  }
+  const expected = normalizeBaseUrl(
+    config.expectedPublicBaseUrl,
+    '--expected-public-base-url',
+  );
+  const normalizedActual = normalizeBaseUrl(
+    actual,
+    'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL',
+  );
+  if (normalizedActual !== expected) {
+    failures.push(
+      `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL 应为 ${expected}，实际 ${normalizedActual}。`,
+    );
+  }
+}
+
+function checkPublicHost() {
+  const publicHost = envValue('GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST');
+  const baseUrl =
+    config.expectedPublicBaseUrl ||
+    envValue('GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL');
+
+  if (publicHost) {
+    try {
+      validateHostOption(publicHost, 'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST');
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+
+  if (config.expectedPublicHost !== null && publicHost !== config.expectedPublicHost) {
+    failures.push(
+      `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 应为 ${config.expectedPublicHost}，实际 ${publicHost || '(空)'}。`,
+    );
+  }
+
+  if (config.requireEmptyPublicHost && publicHost) {
+    failures.push(
+      `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 应为空，实际 ${publicHost}。`,
+    );
+  }
+
+  if (
+    config.expectedGatewayMode === 'pingora-direct' &&
+    baseUrl &&
+    isLoopbackUrl(baseUrl) &&
+    !publicHost
+  ) {
+    failures.push(
+      'Pingora direct 模式使用本机 public base URL 时必须配置 GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST，避免巡检命中默认 vhost。',
+    );
+  }
+}
+
+function normalizeBaseUrl(value, label) {
+  try {
+    const parsed = new URL(value);
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+      throw new Error('unsupported protocol');
+    }
+    return parsed.toString().replace(/\/+$/u, '');
+  } catch {
+    throw new Error(`${label} 必须是合法 http(s) URL: ${value}`);
+  }
+}
+
+function validateHostOption(value, label) {
+  const raw = String(value);
+  if (raw !== raw.trim() || raw.includes('://') || /[\s/?#@]/.test(raw)) {
+    throw new Error(
+      `${label} 只能是 host 或 host:port，不能包含 scheme、路径、查询、片段或空白字符。`,
+    );
+  }
+  try {
+    const parsed = new URL(`https://${raw}`);
+    if (
+      !parsed.hostname ||
+      parsed.pathname !== '/' ||
+      parsed.search ||
+      parsed.hash ||
+      parsed.username ||
+      parsed.password
+    ) {
+      throw new Error('invalid host');
+    }
+  } catch {
+    throw new Error(`${label} 不是合法的 host 或 host:port。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function isLoopbackUrl(value) {
+  try {
+    const hostname = new URL(value).hostname.toLowerCase();
+    return (
+      hostname === 'localhost' ||
+      hostname === '::1' ||
+      hostname === '[::1]' ||
+      hostname.startsWith('127.')
+    );
+  } catch {
+    return false;
+  }
+}
diff --git a/scripts/check-production-health-patrol.mjs b/scripts/check-production-health-patrol.mjs
new file mode 100644
index 000000000..b61f12da5
--- /dev/null
+++ b/scripts/check-production-health-patrol.mjs
@@ -0,0 +1,478 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import http from 'node:http';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-health-patrol-check-'),
+);
+
+try {
+  await main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:production-health-patrol] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:production-health-patrol] OK');
+
+async function main() {
+  assertPublicBaseUrlDefaultsToGatewayEntry();
+  await assertNginxModeChecksNginxService();
+  await assertPingoraDirectModeChecksPingoraServiceAndPublicHost();
+  assertRejectsInvalidGatewayMode();
+  assertRejectsInvalidPublicHost();
+  assertRejectsInvalidTimeoutAndSlowThreshold();
+  assertRejectsInvalidBoolEnv();
+}
+
+function assertPublicBaseUrlDefaultsToGatewayEntry() {
+  const script = readFileSync(
+    'scripts/ops/production-health-patrol.mjs',
+    'utf8',
+  );
+  assertIncludes(
+    script,
+    "process.env.GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL ||\n      'http://127.0.0.1'",
+    'publicBaseUrl 默认必须指向本机网关入口，不能回落到 API 直连端口。',
+  );
+  if (
+    script.includes(
+      'process.env.GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL ||\n      process.env.GENARRATIVE_HEALTH_PATROL_API_BASE_URL',
+    )
+  ) {
+    failures.push('publicBaseUrl 默认不应回落到 API base URL。');
+  }
+}
+
+async function assertNginxModeChecksNginxService() {
+  const fixture = await prepareFixture('nginx-mode');
+  const result = await runPatrol(fixture, ['--gateway-mode', 'nginx']);
+
+  assertStatus(result, 0, 'nginx gateway mode 巡检应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+
+  const payload = JSON.parse(result.stdout);
+  assertEqual(
+    payload.gatewayMode,
+    'nginx',
+    '巡检 JSON 必须记录 gatewayMode=nginx。',
+  );
+
+  const commandsLog = readFileSync(fixture.commandsLog, 'utf8');
+  assertIncludes(
+    commandsLog,
+    'systemctl is-active nginx.service',
+    'nginx gateway mode 必须检查 nginx.service。',
+  );
+  if (commandsLog.includes('genarrative-pingora-gateway.service')) {
+    failures.push(
+      'nginx gateway mode 不应要求 Pingora gateway service active。',
+    );
+  }
+}
+
+async function assertPingoraDirectModeChecksPingoraServiceAndPublicHost() {
+  const fixture = await prepareFixture('pingora-direct-mode');
+  const result = await runPatrol(fixture, [
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-host',
+    'genarrative.example',
+  ]);
+
+  assertStatus(result, 0, 'pingora-direct gateway mode 巡检应成功。');
+  if (result.status !== 0) {
+    return;
+  }
+
+  const payload = JSON.parse(result.stdout);
+  assertEqual(
+    payload.gatewayMode,
+    'pingora-direct',
+    '巡检 JSON 必须记录 gatewayMode=pingora-direct。',
+  );
+
+  const commandsLog = readTextFile(fixture.commandsLog, 'systemctl 命令日志');
+  assertIncludes(
+    commandsLog,
+    'systemctl is-active genarrative-pingora-gateway.service',
+    'pingora-direct gateway mode 必须检查 Pingora gateway service。',
+  );
+  if (commandsLog.includes('systemctl is-active nginx.service')) {
+    failures.push(
+      'pingora-direct gateway mode 不应要求 nginx.service active。',
+    );
+  }
+
+  const requestsLog = readTextFile(
+    fixture.requestsLog,
+    'public probe 请求日志',
+  );
+  assertIncludes(
+    requestsLog,
+    'host=genarrative.example path=/api/creation-entry/config',
+    'public probe 必须带正式域名 Host header。',
+  );
+}
+
+function assertRejectsInvalidGatewayMode() {
+  const result = spawnSync(
+    'node',
+    [
+      'scripts/ops/production-health-patrol.mjs',
+      '--gateway-mode',
+      'direct',
+      '--skip-journal',
+      '--json',
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+
+  if ((result.status ?? 0) === 0) {
+    failures.push('非法 gateway mode 必须失败。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--gateway-mode 只支持 nginx 或 pingora-direct',
+    '非法 gateway mode 必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidPublicHost() {
+  const result = spawnSync(
+    'node',
+    [
+      'scripts/ops/production-health-patrol.mjs',
+      '--public-host',
+      'https://genarrative.example',
+      '--skip-journal',
+      '--json',
+    ],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+
+  if ((result.status ?? 0) === 0) {
+    failures.push('非法 public host 必须失败。');
+  }
+  assertIncludes(
+    `${result.stdout}\n${result.stderr}`,
+    '--public-host 只接受域名或 host:port',
+    '非法 public host 必须给出明确错误。',
+  );
+}
+
+function assertRejectsInvalidTimeoutAndSlowThreshold() {
+  const cases = [
+    {
+      args: ['--timeout-ms', '0'],
+      env: {},
+      expected: '--timeout-ms 必须是正整数',
+      reason: '非法 CLI timeout 必须失败。',
+    },
+    {
+      args: ['--slow-ms', 'abc'],
+      env: {},
+      expected: '--slow-ms 必须是正整数',
+      reason: '非法 CLI slow threshold 必须失败。',
+    },
+    {
+      args: [],
+      env: {
+        GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS: 'abc',
+      },
+      expected: 'GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS 必须是正整数',
+      reason: '非法 env timeout 必须失败。',
+    },
+    {
+      args: [],
+      env: {
+        GENARRATIVE_HEALTH_PATROL_SLOW_MS: '0',
+      },
+      expected: 'GENARRATIVE_HEALTH_PATROL_SLOW_MS 必须是正整数',
+      reason: '非法 env slow threshold 必须失败。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = spawnSync(
+      'node',
+      [
+        'scripts/ops/production-health-patrol.mjs',
+        '--skip-journal',
+        '--json',
+        ...testCase.args,
+      ],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: {
+          ...process.env,
+          ...testCase.env,
+        },
+      },
+    );
+
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+function assertRejectsInvalidBoolEnv() {
+  const cases = [
+    {
+      env: {
+        GENARRATIVE_HEALTH_PATROL_FAIL_ON_WARNING: 'ture',
+      },
+      expected: 'GENARRATIVE_HEALTH_PATROL_FAIL_ON_WARNING 必须是布尔值',
+      reason: '生产健康巡检必须拒绝拼写错误的 fail-on-warning env。',
+    },
+    {
+      env: {
+        GENARRATIVE_HEALTH_PATROL_SKIP_JOURNAL: 'maybe',
+      },
+      expected: 'GENARRATIVE_HEALTH_PATROL_SKIP_JOURNAL 必须是布尔值',
+      reason: '生产健康巡检必须拒绝非法 skip-journal env。',
+    },
+  ];
+
+  for (const testCase of cases) {
+    const result = spawnSync(
+      'node',
+      ['scripts/ops/production-health-patrol.mjs', '--json'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: {
+          ...process.env,
+          ...testCase.env,
+        },
+      },
+    );
+
+    if ((result.status ?? 0) === 0) {
+      failures.push(testCase.reason);
+    }
+    assertIncludes(
+      `${result.stdout}\n${result.stderr}`,
+      testCase.expected,
+      `${testCase.reason} 必须给出明确错误。`,
+    );
+  }
+}
+
+async function prepareFixture(name) {
+  const root = path.join(tmpRoot, name);
+  const fakeBin = path.join(root, 'bin');
+  const commandsLog = path.join(root, 'commands.log');
+  const requestsLog = path.join(root, 'requests.log');
+
+  mkdirSync(fakeBin, { recursive: true });
+
+  writeFileSync(
+    path.join(fakeBin, 'systemctl'),
+    [
+      '#!/usr/bin/env bash',
+      `printf 'systemctl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      'if [[ "$1" == "list-units" && "$2" == "genarrative-external-generation-worker@*.service" ]]; then',
+      '  echo "genarrative-external-generation-worker@1.service loaded active running Genarrative external generation worker 1"',
+      '  exit 0',
+      'fi',
+      'echo active',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(fakeBin, 'journalctl'),
+    [
+      '#!/usr/bin/env bash',
+      `printf 'journalctl %s\\n' "$*" >> ${shellQuote(commandsLog)}`,
+      'echo "-- No entries --"',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodExecutable(path.join(fakeBin, 'systemctl'));
+  chmodExecutable(path.join(fakeBin, 'journalctl'));
+
+  const server = http.createServer((request, response) => {
+    writeFileSync(
+      requestsLog,
+      `host=${request.headers.host || ''} path=${request.url || ''}\n`,
+      {
+        encoding: 'utf8',
+        flag: 'a',
+      },
+    );
+    response.writeHead(200, {
+      'Content-Type': 'application/json',
+    });
+    response.end(JSON.stringify({ ok: true }));
+  });
+  await listen(server, '127.0.0.1', 0);
+
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('测试 HTTP server 未返回 TCP 端口。');
+  }
+
+  return {
+    root,
+    fakeBin,
+    commandsLog,
+    requestsLog,
+    server,
+    baseUrl: `http://127.0.0.1:${address.port}`,
+  };
+}
+
+async function runPatrol(fixture, args) {
+  try {
+    return await spawnProcess(
+      'node',
+      [
+        'scripts/ops/production-health-patrol.mjs',
+        '--api-base-url',
+        fixture.baseUrl,
+        '--spacetime-base-url',
+        fixture.baseUrl,
+        '--public-base-url',
+        fixture.baseUrl,
+        '--skip-journal',
+        '--json',
+        ...args,
+      ],
+      {
+        cwd: process.cwd(),
+        env: {
+          ...process.env,
+          PATH: `${fixture.fakeBin}:${process.env.PATH || ''}`,
+        },
+      },
+    );
+  } finally {
+    await closeServer(fixture.server);
+  }
+}
+
+function spawnProcess(command, args, options) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      ...options,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) => {
+      resolve({
+        status: 1,
+        stdout,
+        stderr: `${stderr}${error.message}`,
+      });
+    });
+    child.on('close', (code, signal) => {
+      resolve({
+        status: code ?? 1,
+        signal,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+function listen(server, host, port) {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolve);
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolve) => {
+    server.close(() => resolve());
+  });
+}
+
+function readTextFile(filePath, label) {
+  if (!existsSync(filePath)) {
+    failures.push(`${label} 未生成：${filePath}`);
+    return '';
+  }
+  return readFileSync(filePath, 'utf8');
+}
+
+function chmodExecutable(filePath) {
+  spawnSync('chmod', ['0755', filePath], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function assertStatus(result, expected, reason) {
+  const actual = result.status ?? 0;
+  if (actual !== expected) {
+    failures.push(
+      `${reason} 预期退出码 ${expected}，实际 ${actual}。\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+    );
+  }
+}
+
+function assertIncludes(content, needle, reason) {
+  if (!content.includes(needle)) {
+    failures.push(`${reason} 缺少: ${needle}`);
+  }
+}
+
+function assertEqual(actual, expected, reason) {
+  if (actual !== expected) {
+    failures.push(`${reason} 实际 ${actual}，预期 ${expected}。`);
+  }
+}
diff --git a/scripts/check-production-ops-guardrails.mjs b/scripts/check-production-ops-guardrails.mjs
index 89ce254ec..4ab1e3ff1 100644
--- a/scripts/check-production-ops-guardrails.mjs
+++ b/scripts/check-production-ops-guardrails.mjs
@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import {readFileSync} from 'node:fs';
+import { readFileSync } from 'node:fs';
 
 const checks = [
   {
@@ -8,21 +8,955 @@ const checks = [
     includes: '--restart-service-after genarrative-api.service',
     reason: '生产冷备份恢复 SpacetimeDB 后必须显式拉起依赖它的 API 服务。',
   },
+  {
+    file: 'deploy/systemd/genarrative-database-backup.service',
+    includes: 'ExecStart=/usr/bin/node -- /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file',
+    reason:
+      '生产冷备份 service 必须用 node -- 分隔脚本参数，避免 Node 22 抢占业务 --env-file。',
+  },
   {
     file: 'deploy/systemd/genarrative-health-patrol.service',
     includes: 'scripts/ops/production-health-patrol.mjs',
     reason: '健康巡检 systemd service 必须调用随 API release 发布的巡检脚本。',
   },
+  {
+    file: 'deploy/env/health-patrol.env.example',
+    includes: 'GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL',
+    reason: '健康巡检环境示例必须保留 Pingora shadow 可选巡检配置。',
+  },
+  {
+    file: 'deploy/env/health-patrol.env.example',
+    includes: 'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx',
+    reason: '健康巡检环境示例必须显式保留默认 Nginx 网关模式。',
+  },
+  {
+    file: 'deploy/env/health-patrol.env.example',
+    includes: 'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=',
+    reason: '健康巡检环境示例必须暴露公网 Host header 配置。',
+  },
+  {
+    file: 'scripts/ops/production-health-patrol.mjs',
+    includes: 'pingora-direct',
+    reason:
+      '健康巡检必须支持 Pingora 直连模式，避免直连切换后误要求 Nginx active。',
+  },
+  {
+    file: 'scripts/ops/production-health-patrol.mjs',
+    includes: 'genarrative-pingora-gateway.service',
+    reason: 'Pingora 直连巡检模式必须检查 Pingora gateway service。',
+  },
+  {
+    file: 'scripts/ops/production-health-patrol.mjs',
+    includes: 'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST',
+    reason: '健康巡检必须支持给 public probe 传正式域名 Host header。',
+  },
+  {
+    file: 'scripts/ops/production-health-patrol.mjs',
+    includes: 'parseRequiredPositiveInt',
+    reason:
+      '健康巡检 timeout 和慢请求阈值必须严格校验，不能静默回默认值。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'current release 自包含能力',
+    reason: 'Pingora current release 自审脚本必须说明它只检查发布包自包含能力。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'scripts/check-pingora-release-readiness.mjs',
+    reason: 'Pingora current release 自审必须确认 release readiness 聚合门禁脚本已随包发布。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    reason: 'Pingora current release 自审必须确认直连彩排状态脚本已随包发布。',
+  },
+  {
+    file: 'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    includes: '该脚本只读采集',
+    reason: 'Pingora 直连彩排状态脚本必须声明只读边界。',
+  },
+  {
+    file: 'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    includes: 'ss',
+    reason: 'Pingora 直连彩排状态脚本必须读取端口监听状态。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rehearsal-status.mjs',
+    includes: 'assertNginxPublicRealpathRehearsalPasses',
+    reason: 'Pingora 直连彩排状态自测必须覆盖 Nginx 公网 + realpath canary 正例。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'scripts/check-pingora-canary-live.mjs',
+    reason: 'Pingora current release 自审必须确认 canary live smoke 脚本已随包发布。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'scripts/deploy/pingora-realpath-canary-enable.sh',
+    reason: 'Pingora current release 自审必须确认 realpath canary 启用脚本已随包发布。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'scripts/deploy/pingora-realpath-canary-disable.sh',
+    reason: 'Pingora current release 自审必须确认 realpath canary 关闭脚本已随包发布。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: '--systemd-show',
+    reason: 'Pingora current release 自审必须能核验 systemd ExecStart 指向 current release。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'pingora-gateway.sha256',
+    reason: 'Pingora current release 自审必须校验 Pingora 网关 checksum。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'release-manifest.api-server.json',
+    reason: 'Pingora current release 自审必须读取部署后的 API release manifest。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'release manifest 缺少 pingora-gateway artifact',
+    reason: 'Pingora current release 自审必须阻断 manifest 未登记 Pingora 产物。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'parseRequiredPositiveInt',
+    reason: 'Pingora current release 自审 timeout 参数必须严格校验，不能静默回默认值。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: '必须是布尔值 true/false 或 1/0',
+    reason:
+      'Pingora current release 自审布尔 env 必须严格校验，避免拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'isFilesystemRootPath',
+    reason: 'Pingora current release 自审必须显式拒绝把 release root 指到 /。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: 'validateNoControlCharacters',
+    reason:
+      'Pingora current release 自审必须在执行 systemctl 前拒绝带控制字符的路径和子命令参数。',
+  },
+  {
+    file: 'scripts/ops/pingora-current-release-audit.mjs',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora current release 自审必须明确拒绝带换行或 NUL 的路径和子命令参数。',
+  },
+  {
+    file: 'scripts/check-pingora-current-release-audit.mjs',
+    includes: '完整 release 自审必须确认 canary live smoke 脚本存在',
+    reason: 'Pingora current release 自审自测必须覆盖 canary live smoke 脚本随包存在。',
+  },
+  {
+    file: 'scripts/check-pingora-current-release-audit.mjs',
+    includes: 'assertChecksumMismatchFails',
+    reason: 'Pingora current release 自审自测必须覆盖 checksum 不匹配负例。',
+  },
+  {
+    file: 'scripts/check-pingora-current-release-audit.mjs',
+    includes: 'assertManifestMustRegisterIncludedPingoraGateway',
+    reason: 'Pingora current release 自审自测必须覆盖 manifest 未登记 Pingora 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-current-release-audit.mjs',
+    includes: 'assertRejectsInvalidTimeout',
+    reason: 'Pingora current release 自审自测必须覆盖非法 timeout 参数和 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-current-release-audit.mjs',
+    includes: 'assertRejectsInvalidBoolEnv',
+    reason: 'Pingora current release 自审自测必须覆盖非法布尔 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-current-release-audit.mjs',
+    includes: 'assertRejectsFilesystemRootReleaseRoot',
+    reason: 'Pingora current release 自审自测必须覆盖 release root 指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-current-release-audit.mjs',
+    includes: 'assertRejectsPathArgsWithControlCharacters',
+    reason:
+      'Pingora current release 自审自测必须覆盖带控制字符路径参数在执行 systemctl 前失败。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'scripts/ops/pingora-current-release-audit.mjs',
+    reason: 'Pingora 切换状态快照必须把 current release 自审脚本纳入随包依赖采集。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: '--fail-on-critical',
+    reason: 'Pingora 切换状态快照必须能作为只读硬门禁运行。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: '--run-health-patrol',
+    reason: 'Pingora 切换状态快照必须复用生产健康巡检作为证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'current-release-audit',
+    reason: 'Pingora 切换状态快照必须执行 current release 自审。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'releaseManifest',
+    reason: 'Pingora 切换状态快照必须收录 manifest 自审结果。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'collectSecretValuesFromEnv',
+    reason: 'Pingora 切换状态快照必须从 env 中收集敏感值用于后续输出脱敏。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'delete healthPatrolEnv.secretValues',
+    reason: 'Pingora 切换状态快照 JSON 不能输出 health patrol env 敏感值缓存。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'delete pingoraEnv.secretValues',
+    reason: 'Pingora 切换状态快照 JSON 不能输出 Pingora env 敏感值缓存。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'redactSecrets',
+    reason: 'Pingora 切换状态快照必须在收录子命令 stdout/stderr 前脱敏敏感值。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'parseRequiredPositiveInt',
+    reason: 'Pingora 切换状态快照 timeout 参数必须严格校验，不能静默回默认值。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: '必须是布尔值 true/false 或 1/0',
+    reason:
+      'Pingora 切换状态快照布尔 env 必须严格校验，避免 run/fail/require 开关拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'isFilesystemRootPath',
+    reason: 'Pingora 切换状态快照必须显式拒绝把 release root 指到 /。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'validateNoControlCharacters',
+    reason:
+      'Pingora 切换状态快照必须在执行子命令前拒绝带控制字符的路径和子命令参数。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora 切换状态快照必须明确拒绝带换行或 NUL 的路径和子命令参数。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: '--health-patrol-env-file 不能是文件系统根目录',
+    reason: 'Pingora 切换状态快照必须拒绝把 health patrol env 文件指到 /。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: '--pingora-env-file 不能是文件系统根目录',
+    reason: 'Pingora 切换状态快照必须拒绝把 Pingora env 文件指到 /。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'environmentFileMatchesPingoraEnvFile',
+    reason:
+      'Pingora 切换状态快照必须确认 systemd EnvironmentFile 指向本次 pingora env。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: '--expected-pingora-env-mode',
+    reason:
+      'Pingora 切换状态快照必须支持按阶段强制校验 active Pingora env 是 direct 或 shadow。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'summarizePingoraEnvPosture',
+    reason:
+      'Pingora 切换状态快照必须输出 active Pingora env 的 shadow/direct 姿态摘要。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'EnvironmentFile 未包含本次 --pingora-env-file',
+    reason:
+      'Pingora 切换状态快照必须在 systemd EnvironmentFile 漂移时给出明确诊断。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertFailOnCriticalRejectsReleaseAuditFailure',
+    reason: 'Pingora 状态快照自测必须覆盖 current release 自审失败负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertFailOnCriticalRejectsSystemdPingoraEnvDrift',
+    reason: 'Pingora 状态快照自测必须覆盖 systemd 读取了另一份 Pingora env 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertSnapshotRejectsDirectPingoraEnvModeDrift',
+    reason:
+      'Pingora 状态快照自测必须覆盖启用后 active env 仍是 shadow 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertSnapshotRejectsShadowPingoraEnvModeDrift',
+    reason:
+      'Pingora 状态快照自测必须覆盖回退后 active env 仍残留 direct TLS 配置的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertSnapshotRedactsEnvProbeTokens',
+    reason: 'Pingora 状态快照自测必须确认 env probe token 不进入快照输出。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertRejectsInvalidTimeout',
+    reason: 'Pingora 状态快照自测必须覆盖非法 timeout 参数和 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertRejectsInvalidBoolEnv',
+    reason: 'Pingora 状态快照自测必须覆盖非法布尔 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertRejectsFilesystemRootReleaseRoot',
+    reason: 'Pingora 状态快照自测必须覆盖 release root 指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertRejectsPathArgsWithControlCharacters',
+    reason:
+      'Pingora 状态快照自测必须覆盖带控制字符路径参数在执行 systemctl 前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertRejectsFilesystemRootEnvFiles',
+    reason: 'Pingora 状态快照自测必须覆盖 env 文件参数指到 / 的负例。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'snapshot.stdout.txt',
+    reason: 'Pingora 切换证据包必须保存状态快照 stdout 便于复盘。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'direct-live.stdout.txt',
+    reason:
+      'Pingora 切换证据包必须保存 direct live stdout，保留 request_id / access log 复核证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'parseDirectLiveJson',
+    reason:
+      'Pingora 切换证据包必须能从 direct live stdout 中提取 JSON 结果。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'pingoraEnvShadow',
+    reason:
+      'Pingora 切换证据包必须把状态快照中的 Pingora env shadow 摘要提升到 manifest。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--expected-pingora-env-mode',
+    reason:
+      'Pingora 切换证据包必须把 active Pingora env 姿态要求透传给状态快照。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'tlsCertFile 应为空',
+    reason:
+      'Pingora env shadow 摘要必须把 TLS 证书路径残留纳入回退证据诊断。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'snapshotParseError',
+    reason:
+      'Pingora 切换证据包必须把 snapshot 解析失败文件纳入 manifest 和 stdout 索引。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'directLiveParseError',
+    reason:
+      'Pingora 切换证据包必须把 direct live 解析失败文件纳入 manifest 和 stdout 索引。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--run-direct-live',
+    reason:
+      'Pingora 切换证据包必须提供显式 direct live 归档开关。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--direct-pingora-access-log',
+    reason:
+      'Pingora 切换证据包 direct live 归档必须接入 access log request_id 校验路径。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'SECRET_VALUE_FLAGS',
+    reason: 'Pingora 切换证据包命令记录必须集中维护敏感参数脱敏列表。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '<redacted>',
+    reason: 'Pingora 切换证据包命令记录不能落盘 probe token 原文。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'args: redactSecretArgs',
+    reason: 'Pingora 切换证据包命令记录必须保存结构化脱敏参数数组。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'validateEvidenceCommandArgs',
+    reason:
+      'Pingora 切换证据包必须在执行状态快照或 direct live 前拒绝带控制字符的子命令参数。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'validateSafeAbsoluteFilePath',
+    reason:
+      'Pingora 切换证据包 direct live 显式文件路径必须统一拒绝相对路径、根目录和控制字符。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--direct-spacetime-database',
+    reason:
+      'Pingora 切换证据包必须在配置层拒绝带控制字符的 direct SpacetimeDB 数据库名。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--direct-probe-token',
+    reason:
+      'Pingora 切换证据包必须在配置层拒绝带控制字符的 direct live probe token。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora 切换证据包必须明确拒绝带换行或 NUL 的状态快照 / direct live 参数。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: "createHash('sha256')",
+    reason: 'Pingora 切换证据包 manifest 必须记录证据文件 sha256，便于归档后复核。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'sizeBytes',
+    reason: 'Pingora 切换证据包 manifest 必须记录证据文件大小，便于归档后复核。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'snapshot-command.json 结构化参数数组必须保留快照参数',
+    reason: 'Pingora 切换证据包自测必须覆盖结构化命令参数记录。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertManifestFileMetadata',
+    reason: 'Pingora 切换证据包自测必须覆盖 manifest 文件大小与 sha256 元数据。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertBundleCanArchiveDirectLiveEvidence',
+    reason:
+      'Pingora 切换证据包自测必须覆盖 direct live 证据归档成功路径。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertBundleSummarizesPingoraEnvShadow',
+    reason:
+      'Pingora 切换证据包自测必须覆盖 Pingora env shadow 摘要成功路径。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertDirectLiveFailureStillWritesEvidenceAndFails',
+    reason:
+      'Pingora 切换证据包自测必须覆盖 direct live 失败时保留证据并失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertDirectLiveParseFailureWritesParseErrorEvidence',
+    reason:
+      'Pingora 切换证据包自测必须覆盖 direct live stdout 解析失败时保留 parse error 证据。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertSnapshotParseFailureWritesParseErrorEvidence',
+    reason:
+      'Pingora 切换证据包自测必须覆盖 snapshot stdout 解析失败时保留 parse error 证据。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertRejectsSnapshotArgsWithControlCharacters',
+    reason:
+      'Pingora 切换证据包自测必须覆盖带控制字符的状态快照参数在执行前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertRejectsDirectLiveArgsWithControlCharacters',
+    reason:
+      'Pingora 切换证据包自测必须覆盖带控制字符的 direct live 参数在执行前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: '--direct-pingora-access-log 不能是文件系统根目录',
+    reason:
+      'Pingora 切换证据包自测必须覆盖 direct live access log 指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: '--direct-access-log-since-lines 不能包含换行或 NUL 字符',
+    reason:
+      'Pingora 切换证据包自测必须覆盖 direct live access log tail 行数带控制字符的负例。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'BUNDLE_DIR_MODE = 0o750',
+    reason: 'Pingora 切换证据包目录必须显式限制为 owner/group 可读。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'EVIDENCE_FILE_MODE = 0o640',
+    reason: 'Pingora 切换证据文件必须显式禁止 world-readable。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: "flag: 'wx'",
+    reason: 'Pingora 切换证据包写文件必须避免覆盖既有证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'validatePhase(config.phase);',
+    reason: 'Pingora 切换证据包必须拒绝不安全 phase，避免目录名和 manifest 阶段漂移。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'validateOutputRootForWriting(outputRoot);',
+    reason:
+      'Pingora 切换证据包写入前必须复核 output-root 路径，避免写入软链或非目录。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--output-root 不能是符号链接',
+    reason: 'Pingora 切换证据包必须拒绝符号链接 output-root。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--output-root 已存在但不是目录',
+    reason: 'Pingora 切换证据包必须拒绝已存在但不是目录的 output-root。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '不能是文件系统根目录',
+    reason: 'Pingora 切换证据包必须拒绝把显式路径参数指到 /。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'parseRequiredPositiveInt',
+    reason: 'Pingora 切换证据包 timeout 参数必须严格校验，不能静默回默认值。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '必须是布尔值 true/false 或 1/0',
+    reason:
+      'Pingora 切换证据包布尔 env 必须严格校验，避免证据生成开关拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertRejectsUnsafePhase',
+    reason: 'Pingora 切换证据包自测必须覆盖不安全 phase 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertBundleRedactsProbeTokensFromArtifacts',
+    reason: 'Pingora 切换证据包自测必须确认所有证据文件不落盘 probe token 原文。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertMode',
+    reason: 'Pingora 切换证据包自测必须断言目录和文件权限。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertRejectsInvalidTimeout',
+    reason: 'Pingora 切换证据包自测必须覆盖非法 timeout 参数和 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertRejectsInvalidBoolEnv',
+    reason: 'Pingora 切换证据包自测必须覆盖非法布尔 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertRejectsSymlinkOutputRootBeforeSnapshot',
+    reason:
+      'Pingora 切换证据包自测必须覆盖符号链接 output-root，且失败时不执行状态快照。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertRejectsFileOutputRootBeforeSnapshot',
+    reason:
+      'Pingora 切换证据包自测必须覆盖非目录 output-root，且失败时不执行状态快照。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertRejectsFilesystemRootPaths',
+    reason:
+      'Pingora 切换证据包自测必须覆盖显式路径参数指向文件系统根目录的负例。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--require-pingora-gateway',
+    reason: 'Pingora 切换证据包必须能透传发布物自审要求。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '只写 --output-root 下的新证据目录',
+    reason: 'Pingora 切换证据包必须明确不会修改 /etc、systemd、Nginx 或 Pingora。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: 'command.stdout.txt',
+    reason: 'Pingora 切换命令证据脚本必须保存真实命令 stdout。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: 'command.stderr.txt',
+    reason: 'Pingora 切换命令证据脚本必须保存真实命令 stderr。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: 'command-record.json',
+    reason: 'Pingora 切换命令证据脚本必须保存结构化命令记录。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: "createHash('sha256')",
+    reason: 'Pingora 切换命令证据 manifest 必须记录证据文件 sha256，便于归档后复核。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: 'sizeBytes',
+    reason: 'Pingora 切换命令证据 manifest 必须记录证据文件大小，便于归档后复核。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: 'redactSecrets(text',
+    reason: 'Pingora 切换命令证据脚本必须脱敏 stdout/stderr 中的 probe token。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: 'validateCommandPath(config.command);',
+    reason: 'Pingora 切换命令证据脚本必须拒绝非绝对路径真实命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: 'path.resolve(command) === path.parse(path.resolve(command)).root',
+    reason: 'Pingora 切换命令证据脚本必须拒绝文件系统根目录真实命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: '/[\\0\\r\\n]/u.test(command)',
+    reason: 'Pingora 切换命令证据脚本必须拒绝带换行或 NUL 的真实命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: '真实命令参数不能包含换行或 NUL 字符',
+    reason: 'Pingora 切换命令证据脚本必须拒绝带换行或 NUL 的真实命令参数。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: '--expected-executable',
+    reason: 'Pingora 切换命令证据脚本必须支持绑定预期真实命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: "validateSafeExecutablePath(config.expectedExecutable, '--expected-executable')",
+    reason: 'Pingora 切换命令证据生成端必须拒绝不安全 expected executable 路径。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: '--require-arg',
+    reason: 'Pingora 切换命令证据脚本必须支持执行前校验真实命令必需参数。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: '真实命令与 --expected-executable 不一致',
+    reason: 'Pingora 切换命令证据脚本必须拒绝挂错真实执行脚本。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: '真实命令参数缺少 --require-arg 要求',
+    reason: 'Pingora 切换命令证据脚本必须在执行前拒绝缺少必需参数的真实命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    includes: "validateNoControlCharacters(config.outputRoot, '--output-root')",
+    reason:
+      'Pingora 切换命令证据脚本必须拒绝带换行或 NUL 的 output-root。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertCommandFailureStillWritesEvidenceAndFails',
+    reason: 'Pingora 切换命令证据自测必须覆盖真实命令失败时仍保留证据。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsMissingRequiredArgBeforeCommand',
+    reason: 'Pingora 切换命令证据自测必须覆盖缺少 --apply 时执行前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsBareCommandName',
+    reason: 'Pingora 切换命令证据自测必须覆盖 PATH 裸命令名被拒绝。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsFilesystemRootCommand',
+    reason: 'Pingora 切换命令证据自测必须覆盖文件系统根目录真实命令被拒绝。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsOutputRootWithControlCharacters',
+    reason: 'Pingora 切换命令证据自测必须覆盖 output-root 带控制字符的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsCommandWithControlCharacters',
+    reason: 'Pingora 切换命令证据自测必须覆盖带控制字符真实命令被拒绝。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsCommandArgWithControlCharacters',
+    reason: 'Pingora 切换命令证据自测必须覆盖带控制字符真实命令参数被拒绝。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsFilesystemRootExpectedExecutable',
+    reason: 'Pingora 切换命令证据自测必须覆盖 expected executable 指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsExpectedExecutableWithControlCharacters',
+    reason: 'Pingora 切换命令证据自测必须覆盖 expected executable 带控制字符的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertCommandEvidenceRedactsProbeTokensFromArtifacts',
+    reason: 'Pingora 切换命令证据自测必须覆盖 token 不落盘。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertManifestFileMetadata',
+    reason: 'Pingora 切换命令证据自测必须覆盖 manifest 文件大小与 sha256 元数据。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsSymlinkOutputRootBeforeCommand',
+    reason: 'Pingora 切换命令证据自测必须覆盖符号链接 output-root 且失败时不执行真实命令。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-command-evidence.mjs',
+    includes: 'assertRejectsMismatchedExpectedExecutableBeforeCommand',
+    reason: 'Pingora 切换命令证据自测必须覆盖 expected executable 不匹配且失败时不执行真实命令。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol.mjs',
+    includes: 'assertPingoraDirectModeChecksPingoraServiceAndPublicHost',
+    reason:
+      '生产健康巡检动态烟测必须覆盖 Pingora 直连模式和 public Host header。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol.mjs',
+    includes: 'assertRejectsInvalidTimeoutAndSlowThreshold',
+    reason:
+      '生产健康巡检动态烟测必须覆盖非法 timeout 和慢请求阈值负例。',
+  },
+  {
+    file: 'scripts/ops/production-health-patrol.mjs',
+    includes: '必须是布尔值 true/false 或 1/0',
+    reason:
+      '生产健康巡检布尔 env 必须严格校验，避免 fail-on-warning / skip-journal 拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol.mjs',
+    includes: 'assertRejectsInvalidBoolEnv',
+    reason: '生产健康巡检动态烟测必须覆盖非法布尔 env 负例。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol-env.mjs',
+    includes: 'Pingora direct 模式使用本机 public base URL 时必须配置 GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST',
+    reason:
+      '生产健康巡检 env 复核必须阻断直连后本机探测缺少正式 Host 的配置。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol-env.mjs',
+    includes: '必须是布尔值 true/false 或 1/0',
+    reason:
+      '生产健康巡检 env 复核布尔 env 必须严格校验，避免 require-empty-public-host 拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol-env.mjs',
+    includes: 'isFilesystemRootPath',
+    reason: '生产健康巡检 env 复核必须显式拒绝把 env 文件指到 /。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol-env-check.mjs',
+    includes: 'assertRejectsPingoraDirectLoopbackWithoutHost',
+    reason:
+      '生产健康巡检 env 自测必须覆盖 Pingora direct loopback 缺 Host 负例。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol-env-check.mjs',
+    includes: 'assertRejectsInvalidBoolEnv',
+    reason: '生产健康巡检 env 自测必须覆盖非法布尔 env 负例。',
+  },
+  {
+    file: 'scripts/check-production-health-patrol-env-check.mjs',
+    includes: 'assertRejectsInvalidEnvFilePaths',
+    reason: '生产健康巡检 env 自测必须覆盖相对路径和 / 路径负例。',
+  },
+  {
+    file: 'deploy/logrotate/genarrative-pingora-gateway',
+    includes: '/var/log/genarrative/pingora-gateway.access.log',
+    reason:
+      'Pingora access log 必须有 logrotate 模板，避免 canary 日志无限增长。',
+  },
   {
     file: 'deploy/systemd/genarrative-health-patrol.timer',
     includes: 'genarrative-health-patrol.service',
     reason: '健康巡检 timer 必须绑定巡检 service。',
   },
+  {
+    file: 'deploy/systemd/genarrative-pingora-gateway.service',
+    includes: '/var/log/genarrative',
+    reason: 'Pingora systemd 沙箱必须允许写入 access log 目录。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-pingora-gateway.service',
+    includes: '影子网关只监听本机高端口',
+    reason:
+      'Pingora 主 service 必须保持默认 shadow 口径，不能默认声明公网直连。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-pingora-gateway.service',
+    excludes: 'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    reason:
+      'Pingora 主 service 不能默认带低端口 capability，直连只能通过显式 drop-in 启用。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    includes: 'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    reason: 'Pingora 直连 80/443 时必须通过显式 drop-in 授予低端口绑定能力。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    includes: 'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+    reason: 'Pingora 直连 drop-in 必须把 capability 边界限制为低端口绑定。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    includes:
+      '/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf',
+    reason: 'Pingora 直连 drop-in 必须明确人工启用位置，不能被误认为默认生效。',
+  },
+  {
+    file: 'deploy/nginx/snippets/genarrative-pingora-canary.conf',
+    includes: 'X-Genarrative-Nginx-Handoff',
+    reason:
+      'Pingora canary snippet 必须带明确响应头，方便验证 Nginx 已经切到 Pingora handoff。',
+  },
+  {
+    file: 'deploy/nginx/snippets/genarrative-pingora-canary.conf',
+    includes: 'deny all',
+    reason:
+      'Pingora canary snippet 默认必须限制访问来源，避免误 include 后公开接流。',
+  },
+  {
+    file: 'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    includes: 'listen 127.0.0.1:18083;',
+    reason:
+      'Pingora 真实路径 canary 必须默认只监听本机端口，避免误 include 后公开接流。',
+  },
+  {
+    file: 'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    includes: 'genarrative-pingora-realpath-canary.access.log',
+    reason:
+      'Pingora 真实路径 canary 必须使用独立 Nginx access log，避免和生产真实路径请求混淆。',
+  },
+  {
+    file: 'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    includes: 'pingora-realpath-canary',
+    reason:
+      'Pingora 真实路径 canary 必须带独立 handoff 标识，方便区分前缀 canary。',
+  },
+  {
+    file: 'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+    includes: 'location = /api/creation-entry/config',
+    reason:
+      'Pingora 真实路径 canary 必须覆盖代表性 API 真实路径。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'zz-genarrative-pingora-realpath-canary.conf',
+    reason:
+      'Pingora 真实路径 canary 运维说明必须记录 conf.d 加载顺序，避免早于 log_format 定义加载。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'unknown log format "genarrative_upstream"',
+    reason:
+      'Pingora 试点文档必须记录 realpath canary 的 Nginx log_format 加载顺序踩坑。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: 'Pingora realpath canary include 要晚于 log_format',
+    reason:
+      '团队共享踩坑必须记录 realpath canary 独立 server 在 conf.d 中的加载顺序要求。',
+  },
   {
     file: 'scripts/jenkins-server-provision.sh',
     includes: 'genarrative-health-patrol.timer',
     reason: 'Server-Provision 必须安装并启用健康巡检 timer。',
   },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: 'genarrative-pingora-canary.conf',
+    reason:
+      'Server-Provision 必须安装 Pingora canary snippet，供人工启用 Nginx handoff。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: 'genarrative-pingora-realpath-canary.conf',
+    reason:
+      'Server-Provision 必须安装 Pingora 真实路径 canary snippet，供人工启用直连前中间验证。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes: 'genarrative-pingora-gateway',
+    reason: 'Server-Provision 必须安装 Pingora access log 的 logrotate 配置。',
+  },
+  {
+    file: 'scripts/jenkins-server-provision.sh',
+    includes:
+      '/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf',
+    reason:
+      'Server-Provision 必须只把 Pingora 直连 drop-in 安装为人工启用模板。',
+  },
   {
     file: 'scripts/jenkins-server-provision.sh',
     includes: 'genarrative-external-generation-controller.service',
@@ -68,33 +1002,5325 @@ const checks = [
     includes: 'production-health-patrol.mjs',
     reason: '生产 API release 必须携带健康巡检脚本。',
   },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/ops/pingora-current-release-audit.mjs',
+    reason: '生产 API release 必须携带 Pingora current release 自审脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    reason: '生产 API release 必须携带 Pingora 直连彩排状态脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    reason: '生产 API release 必须携带 Pingora 切换状态快照脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    reason: '生产 API release 必须携带 Pingora 切换证据包脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    reason: '生产 API release 必须携带 Pingora 切换命令证据脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'check-production-health-patrol-env.mjs',
+    reason: '生产 API release 必须携带健康巡检 env 复核脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'check-pingora-release-readiness.mjs',
+    reason:
+      '生产 API release 必须携带 Pingora release readiness 聚合门禁脚本，确保正式 runbook 不依赖源码 checkout。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'check-pingora-canary-live.mjs',
+    reason: '生产 API release 必须携带 Pingora canary live smoke 脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'check-pingora-canary-access-log-parity.mjs',
+    reason: '生产 API release 必须携带 Pingora canary access log 对账脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: '--include-pingora-gateway',
+    reason: 'Pingora 影子网关必须保持显式可选产物打包入口。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'require_pingora_build_toolchain',
+    reason: '显式构建 Pingora 影子网关时必须先检查 cmake 和 C/C++ 编译器。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'require_command cmake',
+    reason: 'Pingora release 构建必须对 cmake 缺失 fail-fast。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'require_any_command "C++ 编译器"',
+    reason: 'Pingora release 构建必须对 C++ 编译器缺失 fail-fast。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/deploy/production-api-deploy.sh',
+    reason: '生产 API release 必须携带随产物执行的 API deploy 脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes:
+      '同目录的 \\`maintenance-on.sh\\` / \\`maintenance-off.sh\\` 必须来自同一发布包',
+    reason:
+      '生产 API release README 必须说明 deploy 同目录维护脚本来自同一发布包。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/deploy/maintenance-on.sh',
+    reason: '生产 API release 必须在 deploy 脚本同目录携带 maintenance-on.sh。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/deploy/maintenance-off.sh',
+    reason:
+      '生产 API release 必须在 deploy 脚本同目录携带 maintenance-off.sh。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/deploy/pingora-direct-rollback.sh',
+    reason: '生产 API release 必须携带 Pingora 直连回退脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/deploy/pingora-realpath-canary-enable.sh',
+    reason: '生产 API release 必须携带 Pingora realpath canary 启用脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/deploy/pingora-realpath-canary-disable.sh',
+    reason: '生产 API release 必须携带 Pingora realpath canary 关闭脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason: '生产 API release 必须携带 Pingora health patrol env 切换脚本。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--health-patrol-expected-public-base-url',
+    reason:
+      'Pingora 直连回退脚本必须能复核 health patrol public base URL 已恢复为切换前记录值。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--health-patrol-expected-public-host',
+    reason:
+      'Pingora 直连回退脚本必须能复核切换前存在的 health patrol public Host 覆盖。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/deploy/pingora-direct-enable.sh',
+    reason: '生产 API release 必须携带 Pingora 直连启用脚本。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/check-pingora-direct-preflight.mjs',
+    reason:
+      '生产 API release 必须携带 Pingora 直连预检脚本，确保 current release 可独立执行直连启用。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'scripts/check-pingora-direct-live.mjs',
+    reason:
+      '生产 API release 必须携带 Pingora 直连 live smoke 脚本，确保启用脚本 apply 后可独立验收。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'deploy/pingora',
+    reason:
+      '生产 API release 必须携带 Pingora 配置目录，供直连预检读取 env 示例和路由矩阵。',
+  },
+  {
+    file: 'scripts/build-production-release.sh',
+    includes: 'deploy/env',
+    reason:
+      '生产 API release 必须携带 env 示例目录，供健康巡检和 Pingora live smoke 复制配置。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'ENV_DEPLOY_DIR_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 env 示例目录到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'PINGORA_CANARY_LIVE_SCRIPT_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 Pingora canary live smoke 脚本到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'PINGORA_REALPATH_CANARY_ENABLE_SCRIPT_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 Pingora realpath canary 启用脚本到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'PINGORA_REALPATH_CANARY_DISABLE_SCRIPT_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 Pingora realpath canary 关闭脚本到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '发布产物缺少 Pingora realpath canary 启用脚本',
+    reason: 'API deploy 缺少 realpath canary 启用脚本时必须 fail-fast。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '发布产物缺少 Pingora realpath canary 关闭脚本',
+    reason: 'API deploy 缺少 realpath canary 关闭脚本时必须 fail-fast。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'PINGORA_CURRENT_RELEASE_AUDIT_SCRIPT_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 Pingora current release 自审脚本。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'PINGORA_DIRECT_REHEARSAL_STATUS_SCRIPT_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 Pingora 直连彩排状态脚本。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'PINGORA_CUTOVER_STATUS_SNAPSHOT_SCRIPT_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 Pingora 切换状态快照脚本。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'PINGORA_CUTOVER_EVIDENCE_BUNDLE_SCRIPT_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 Pingora 切换证据包脚本。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'PINGORA_CUTOVER_COMMAND_EVIDENCE_SCRIPT_SOURCE',
+    reason: 'API deploy 必须从发布产物复制 Pingora 切换命令证据脚本。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'deploy/env/health-patrol.env.example',
+    reason: 'API release 动态烟测必须断言健康巡检 env 示例随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/ops/pingora-current-release-audit.mjs',
+    reason: 'API release 动态烟测必须断言 Pingora current release 自审脚本随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/ops/pingora-direct-rehearsal-status.mjs',
+    reason: 'API release 动态烟测必须断言 Pingora 直连彩排状态脚本随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    reason: 'API release 动态烟测必须断言 Pingora 切换状态快照脚本随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    reason: 'API release 动态烟测必须断言 Pingora 切换证据包脚本随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    reason: 'API release 动态烟测必须断言 Pingora 切换命令证据脚本随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/check-production-health-patrol-env.mjs',
+    reason: 'API release 动态烟测必须断言健康巡检 env 复核脚本随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/pingora-realpath-canary-enable.sh',
+    reason: 'API release 动态烟测必须断言 Pingora realpath canary 启用脚本随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/pingora-realpath-canary-disable.sh',
+    reason: 'API release 动态烟测必须断言 Pingora realpath canary 关闭脚本随包发布。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'deploy/env/health-patrol.env.example',
+    reason:
+      'API deploy 动态烟测必须断言健康巡检 env 示例复制到 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/ops/pingora-current-release-audit.mjs',
+    reason:
+      'API deploy 动态烟测必须断言 Pingora current release 自审脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    reason:
+      'API deploy 动态烟测必须断言 Pingora 切换状态快照脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    reason:
+      'API deploy 动态烟测必须断言 Pingora 切换证据包脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    reason:
+      'API deploy 动态烟测必须断言 Pingora 切换命令证据脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/deploy/pingora-realpath-canary-enable.sh',
+    reason:
+      'API deploy 动态烟测必须断言 Pingora realpath canary 启用脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/deploy/pingora-realpath-canary-disable.sh',
+    reason:
+      'API deploy 动态烟测必须断言 Pingora realpath canary 关闭脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingPingoraRealpathCanaryEnableFails',
+    reason:
+      'API deploy 动态烟测必须覆盖缺少 Pingora realpath canary 启用脚本时 fail-fast。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingPingoraRealpathCanaryDisableFails',
+    reason:
+      'API deploy 动态烟测必须覆盖缺少 Pingora realpath canary 关闭脚本时 fail-fast。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingPingoraCutoverCommandEvidenceFails',
+    reason:
+      'API deploy 动态烟测必须覆盖缺少 Pingora 切换命令证据脚本时 fail-fast。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingHealthPatrolEnvCheckFails',
+    reason:
+      'API deploy 动态烟测必须覆盖缺少健康巡检 env 复核脚本时 fail-fast。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingEnvExamplesFails',
+    reason: 'API deploy 动态烟测必须覆盖缺少 env 示例目录时 fail-fast。',
+  },
+  {
+    file: 'package.json',
+    includes: 'deploy:pingora-direct-enable',
+    reason: 'Pingora 直连启用必须保留可重复执行的 npm 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-realpath-canary-toggle',
+    reason: 'Pingora realpath canary 启停脚本必须有本地自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'deploy:pingora-realpath-canary-enable',
+    reason: 'Pingora realpath canary 启用必须保留可重复执行的 npm 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'deploy:pingora-realpath-canary-disable',
+    reason: 'Pingora realpath canary 关闭必须保留可重复执行的 npm 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'deploy:pingora-direct-rollback',
+    reason: 'Pingora 直连回退必须保留可重复执行的 npm 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-gateway-smoke',
+    reason: 'Pingora 网关必须保留可重复本地 smoke 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:nginx-pingora-canary',
+    reason: 'Pingora Nginx canary snippet 必须保留可重复本地校验入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-route-parity',
+    reason: 'Pingora 与 Nginx 路由矩阵必须保留可重复本地校验入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-canary-live',
+    reason: 'Pingora Nginx 前缀 canary 必须保留启用后的真实入口 smoke。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-direct-live',
+    reason: 'Pingora 直连 HTTPS / HTTP redirect 必须保留目标机 live smoke。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-direct-live-guard',
+    reason:
+      'Pingora direct live 参数护栏必须保留单独 npm 入口，方便正式切换前聚合门禁和本地 focused 验证复用。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-direct-preflight',
+    reason: 'Pingora 直连切换前必须保留目标机 env / systemd / 端口预检入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-direct-enable',
+    reason: 'Pingora 直连启用必须保留可重复 dry-run 行为检查入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-direct-rollback',
+    reason: 'Pingora 直连回退必须保留可重复 dry-run 行为检查入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-canary-docker',
+    reason: 'Pingora Nginx handoff 必须保留本机 Docker 可复现 smoke。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-production-release-build',
+    reason: 'Pingora release 真实构建烟测必须保留可重复 npm 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-release-readiness',
+    reason: 'Pingora 正式切换前必须保留聚合门禁入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'plan:pingora-direct-cutover',
+    reason: 'Pingora 直连切换必须保留可审阅 runbook 计划入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-release-readiness-plan',
+    reason: 'Pingora 聚合门禁计划必须有可重复自检入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:production-api-release',
+    reason: 'API release build 动态烟测必须保留可重复 npm 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:production-health-patrol',
+    reason: '生产健康巡检动态烟测必须保留可重复 npm 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:production-health-patrol-env',
+    reason: '生产健康巡检 env 复核动态烟测必须保留可重复 npm 入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-health-patrol-env-switch',
+    reason: 'Pingora health patrol env 切换脚本必须保留可重复 npm 自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-gateway-env-shadow-switch',
+    reason: 'Pingora gateway env shadow 切换脚本必须保留可重复 npm 自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-current-release-audit',
+    reason: 'Pingora current release 自审必须保留可重复 npm 自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-direct-rehearsal-status',
+    reason: 'Pingora 直连彩排状态脚本必须保留可重复 npm 自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-cutover-status-snapshot',
+    reason: 'Pingora 切换状态快照脚本必须保留可重复 npm 自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-cutover-evidence-bundle',
+    reason: 'Pingora 切换证据包必须保留可重复 npm 自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-cutover-command-evidence',
+    reason: 'Pingora 切换命令证据必须保留可重复 npm 自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-canary-access-log-parity',
+    reason: 'Pingora canary access log 对账必须保留可重复 npm 自测入口。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-canary-live-guard',
+    reason:
+      'Pingora canary live 参数护栏必须保留单独 npm 入口，方便正式切换前 focused 验证复用。',
+  },
+  {
+    file: 'package.json',
+    includes: 'check:production-api-deploy',
+    reason: 'API deploy 动态烟测必须保留可重复 npm 入口。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:production-api-release',
+    reason: 'Pingora 聚合门禁必须执行 API release build 动态烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-production-release-build',
+    reason: 'Pingora 聚合门禁必须执行真实 Pingora release 构建烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'Pingora production release 真实构建烟测',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖真实 release 构建烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-production-release-build.mjs',
+    includes: '--include-pingora-gateway',
+    reason: 'Pingora production release 构建烟测必须走真实 include 打包路径。',
+  },
+  {
+    file: 'scripts/check-pingora-production-release-build.mjs',
+    includes: 'CARGO_TARGET_DIR',
+    reason: 'Pingora production release 构建烟测必须使用临时 target，避免污染本地默认 target。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:production-api-deploy',
+    reason: 'Pingora 聚合门禁必须执行 API deploy 动态烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'redactSecretArgs(args).join',
+    reason: 'Pingora 聚合门禁真实执行日志必须隐藏 probe token 参数值。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertRunStepLogRedactsDirectProbeToken',
+    reason: 'Pingora 聚合门禁计划自测必须覆盖真实执行日志 token 脱敏。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:production-health-patrol',
+    reason: 'Pingora 聚合门禁必须执行生产健康巡检动态烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:production-health-patrol-env',
+    reason: 'Pingora 聚合门禁必须执行生产健康巡检 env 动态烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-health-patrol-env-switch',
+    reason: 'Pingora 聚合门禁必须执行 health patrol env 切换脚本烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-gateway-env-shadow-switch',
+    reason: 'Pingora 聚合门禁必须执行 gateway env shadow 切换脚本烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-current-release-audit',
+    reason: 'Pingora 聚合门禁必须执行 current release 自审烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-direct-rehearsal-status',
+    reason: 'Pingora 聚合门禁必须执行直连彩排状态烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-cutover-status-snapshot',
+    reason: 'Pingora 聚合门禁必须执行切换状态快照烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-cutover-evidence-bundle',
+    reason: 'Pingora 聚合门禁必须执行切换证据包烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-cutover-command-evidence',
+    reason: 'Pingora 聚合门禁必须执行切换命令证据烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'scripts/ops/pingora-cutover-command-evidence.mjs',
+    reason: 'Pingora cutover runbook apply 步骤必须使用 current release 随包命令证据脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--expected-executable',
+    reason: 'Pingora cutover runbook apply 步骤必须把命令证据绑定到预期 current release 脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-arg',
+    reason: 'Pingora cutover runbook apply 步骤必须让命令证据脚本提前校验 --apply 参数。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'pingora-direct-rollback-apply',
+    reason: 'Pingora runbook 自检必须确认 rollback apply 被命令证据脚本归档。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '必须在命令证据脚本中要求真实命令参数',
+    reason: 'Pingora runbook 自检必须锁住命令证据脚本的 --apply 早失败参数。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'pingora-direct-enable-apply',
+    reason: 'Pingora runbook 自检必须确认 enable apply 被命令证据脚本归档。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用命令证据 manifest 只读验真',
+    reason: 'Pingora cutover runbook 必须在 enable apply 命令证据生成后立即验真 manifest。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '<enable-apply-bundle-dir>',
+    reason: 'Pingora cutover runbook 必须提示用 enable apply 命令证据 bundleDir 执行即时验真。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-summary-ok',
+    reason: 'Pingora cutover runbook 的即时证据验真必须要求 manifest.summary.status 为 OK。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '回退命令证据 manifest 只读验真',
+    reason: 'Pingora cutover runbook 必须在 rollback apply 命令证据生成后立即验真 manifest。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '<rollback-apply-bundle-dir>',
+    reason: 'Pingora cutover runbook 必须提示用 rollback apply 命令证据 bundleDir 执行即时验真。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '启用命令证据验真必须使用 current release 随包 verifier',
+    reason: 'Pingora runbook 自检必须锁住 enable apply 命令证据即时验真脚本来源。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '回退命令证据验真必须使用 current release 随包 verifier',
+    reason: 'Pingora runbook 自检必须锁住 rollback apply 命令证据即时验真脚本来源。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 必须先验真 enable apply 命令证据，再切换 health patrol 到 pingora-direct',
+    reason: 'Pingora runbook 自检必须锁住 enable apply 命令证据即时验真的执行顺序。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 必须先验真 rollback apply 命令证据，再执行回退后 env 复核',
+    reason: 'Pingora runbook 自检必须锁住 rollback apply 命令证据即时验真的执行顺序。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-canary-access-log-parity',
+    reason: 'Pingora 聚合门禁必须执行 canary access log 对账烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'scripts/check-pingora-canary-live-guard.mjs',
+    reason:
+      'Pingora 聚合门禁必须执行 canary live 参数护栏，避免正式切换前漏掉脚本输入污染负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'Pingora canary access log 对账烟测',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖 canary access log 对账烟测。',
+  },
+  {
+    file: 'scripts/check-pingora-health-patrol-env-switch.mjs',
+    includes: '复核失败时 apply 不应写入真实 health patrol env 文件',
+    reason: 'Pingora health patrol env 切换脚本自测必须覆盖复核失败不落盘。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: '必须是布尔值 true/false 或 1/0',
+    reason:
+      'Pingora health patrol env 切换脚本布尔 env 必须严格校验，避免 clear-public-host 拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/check-pingora-health-patrol-env-switch.mjs',
+    includes: 'assertRejectsInvalidBoolEnv',
+    reason:
+      'Pingora health patrol env 切换脚本自测必须覆盖非法布尔 env 负例。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: 'DRY_RUN_ENV_FILE_MODE = 0o600',
+    reason: 'Pingora health patrol env 切换脚本的临时复核 env 必须显式限制为 0600。',
+  },
+  {
+    file: 'scripts/check-pingora-health-patrol-env-switch.mjs',
+    includes: 'assertDryRunEnvFileModeIsPrivate',
+    reason: 'Pingora health patrol env 切换脚本自测必须动态验证临时复核 env 权限。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: 'runHealthPatrolEnvCheck(checkFile);',
+    reason: 'Pingora health patrol env 切换脚本必须先复核临时目标 env。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: 'writeEnvFileAtomically(config.envFile, nextText);',
+    reason: 'Pingora health patrol env 切换脚本只能在复核通过后原子写入真实 env。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: 'chownSync(tempFile, currentStat.uid, currentStat.gid);',
+    reason:
+      'Pingora health patrol env 切换脚本原子替换真实 env 时必须保留 owner/group。',
+  },
+  {
+    file: 'scripts/check-pingora-health-patrol-env-switch.mjs',
+    includes: 'assertApplyPreservesEnvFileModeAndOwnership',
+    reason:
+      'Pingora health patrol env 切换脚本自测必须覆盖 apply 保留 mode 与 owner/group。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: '--env-file 不能是符号链接',
+    reason:
+      'Pingora health patrol env 切换脚本 apply 必须拒绝符号链接 env，避免替换链接或写入非预期目标。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: 'isFilesystemRootPath',
+    reason: 'Pingora health patrol env 切换脚本必须显式拒绝把路径参数指到 /。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: '--check-script 不能是文件系统根目录',
+    reason: 'Pingora health patrol env 切换脚本必须拒绝把复核脚本路径指到 /。',
+  },
+  {
+    file: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    includes: 'function validateNoControlCharacters(value, label)',
+    reason:
+      'Pingora health patrol env 切换脚本必须拒绝 env 路径、check script、public URL 和 Host 中的换行 / NUL。',
+  },
+  {
+    file: 'scripts/check-pingora-health-patrol-env-switch.mjs',
+    includes: 'assertApplyRejectsSymlinkEnvFileBeforeWrite',
+    reason:
+      'Pingora health patrol env 切换脚本自测必须覆盖符号链接 env 被拒绝且不写目标文件。',
+  },
+  {
+    file: 'scripts/check-pingora-health-patrol-env-switch.mjs',
+    includes: 'assertRejectsFilesystemRootPaths',
+    reason: 'Pingora health patrol env 切换脚本自测必须覆盖路径参数指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-health-patrol-env-switch.mjs',
+    includes: 'assertRejectsControlCharacterInputsBeforeWrite',
+    reason:
+      'Pingora health patrol env 切换脚本自测必须覆盖控制字符参数在 apply 写入前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-env-shadow-switch.mjs',
+    includes: 'assertApplyRestoresShadowAndPreservesOtherKeys',
+    reason: 'Pingora gateway env shadow 切换脚本自测必须覆盖恢复 shadow 并保留其它键。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_LISTEN: \'127.0.0.1:18081\'',
+    reason: 'Pingora gateway env shadow 切换脚本必须固定恢复 shadow 高端口监听。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: \'\'',
+    reason: 'Pingora gateway env shadow 切换脚本必须清空 TLS 低端口监听。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: \'\'',
+    reason: 'Pingora gateway env shadow 切换脚本必须清空 HTTP redirect 低端口监听。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: \'\'',
+    reason:
+      'Pingora gateway env shadow 切换脚本必须清空 TLS cert，避免回退后形成不完整 TLS 配置。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: \'\'',
+    reason:
+      'Pingora gateway env shadow 切换脚本必须清空 TLS key，避免回退后形成不完整 TLS 配置。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'assertShadowEnv(checkFile);',
+    reason: 'Pingora gateway env shadow 切换脚本必须先复核临时目标 env。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'writeEnvFileAtomically(config.envFile, nextText);',
+    reason: 'Pingora gateway env shadow 切换脚本只能在复核通过后原子写入真实 env。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-env-shadow-switch.mjs',
+    includes: 'assertRejectsSymlinkEnvFileBeforeWrite',
+    reason: 'Pingora gateway env shadow 切换脚本自测必须覆盖符号链接 env 被拒绝。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--release-runtime-only',
+    reason:
+      'Pingora release readiness 必须支持 current release 包内运行时复核模式，避免目标机依赖源码 checkout。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'buildReleaseRuntimeSteps',
+    reason: 'Pingora release runtime-only 模式必须单独构建包内自包含检查步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'releaseScriptPath',
+    reason: 'Pingora release runtime-only 模式必须从 current release 解析随包脚本绝对路径。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-live',
+    reason: 'Pingora 正式切换聚合门禁必须支持目标机 live canary 强制验收。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-live 时必须提供 --live-host',
+    reason: 'Pingora 强制 live canary 门禁不能跳过正式域名 Host header 验证。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '目标 Nginx live canary access log 对账',
+    reason: 'Pingora 强制 live canary 门禁必须在 live smoke 后执行真实 access log 对账。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--live-nginx-access-log',
+    reason: 'Pingora 强制 live canary 门禁必须允许显式指定 Nginx access log。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--live-pingora-access-log',
+    reason: 'Pingora 强制 live canary 门禁必须允许显式指定 Pingora access log。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'validateSafeAbsoluteFilePath(filePath, label);',
+    reason:
+      'Pingora release readiness 的 live/direct 文件路径必须统一拒绝相对路径和文件系统根目录。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertReleaseRuntimeOnlyPlanUsesCurrentReleaseScripts',
+    reason: 'Pingora release readiness plan 自测必须覆盖 runtime-only 使用 current release 随包脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertReleaseRuntimeOnlyRejectsSourceOnlyFlags',
+    reason: 'Pingora release readiness plan 自测必须覆盖 runtime-only 拒绝源码/本机依赖参数。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-live 计划必须在 live smoke 后包含 access log 对账',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖 live smoke 后真实日志对账。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-live 的 Nginx access log 不能接受相对路径',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖 live 日志路径负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertRequireLiveRejectsFilesystemRootAccessLog',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 live 日志路径指向文件系统根目录的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-direct',
+    reason: 'Pingora 正式切换聚合门禁必须支持目标机直连入口强制验收。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--dry-run-cutover',
+    reason: 'Pingora 正式直连切换必须支持只打印可审阅 runbook。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '切换 Host 一致性确认',
+    reason: 'Pingora cutover runbook 必须输出 Host 一致性确认步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'assertSameCutoverHostname',
+    reason: 'Pingora cutover runbook 必须在生成阶段阻断 Host 漂移。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--rollback-pingora-shadow-probe-url',
+    reason: 'Pingora cutover runbook 必须支持把可选 shadow probe 参数传给 rollback。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--rollback-health-patrol-public-base-url',
+    reason:
+      'Pingora cutover runbook 必须显式声明回退后恢复的 Nginx public base URL。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '避免回退 runbook 覆盖现场原有 Nginx 巡检入口',
+    reason:
+      'Pingora cutover runbook 不能把回退后的 health patrol public base URL 隐式写成仓库默认值。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '<redacted>',
+    reason: 'Pingora cutover runbook 输出不能泄露 probe token 原文。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'Pingora direct enable apply',
+    reason: 'Pingora cutover runbook 必须显式列出 direct enable apply 步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'Pingora direct rollback apply',
+    reason: 'Pingora cutover runbook 必须显式列出失败回退 apply 步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '切换后 health patrol 切到 Pingora direct',
+    reason:
+      'Pingora cutover runbook 必须提醒直连启用后把健康巡检切到 pingora-direct。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '回退前 health patrol 预置回 Nginx',
+    reason:
+      'Pingora cutover runbook 必须在 rollback apply 前提醒把健康巡检预置回 nginx。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '回退前 Pingora env 预置回 shadow',
+    reason:
+      'Pingora cutover runbook 必须在 rollback apply 前提醒把 Pingora env 预置回 shadow。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'Pingora cutover runbook 必须用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 回退前 Pingora gateway env shadow 切换必须显式带 --apply。',
+    reason:
+      'Pingora runbook 自检必须锁住 rollback apply 前 Pingora shadow env 脚本化预置步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'pingora-health-patrol-env-switch.mjs',
+    reason:
+      'Pingora cutover runbook 必须使用随包脚本切换 health patrol env，不能只给手工编辑提示。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '切换前 current release 自包含自审',
+    reason: 'Pingora cutover runbook 必须先审 current release 自包含能力。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '切换前状态快照',
+    reason:
+      'Pingora cutover runbook 必须在启用前采集只读状态快照。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '切换前状态快照证据包',
+    reason:
+      'Pingora cutover runbook 必须在启用前归档状态快照证据包。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--cutover-evidence-output-root',
+    reason: 'Pingora cutover runbook 必须显式固定证据包输出根目录。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用后状态快照',
+    reason:
+      'Pingora cutover runbook 必须在启用后采集只读状态快照。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--run-direct-live',
+    reason:
+      'Pingora cutover runbook 启用后证据包必须归档 direct live 和 access log request_id 证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '启用后状态快照证据包必须归档 direct live smoke 证据',
+    reason:
+      'Pingora runbook 自检必须锁住 post-enable 证据包的 direct live 归档。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '证据 manifest 只读验真',
+    reason: 'Pingora cutover runbook 必须在每个证据包阶段后提示只读验真。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '证据验真必须使用 current release 随包 verifier',
+    reason: 'Pingora runbook 自检必须锁住 current release 随包证据验真脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '证据验真必须要求 manifest.summary.status=OK',
+    reason: 'Pingora runbook 自检必须锁住即时证据验真的 summary OK 要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDryRunCutoverPlanAvoidsManualEvidenceEscapeHatches',
+    reason: 'Pingora runbook 自检必须确认正式切换计划不携带人工证据放行参数。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--allow-extra-root-entries',
+    reason: 'Pingora runbook 自检必须显式覆盖证据根目录额外条目放行参数不得进入正式计划。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: 'findExtraEvidenceEntries',
+    reason: 'Pingora 证据验真脚本必须扫描 manifest.files 未登记的额外条目。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: '--require-summary-ok',
+    reason: 'Pingora 证据验真脚本必须支持正式 runbook 的 summary OK 强制模式。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: 'manifest.summary.status is not OK',
+    reason: 'Pingora 证据验真脚本必须在 summary 非 OK 时给出结构化失败原因。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: 'extra file not registered in manifest.files',
+    reason: 'Pingora 证据验真脚本必须默认拒绝未登记普通文件。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: 'extra directory not registered in manifest.files',
+    reason: 'Pingora 证据验真脚本必须默认拒绝未登记目录。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: 'extra symlink not registered in manifest.files',
+    reason: 'Pingora 证据验真脚本必须默认拒绝未登记符号链接。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: '--allow-extra-files',
+    reason: 'Pingora 证据验真脚本允许额外条目时必须显式使用例外开关。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: '正式切换归档不应使用',
+    reason: 'Pingora 证据验真脚本必须声明额外条目例外不属于正式归档口径。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: 'validateNoControlCharacters',
+    reason:
+      'Pingora 证据验真脚本必须拒绝带换行或 NUL 的入口路径和 manifest 文件名。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-verify.mjs',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora 证据验真脚本必须对控制字符路径给出明确错误。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-verify.mjs',
+    includes: 'assertExtraFileFailsByDefault',
+    reason: 'Pingora 证据验真自测必须覆盖未登记普通文件默认失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-verify.mjs',
+    includes: 'assertExtraDirectoryFailsByDefault',
+    reason: 'Pingora 证据验真自测必须覆盖未登记目录默认失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-verify.mjs',
+    includes: 'assertExtraSymlinkFailsByDefault',
+    reason: 'Pingora 证据验真自测必须覆盖未登记符号链接默认失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-verify.mjs',
+    includes: 'assertAllowExtraFilesOverrideSucceeds',
+    reason: 'Pingora 证据验真自测必须覆盖显式允许额外条目的人工例外。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-verify.mjs',
+    includes: 'assertRequireSummaryOkFailsForCriticalManifest',
+    reason: 'Pingora 证据验真自测必须覆盖 summary 非 OK 时 --require-summary-ok 失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-verify.mjs',
+    includes: 'assertRequireSummaryOkFailsWhenSummaryMissing',
+    reason: 'Pingora 证据验真自测必须覆盖缺少 summary 时 --require-summary-ok 失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-verify.mjs',
+    includes: 'assertRejectsEntryPathControlCharacters',
+    reason: 'Pingora 证据验真自测必须覆盖入口路径带控制字符的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-verify.mjs',
+    includes: 'assertRejectsManifestFilePathControlCharacters',
+    reason: 'Pingora 证据验真自测必须覆盖 manifest 文件 path 带控制字符的负例。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'manifest.files` 视为闭集',
+    reason: 'Pingora 试点文档必须说明证据验真默认闭集归档口径。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: 'manifest.files` 视为闭集',
+    reason: '生产运维文档必须说明证据验真默认闭集归档口径。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: 'manifest.files` 视为闭集',
+    reason: '团队共享决策必须记录 Pingora 证据验真闭集归档口径。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: 'manifest.files` 视为闭集',
+    reason: '团队共享踩坑必须记录 Pingora 证据目录不能夹带未登记条目。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'pingora-gateway-env-shadow-switch.mjs --apply',
+    reason: 'Pingora 试点文档必须记录 rollback apply 前用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: 'pingora-gateway-env-shadow-switch.mjs --apply',
+    reason: '生产运维文档必须记录 rollback apply 前用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: 'pingora-gateway-env-shadow-switch.mjs --apply',
+    reason: '团队共享决策必须记录 rollback apply 前用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: 'pingora-gateway-env-shadow-switch.mjs --apply',
+    reason: '团队共享踩坑必须记录 rollback apply 前用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'Nginx README 的 API release 清单必须包含 Pingora gateway env shadow 切换脚本。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'rollback apply 前必须先执行',
+    reason: 'Nginx README 必须说明 rollback apply 前先恢复 Pingora gateway shadow env。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'TLS_CERT_FILE',
+    reason: 'Nginx README 必须说明 Pingora gateway shadow 回退会清空 TLS cert/key 路径。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--expected-pingora-env-mode direct',
+    reason: 'Nginx README 必须说明 post-enable 证据包会强制校验 Pingora env direct 姿态。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--expected-pingora-env-mode shadow',
+    reason: 'Nginx README 必须说明 post-rollback 证据包会强制校验 Pingora env shadow 姿态。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'manifest.summary.pingoraEnvShadow',
+    reason: 'Nginx README 必须说明证据 manifest 会提升 Pingora env shadow 摘要。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'tlsCertFile',
+    reason: 'Nginx README 必须说明 Pingora env shadow 摘要包含 TLS cert/key 残留字段。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'tlsCertFile',
+    reason: 'Pingora 试点文档必须说明证据摘要包含 TLS cert/key 残留字段。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '切换证据根目录三阶段总审计',
+    reason: 'Pingora cutover runbook 必须在三阶段证据后执行根目录总审计。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'enable-apply:pingora-direct-enable-apply',
+    reason:
+      'Pingora cutover runbook 总审计必须要求 direct enable apply 命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'rollback-apply:pingora-direct-rollback-apply',
+    reason:
+      'Pingora cutover runbook 总审计必须要求 direct rollback apply 命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'post-enable:pingora-health-patrol-direct-env-switch',
+    reason:
+      'Pingora cutover runbook 总审计必须要求 health patrol 切到 direct 的命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'rollback-prep:pingora-gateway-shadow-env-switch',
+    reason:
+      'Pingora cutover runbook 总审计必须要求回退前 Pingora gateway env shadow 切换命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'rollback-prep:pingora-health-patrol-nginx-env-switch',
+    reason:
+      'Pingora cutover runbook 总审计必须要求回退前 health patrol 切回 Nginx 的命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-phase-pingora-env-shadow',
+    reason:
+      'Pingora cutover runbook 总审计必须要求 post-rollback Pingora env shadow 证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '三阶段总审计必须使用 current release 随包 evidence audit 脚本',
+    reason: 'Pingora runbook 自检必须锁住 current release 随包证据根目录审计脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '三阶段总审计必须要求 post-rollback 阶段带 Pingora env shadow 摘要。',
+    reason:
+      'Pingora runbook 自检必须锁住总审计里的 post-rollback shadow env 证据要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '三阶段总审计必须显式要求真实切换命令证据',
+    reason: 'Pingora runbook 自检必须锁住总审计里的 enable / rollback 和 env 切换命令证据要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason:
+      'Pingora runbook 自检必须锁住 health patrol direct env 切换命令的真实脚本身份。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason:
+      'Pingora runbook 自检必须锁住 Pingora gateway shadow env 切换命令的真实脚本身份。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason:
+      'Pingora runbook 自检必须锁住 health patrol nginx env 切换命令的真实脚本身份。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-command-executable',
+    reason: 'Pingora cutover runbook 总审计必须要求真实切换命令证据的真实脚本身份。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '三阶段总审计必须显式要求真实切换脚本身份',
+    reason: 'Pingora runbook 自检必须锁住总审计里的真实切换命令脚本身份要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-command-arg',
+    reason: 'Pingora cutover runbook 总审计必须要求真实切换命令证据包含关键参数。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '三阶段总审计必须显式要求真实切换命令必需参数',
+    reason: 'Pingora runbook 自检必须锁住总审计里的真实切换命令参数要求。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: "commandName: 'pingora-health-patrol-direct-env-switch'",
+    reason:
+      'Pingora 证据根目录审计标准时间线必须包含 health patrol direct env 切换命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: "commandName: 'pingora-gateway-shadow-env-switch'",
+    reason:
+      'Pingora 证据根目录审计标准时间线必须包含 Pingora gateway shadow env 切换命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: "commandName: 'pingora-health-patrol-nginx-env-switch'",
+    reason:
+      'Pingora 证据根目录审计标准时间线必须包含 health patrol nginx env 切换命令。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: '完整切换时间线总审计必须检查三阶段和五条命令',
+    reason:
+      'Pingora 证据根目录审计自测必须把完整时间线固定为三阶段和五条命令。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--cutover-run-id',
+    reason: 'Pingora cutover runbook 必须公开并传递切换批次 ID。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-cutover-run-id',
+    reason: 'Pingora cutover runbook 最终总审计必须要求同一切换批次 ID。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDryRunCutoverPlanCarriesCutoverRunId',
+    reason: 'Pingora runbook 自检必须覆盖切换批次 ID 贯穿所有证据步骤。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '不会修改证据目录',
+    reason: 'Pingora 证据根目录审计脚本必须声明只读边界。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '--require-command <phase>:<commandName>',
+    reason: 'Pingora 证据根目录审计脚本必须支持强制审计切换命令证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '--require-command-executable <phase>:<commandName>:<absolutePath>',
+    reason: 'Pingora 证据根目录审计脚本必须支持强制审计切换命令真实脚本身份。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes:
+      '--require-command-executable executable 不能包含换行或 NUL 字符',
+    reason:
+      'Pingora 证据根目录审计脚本必须拒绝带控制字符的命令脚本身份要求。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'validateNoControlCharacters',
+    reason:
+      'Pingora 证据根目录审计脚本必须拒绝带换行或 NUL 的根目录和 verifier 路径。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '!/[\\0\\r\\n]/u.test(value)',
+    reason:
+      'Pingora 证据根目录审计脚本必须拒绝 manifest 文件名里的控制字符。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'command executable 带控制字符必须失败',
+    reason:
+      'Pingora 证据根目录审计自测必须覆盖命令脚本身份要求带控制字符的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: '证据根目录带控制字符必须失败',
+    reason: 'Pingora 证据根目录审计自测必须覆盖 evidence-root 控制字符负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'verifier 路径带控制字符必须失败',
+    reason: 'Pingora 证据根目录审计自测必须覆盖 verify-script 控制字符负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertManifestFileNameControlCharacterFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖 manifest 文件名控制字符负例。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '--require-command-arg <phase>:<commandName>:<arg>',
+    reason: 'Pingora 证据根目录审计脚本必须支持强制审计切换命令必需参数。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'mergeRequiredCommands',
+    reason: 'Pingora 命令脚本身份要求必须隐式纳入命令证据审计，不能被静默忽略。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'manifest.expectedExecutable 必须是',
+    reason: 'Pingora 证据根目录审计脚本必须阻断命令证据 expectedExecutable 漂移。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'command.executable 必须是',
+    reason: 'Pingora 证据根目录审计脚本必须阻断命令证据真实 executable 漂移。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'readCommandRecord',
+    reason: 'Pingora 证据根目录审计脚本必须读取独立 command-record.json 做语义复核。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'compareCommandRecords',
+    reason: 'Pingora 证据根目录审计脚本必须阻断 manifest.command 与 command-record.json 漂移。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'stdoutPath',
+    reason: 'Pingora 证据根目录审计脚本必须复核命令 stdout 文件引用一致性。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'stderrPath',
+    reason: 'Pingora 证据根目录审计脚本必须复核命令 stderr 文件引用一致性。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'jsonValuesEqual',
+    reason: 'Pingora 证据根目录审计脚本必须复核命令参数数组一致性。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'args 不能包含换行或 NUL 字符',
+    reason:
+      'Pingora 证据根目录审计脚本必须拒绝被控制字符污染的命令参数证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'scalarFields',
+    reason: 'Pingora 证据根目录审计脚本必须复核脱敏命令字符串一致性。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: "'command'",
+    reason: 'Pingora 证据根目录审计脚本必须把脱敏命令字符串纳入一致性比较。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'checkCommandRecordTimes',
+    reason: 'Pingora 证据根目录审计脚本必须校验命令记录 startedAt / finishedAt / durationMs。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: "'--require-summary-ok'",
+    reason: 'Pingora 证据根目录审计脚本复用 verifier 时必须启用 strict summary 模式。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'manifest.summary.status 必须是 OK',
+    reason: 'Pingora 证据根目录审计脚本必须阻断 summary 非 OK 的阶段或命令证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'candidate.commandName === null',
+    reason: 'Pingora 证据根目录审计脚本必须防止命令证据冒充阶段证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'manifest.summary.exitCode 必须是 0',
+    reason: 'Pingora 证据根目录审计脚本必须阻断退出码非 0 的命令证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'CUTOVER_TIMELINE_ORDER',
+    reason: 'Pingora 证据根目录审计脚本必须内置标准直连切换时间线顺序。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '疑似混入不同切换窗口证据',
+    reason: 'Pingora 证据根目录审计脚本必须阻断标准切换时间线倒序证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'DEFAULT_CUTOVER_TIMELINE_MAX_SPAN_MS = 24 * 60 * 60 * 1000',
+    reason: 'Pingora 证据根目录审计脚本必须默认限制标准切换证据窗口为 24 小时。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '--timeline-max-span-ms',
+    reason: 'Pingora 证据根目录审计脚本必须允许切换窗口显式覆盖最大时间跨度。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '--require-cutover-run-id',
+    reason: 'Pingora 证据根目录审计脚本必须能按切换批次 ID 过滤证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'manifest.cutoverRunId',
+    reason: 'Pingora 证据根目录审计脚本必须读取并校验 manifest.cutoverRunId。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '--allow-extra-root-entries',
+    reason: 'Pingora 证据根目录审计脚本允许额外根目录条目时必须显式使用例外开关。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '正式切换归档不应使用',
+    reason: 'Pingora 证据根目录审计脚本必须声明额外根目录条目例外不属于正式归档口径。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '证据根目录只能包含证据目录，发现普通文件',
+    reason: 'Pingora 证据根目录审计脚本必须默认拒绝根目录普通文件。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '证据根目录只能包含带 manifest.json 的证据目录',
+    reason: 'Pingora 证据根目录审计脚本必须默认拒绝无 manifest 的根目录子目录。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertExtraRootFileFailsByDefault',
+    reason: 'Pingora 证据根目录审计自测必须覆盖根目录普通文件默认失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertExtraRootDirectoryFailsByDefault',
+    reason: 'Pingora 证据根目录审计自测必须覆盖无 manifest 根目录子目录默认失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertExtraRootSymlinkFailsByDefault',
+    reason: 'Pingora 证据根目录审计自测必须覆盖根目录符号链接默认失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertAllowExtraRootEntriesSucceeds',
+    reason: 'Pingora 证据根目录审计自测必须覆盖显式允许额外根目录条目的人工例外。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertRequiredCommandExecutableImplicitlyRequiresCommand',
+    reason: 'Pingora 证据根目录审计自测必须覆盖命令脚本身份参数隐式要求命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertRequiredCommandExecutableMismatchFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖命令脚本身份漂移负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertRequiredCommandArgImplicitlyRequiresCommand',
+    reason: 'Pingora 证据根目录审计自测必须覆盖命令必需参数隐式要求命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertRequiredCommandArgMissingFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖命令证据缺少 --apply 参数负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertCommandRecordMismatchFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖 command-record.json 与 manifest.command 漂移负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertCommandRecordTimelineMismatchFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖命令记录时间线漂移负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertCommandRecordOutputPathMismatchFails',
+    reason:
+      'Pingora 证据根目录审计自测必须覆盖 command-record.json 与 manifest.files 的 stdout/stderr 引用漂移负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertCommandRecordArgsMismatchFails',
+    reason:
+      'Pingora 证据根目录审计自测必须覆盖 command-record.json 与 manifest.command 的参数漂移负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertCommandRecordArgsControlCharacterFails',
+    reason:
+      'Pingora 证据根目录审计自测必须覆盖命令参数证据带控制字符的负例。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '时间跨度',
+    reason: 'Pingora 证据根目录审计脚本必须阻断标准切换时间线跨度过大的证据。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertCriticalPhaseSummaryFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖阶段证据 summary 非 OK 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertCommandBundleCannotSatisfyPhaseRequirement',
+    reason: 'Pingora 证据根目录审计自测必须覆盖命令证据不能满足阶段证据要求。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: '必须让 verifier 启用 --require-summary-ok',
+    reason: 'Pingora 证据根目录审计自测必须覆盖总审计调用 verifier 的 strict summary 模式。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertFailedCommandSummaryFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖命令证据退出失败负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertOutOfOrderCutoverTimelineFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖标准切换时间线倒序负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertLongCutoverTimelineFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖标准切换时间线跨度过大负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertCutoverRunIdMismatchFails',
+    reason: 'Pingora 证据根目录审计自测必须覆盖切换批次 ID 不匹配负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--cutover-evidence-timeline-max-span-ms',
+    reason: 'Pingora cutover runbook 必须公开证据时间线最大跨度参数。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '三阶段总审计必须显式传标准切换时间线最大跨度',
+    reason: 'Pingora runbook 自检必须锁住总审计的时间线最大跨度参数。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '回退后状态快照',
+    reason:
+      'Pingora cutover runbook 必须在回退后采集只读状态快照。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '回退后 health patrol env Nginx 模式复核',
+    reason:
+      'Pingora cutover runbook 必须在回退后复核 health patrol env 已回到 Nginx 模式。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs',
+    reason: 'Pingora runbook 自检必须覆盖 current release 随包自审脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason: 'Pingora runbook 自检必须覆盖 current release 随包 health patrol env 切换脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '/opt/genarrative/current/scripts/ops/pingora-cutover-status-snapshot.mjs',
+    reason: 'Pingora runbook 自检必须覆盖 current release 随包切换状态快照脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    reason: 'Pingora runbook 自检必须覆盖 current release 随包切换证据包脚本。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDryRunCutoverRejectsRelativeEvidenceOutputRoot',
+    reason: 'Pingora runbook 自检必须覆盖证据包输出根目录相对路径负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDryRunCutoverRejectsFilesystemRootReleaseRoot',
+    reason: 'Pingora runbook 自检必须覆盖 current release 根目录指向 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDryRunCutoverRejectsFilesystemRootEvidenceOutputRoot',
+    reason: 'Pingora runbook 自检必须覆盖证据包输出根目录指向 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'isFilesystemRootPath',
+    reason: 'Pingora runbook 参数校验必须显式拒绝文件系统根目录。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertUsageCutoverExampleIncludesExplicitEvidenceOutputRoot',
+    reason:
+      'Pingora runbook usage 示例必须显式展示证据包输出根目录，避免值班复制命令时依赖隐藏默认值。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertUsageExamplesIncludeDirectPingoraAccessLog',
+    reason:
+      'Pingora release readiness usage 示例必须显式展示 direct access log 参数，避免值班复制命令后被 --require-direct 拦住。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--clear-public-host',
+    reason: 'Pingora runbook 自检必须覆盖回退后清空 health patrol public Host。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 必须包含回退后 health patrol env Nginx 模式复核',
+    reason: 'Pingora runbook 自检必须覆盖回退后的健康巡检 env 机器复核步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'cutoverReleaseRoot',
+    reason: 'Pingora cutover runbook 必须允许固定 current release 根目录。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-health-patrol-env-file',
+    reason: 'Pingora 强制直连门禁必须允许指定 health patrol env 文件做复核。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '目标 health patrol env 直连模式复核',
+    reason: 'Pingora 强制直连门禁必须复核 health patrol 已切到 direct 模式。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时必须提供 --direct-health-patrol-env-file',
+    reason: 'Pingora 强制直连门禁不能跳过 health patrol env 复核。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'scripts/check-pingora-direct-preflight.mjs',
+    reason: 'Pingora 直连入口门禁必须先执行 direct-entry 预检。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-preflight-env-file',
+    reason: 'Pingora 直连入口门禁必须允许指定目标机 env 文件做预检。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时必须提供 --direct-preflight-env-file',
+    reason: 'Pingora 强制直连门禁不能跳过目标机 env 预检。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时必须提供 --direct-preflight-systemd',
+    reason: 'Pingora 强制直连门禁不能跳过 systemd drop-in 生效核验。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes:
+      '启用 --require-direct 时必须提供 --direct-preflight-check-cert-readable',
+    reason: 'Pingora 强制直连门禁不能跳过 TLS 证书和私钥可读核验。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes:
+      '启用 --require-direct 时必须提供 --direct-preflight-check-service-env-file',
+    reason:
+      'Pingora 强制直连门禁不能跳过 service EnvironmentFile 与 preflight env 一致性核验。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes:
+      '启用 --require-direct 时必须提供 --direct-preflight-check-service-user-cert-readable',
+    reason:
+      'Pingora 强制直连门禁不能跳过 systemd 服务用户读取 TLS 证书和私钥核验。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes:
+      '启用 --require-direct 时必须提供 --direct-preflight-check-service-binary-executable',
+    reason:
+      'Pingora 强制直连门禁不能跳过 current release service 二进制可执行核验。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes:
+      '启用 --dry-run-cutover 时必须提供 --direct-preflight-check-ports-free',
+    reason:
+      'Pingora 切换前 runbook 门禁不能跳过 80/443 端口释放核验；启用后直连复核不再要求端口空闲。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时必须提供 --direct-http-base-url',
+    reason: 'Pingora 强制直连门禁不能跳过 HTTP redirect / ACME live 验证。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时必须提供 --direct-host',
+    reason:
+      'Pingora 强制直连门禁不能跳过正式域名 Host header 和 TLS SNI 验证。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时必须提供 --direct-redirect-host',
+    reason: 'Pingora 强制直连门禁不能跳过 HTTP redirect Location host 验证。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时必须提供 --direct-pingora-access-log',
+    reason: 'Pingora 强制直连门禁不能跳过 direct access log 落盘校验。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: "validateSafeAbsoluteFilePath(\n      result.directPingoraAccessLog,\n      '--direct-pingora-access-log'",
+    reason:
+      'Pingora 强制直连门禁必须拒绝相对 access log 路径和文件系统根目录。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--http-base-url',
+    reason:
+      'Pingora 直连入口门禁必须把 HTTP redirect / ACME base URL 传给 direct live smoke。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--host',
+    reason:
+      'Pingora 直连入口门禁必须把正式域名 Host/SNI 传给 direct live smoke。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--redirect-host',
+    reason:
+      'Pingora 直连入口门禁必须把 redirect Location host 传给 direct live smoke。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--pingora-access-log',
+    reason:
+      'Pingora 直连入口门禁必须把 access log 路径传给 direct live smoke。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-preflight-systemd',
+    reason: 'Pingora 直连入口门禁必须支持检查 systemd drop-in 是否生效。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-preflight-check-service-user-cert-readable',
+    reason: 'Pingora 直连入口门禁必须支持检查 systemd 服务用户可读证书。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-preflight-check-service-env-file',
+    reason:
+      'Pingora 直连入口门禁必须支持检查 service EnvironmentFile 与 preflight env 一致。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-preflight-check-service-binary-executable',
+    reason: 'Pingora 直连入口门禁必须支持检查 service ExecStart 二进制可执行。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-preflight-check-ports-free',
+    reason: 'Pingora 直连入口门禁必须支持检查 TLS/HTTP redirect 端口已释放。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-spacetime-database',
+    reason:
+      'Pingora 直连入口门禁必须允许指定 WSS subscribe 的目标 SpacetimeDB 库。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时必须提供 --direct-spacetime-database',
+    reason: 'Pingora 强制直连门禁不能让 WSS subscribe 隐式使用默认数据库名。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时不能使用 --direct-skip-wss',
+    reason: 'Pingora 强制直连门禁不能允许正式直连跳过 WSS subscribe。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '启用 --require-direct 时不能使用 --direct-insecure-tls',
+    reason: 'Pingora 强制直连门禁不能允许生产直连跳过 TLS 信任校验。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--direct-require-wss-upgrade',
+    reason: 'Pingora 直连入口门禁必须支持强制要求 WSS subscribe 返回 101。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'result.directRequireWssUpgrade = true',
+    reason:
+      'Pingora --require-direct 硬门禁默认必须强制 WSS subscribe 返回 101。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'scripts/check-pingora-canary-docker.mjs',
+    reason: 'Pingora 正式切换聚合门禁必须包含 Docker Nginx handoff smoke。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-route-parity',
+    reason: 'Pingora 正式切换聚合门禁必须包含 Nginx / Pingora 路由 parity。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-direct-rollback',
+    reason: 'Pingora 正式切换聚合门禁必须包含直连回退 dry-run 行为检查。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-direct-preflight',
+    reason: 'Pingora 正式切换聚合门禁必须包含直连入口静态预检。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-direct-enable',
+    reason: 'Pingora 正式切换聚合门禁必须包含直连启用 dry-run 行为检查。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-release-readiness-plan',
+    reason: 'Pingora 正式切换聚合门禁必须自检关键计划语义。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes:
+      '--require-direct 必须把 HTTP redirect / ACME 入口纳入 direct live smoke',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的 HTTP redirect / ACME 硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-live 必须把正式域名 Host 传给 live canary smoke',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-live 的正式域名 Host 硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 必须包含 direct enable apply',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖直连启用 runbook。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 必须包含 rollback apply',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖失败回退 runbook。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 缺少 --require-direct 时必须失败',
+    reason: 'Pingora cutover runbook 不能在缺少直连硬门禁参数时生成。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 必须包含 Host 一致性确认步骤',
+    reason: 'Pingora cutover runbook 必须显式展示 direct / health patrol / rollback Host 一致性。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover redirect Host 与 direct Host 不一致时必须失败',
+    reason: 'Pingora cutover runbook 必须阻断 redirect Host 与正式入口 Host 漂移。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover rollback smoke Host 与 direct Host 不一致时必须失败',
+    reason: 'Pingora cutover runbook 必须阻断 rollback smoke Host 与正式入口 Host 漂移。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover rollback 步骤必须传递 shadow probe URL',
+    reason: 'Pingora cutover runbook 自检必须覆盖可选 rollback shadow probe 传递。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover JSON 不能泄露 shadow probe token 原文',
+    reason: 'Pingora cutover runbook 自检必须覆盖 shadow probe token 脱敏。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run plan JSON 不能泄露 direct probe token 原文',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖 direct probe token 脱敏。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes:
+      '启用后 release readiness 直连复核必须继续传递 direct probe token 参数',
+    reason:
+      'Pingora cutover runbook 自检必须覆盖启用后 readiness 复核继续检查 direct probe。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 启用前基础门禁必须使用 current release 包内运行时复核模式',
+    reason: 'Pingora cutover runbook 自检必须覆盖启用前 readiness 使用 runtime-only 模式。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '启用后 release readiness 直连复核必须使用 current release 包内运行时复核模式',
+    reason: 'Pingora cutover runbook 自检必须覆盖启用后 readiness 使用 runtime-only 模式。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes:
+      '启用后 release readiness 直连复核必须使用 current release 随包 release readiness 聚合门禁脚本',
+    reason:
+      'Pingora cutover runbook 自检必须覆盖启用后 readiness 从 current release 随包脚本执行。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes:
+      'dry-run cutover 启用前基础门禁必须使用 current release 随包 release readiness 聚合门禁脚本',
+    reason:
+      'Pingora cutover runbook 自检必须覆盖启用前 readiness 从 current release 随包脚本执行。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover JSON 不能泄露 direct probe token 原文',
+    reason:
+      'Pingora cutover runbook 自检必须覆盖 direct probe token 在切换计划中脱敏。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover rollback shadow probe URL 缺少 token 时必须失败',
+    reason: 'Pingora cutover runbook 自检必须覆盖 shadow probe 参数成对出现。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 必须把正式域名 Host/SNI 传给 direct live smoke',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的正式域名 Host/SNI 硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes:
+      '--require-direct 必须把显式 redirect Location host 传给 direct live smoke',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的 redirect Location host 硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 必须检查 systemd drop-in 最终生效配置',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的 systemd drop-in 硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 必须检查当前用户可读 TLS 证书和私钥',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的证书可读硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 必须检查 service EnvironmentFile 包含本次 env',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的 service env 一致性硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 必须检查 systemd 服务用户可读 TLS 证书和私钥',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的服务用户证书可读硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes:
+      '--require-direct 必须检查 Pingora service ExecStart 二进制可执行',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的 service 二进制可执行硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 启用前预检必须检查 80/443 端口释放',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖切换前端口释放硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes:
+      '--require-direct 必须把显式 SpacetimeDB 数据库名传给 direct live smoke',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的显式 WSS 数据库名。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes:
+      '--require-direct 必须把 Pingora access log 落盘校验传给 direct live smoke',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的 Pingora access log 硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少 direct HTTP base URL 时必须失败',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖缺少 direct HTTP base URL 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-live 缺少 live Host 时必须失败',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖缺少 live Host 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-live 的 live Host 不能接受 URL 或路径',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖 live Host 格式负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少 direct Host/SNI 时必须失败',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖缺少正式域名 Host/SNI 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 的 direct Host/SNI 不能接受 URL 或路径',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖 direct Host/SNI 格式负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少 direct redirect Location host 时必须失败',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖缺少 redirect Location host 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 的 redirect Location host 不能接受 URL 或路径',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 redirect Location host 格式负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少 systemd preflight 时必须失败',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖缺少 systemd preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少证书可读 preflight 时必须失败',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖缺少证书可读 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少 service EnvironmentFile preflight 时必须失败',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖缺少 service env 一致性 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少服务用户证书可读 preflight 时必须失败',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖缺少服务用户证书可读 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少 service 二进制可执行 preflight 时必须失败',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖缺少 service 二进制可执行 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct post-enable 复核不能要求 80/443 空闲',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖启用后直连复核不再要求端口空闲。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少 SpacetimeDB 数据库名时必须失败',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖缺少显式 WSS 数据库名的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 缺少 direct Pingora access log 时必须失败',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖缺少 direct access log 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 不能允许跳过 WSS subscribe',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖 direct skip WSS 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 不能允许 insecure TLS',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖 direct insecure TLS 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '--require-direct 必须自动强制 WSS subscribe 返回 101',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的 WSS 101 硬要求。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: '--require-docker',
+    reason:
+      'Pingora Docker canary smoke 必须支持在 CI / 目标 agent 上强制执行。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: 'scripts/check-pingora-canary-live.mjs',
+    reason:
+      'Pingora Docker canary smoke 必须复用 live canary 断言，避免双套验收漂移。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: '--realpath',
+    reason:
+      'Pingora Docker canary smoke 必须覆盖真实路径 canary handoff。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: 'genarrative-pingora-realpath-canary.conf',
+    reason:
+      'Pingora Docker canary smoke 必须加载真实路径 canary snippet。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: '--network',
+    reason:
+      'Pingora Docker canary smoke 必须真实启动 Nginx 容器验证 handoff 链路。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: 'log_format genarrative_upstream',
+    reason:
+      'Pingora Docker canary smoke 必须按生产 Nginx access log 口径写 request_id。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: 'scripts/check-pingora-canary-access-log-parity.mjs',
+    reason:
+      'Pingora Docker canary smoke 必须复用真实 access log 对账脚本验证 handoff。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: '/__genarrative_pingora_canary/api/creation-entry/config',
+    reason:
+      'Pingora Docker canary access log 对账必须覆盖代表性 API canary 路径。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: '/__genarrative_pingora_canary/v1/identity',
+    reason:
+      'Pingora Docker canary access log 对账必须覆盖 SpacetimeDB identity 路径。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-docker.mjs',
+    includes: '/__genarrative_pingora_canary/assets/app.js',
+    reason: 'Pingora Docker canary access log 对账必须覆盖静态资源路径。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity.mjs',
+    includes: '该脚本只读比较 Nginx canary handoff access log 和 Pingora access log',
+    reason: 'Pingora canary access log 对账脚本必须说明只读边界。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity.mjs',
+    includes: 'request_id',
+    reason: 'Pingora canary access log 对账必须按 request_id 串联 Nginx 与 Pingora 日志。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity.mjs',
+    includes: 'realpath',
+    reason: 'Pingora canary access log 对账必须支持真实路径 canary 模式。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity.mjs',
+    includes: '/__genarrative_pingora/healthz',
+    reason: 'Pingora canary access log 对账必须覆盖 canary healthz 到 shadow healthz 的真实映射。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity.mjs',
+    includes: 'parseRequiredPositiveInt',
+    reason:
+      'Pingora canary access log 对账 since-lines 必须严格校验，不能静默回默认值。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity.mjs',
+    includes: 'validateSafeAbsoluteFilePath(file, label);',
+    reason: 'Pingora canary access log 对账必须拒绝相对日志路径和文件系统根目录。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity.mjs',
+    includes: 'function validateNoControlCharacters(value, label)',
+    reason:
+      'Pingora canary access log 对账必须拒绝日志路径、前缀、必需路径和 since-lines 中的换行 / NUL。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity-check.mjs',
+    includes: 'assertRejectsFilesystemRootLogPaths',
+    reason: 'Pingora canary access log 对账自测必须覆盖日志路径指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity-check.mjs',
+    includes: 'assertRejectsLogPathControlCharacters',
+    reason: 'Pingora canary access log 对账自测必须覆盖日志路径带控制字符的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity-check.mjs',
+    includes: 'assertRejectsPrefixAndPathControlCharacters',
+    reason:
+      'Pingora canary access log 对账自测必须覆盖 canary prefix 和必需路径带控制字符的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity-check.mjs',
+    includes: 'assertRejectsParsedLogPathControlCharacters',
+    reason:
+      'Pingora canary access log 对账自测必须覆盖日志行解析出的 path 带控制字符的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity-check.mjs',
+    includes: '缺少对应 Pingora access log',
+    reason: 'Pingora canary access log 对账自测必须覆盖缺少 Pingora 日志的失败场景。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-access-log-parity-check.mjs',
+    includes: 'assertRejectsInvalidSinceLines',
+    reason:
+      'Pingora canary access log 对账自测必须覆盖非法 since-lines 参数和 env 负例。',
+  },
+  {
+    file: 'deploy/env/pingora-canary-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_CANARY_BASE_URL',
+    reason: 'Pingora canary live smoke 必须有可复制的环境变量示例。',
+  },
+  {
+    file: 'deploy/env/pingora-canary-live.env.example',
+    includes: '不要填 https:// URL',
+    reason: 'Pingora canary live smoke 环境示例必须提示 Host 只填 host。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL',
+    reason: 'Pingora direct live smoke 必须有可复制的环境变量示例。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL',
+    reason:
+      'Pingora direct live smoke 环境示例必须暴露 HTTP redirect base URL。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST',
+    reason:
+      'Pingora direct live smoke 环境示例必须暴露 HTTP redirect Location host。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_REDIRECT_BASE_URL',
+    reason:
+      'Pingora direct live smoke 环境示例必须暴露高端口 rehearsal 的 redirect Location base URL 覆盖。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: '只填域名或 host:port',
+    reason: 'Pingora direct live smoke 环境示例必须提示 Host 参数格式。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE',
+    reason:
+      'Pingora direct live smoke 环境示例必须暴露 WSS subscribe 使用的数据库名。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_REQUIRE_WSS_UPGRADE',
+    reason: 'Pingora direct live smoke 环境示例必须暴露 WSS 101 强制开关。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct',
+    reason: 'Pingora direct live env 示例必须提醒直连后切换健康巡检模式。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'current release 自审',
+    reason:
+      'Pingora direct live env 示例必须提醒直连启用 apply 前先做 current release 自审。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: '--preflight-check-service-env-file',
+    reason:
+      'Pingora direct live env 示例中的正式启用命令必须包含 service EnvironmentFile 一致性预检。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: '--preflight-check-service-user-cert-readable',
+    reason:
+      'Pingora direct live env 示例中的正式启用命令必须包含服务用户证书可读预检。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: '--preflight-check-service-binary-executable',
+    reason:
+      'Pingora direct live env 示例中的正式启用命令必须包含 service 二进制可执行预检。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes:
+      'plan:pingora-direct-cutover` 会在 JSON runbook 中列出 direct / nginx 两个方向的 env 切换脚本和 env 复核步骤',
+    reason:
+      'Nginx / Pingora 运维文档必须说明 cutover runbook 包含健康巡检切换脚本与复核步骤。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--rollback-health-patrol-public-base-url',
+    reason:
+      'Nginx / Pingora 运维文档必须提醒 runbook 显式声明回退后的 Nginx 巡检入口。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--preflight-check-service-env-file',
+    reason:
+      'Nginx / Pingora 运维文档中的正式启用示例必须包含 service EnvironmentFile 一致性预检。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--preflight-check-service-user-cert-readable',
+    reason:
+      'Nginx / Pingora 运维文档中的正式启用示例必须包含服务用户证书可读预检。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--preflight-check-service-binary-executable',
+    reason:
+      'Nginx / Pingora 运维文档中的正式启用示例必须包含 service 二进制可执行预检。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live.mjs',
+    includes: 'X-Genarrative-Nginx-Handoff',
+    reason: 'Pingora canary live smoke 必须校验 Nginx handoff 响应头。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live.mjs',
+    includes: '/__genarrative_pingora_canary',
+    reason: 'Pingora canary live smoke 必须默认检查前缀 canary 入口。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live.mjs',
+    includes: '/__genarrative_pingora_realpath_canary/healthz',
+    reason: 'Pingora canary live smoke 必须支持真实路径 canary healthz 探针。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-realpath-live',
+    reason: 'Pingora 聚合门禁必须支持把真实路径 canary 纳入目标机 live 复核。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '目标 Nginx realpath canary access log 对账',
+    reason: 'Pingora 聚合门禁计划自检必须覆盖真实路径 canary access log 对账。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live.mjs',
+    includes: 'validateHostOption(result.host,',
+    reason: 'Pingora canary live smoke 必须提前拒绝非法 Host header 参数。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live.mjs',
+    includes: 'parseRequiredPositiveInt',
+    reason:
+      'Pingora canary live smoke timeout 参数必须严格校验，不能静默回默认值。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live.mjs',
+    includes: 'validateNoControlCharacters',
+    reason:
+      'Pingora canary live smoke 必须在发起 canary 请求前拒绝带控制字符的 base URL、prefix、Host、path 和 timeout。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live.mjs',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora canary live smoke 必须对带换行或 NUL 的现场参数给出明确错误。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live-guard.mjs',
+    includes: 'assertRejectsControlCharacter',
+    reason:
+      'Pingora canary live guard 必须动态覆盖控制字符参数在发起 canary 请求前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-canary-live-guard.mjs',
+    includes: '--prefix',
+    reason: 'Pingora canary live guard 必须覆盖 canary prefix 控制字符负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'X-Genarrative-Gateway',
+    reason: 'Pingora direct live smoke 必须确认响应来自 Pingora 网关。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'http-api-redirect',
+    reason: 'Pingora direct live smoke 必须覆盖 HTTP 到 HTTPS 重定向。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-http2-alpn',
+    reason: 'Pingora direct live smoke 必须覆盖 HTTPS HTTP/2 ALPN。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'v2.bsatn.spacetimedb',
+    reason:
+      'Pingora direct live smoke 必须覆盖 SpacetimeDB SDK 默认 WSS 子协议透传。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'wss-spacetime-subscribe',
+    reason: 'Pingora direct live smoke 必须覆盖 WSS subscribe 握手。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: '--require-wss-upgrade',
+    reason:
+      'Pingora direct live smoke 必须支持强制要求 WSS subscribe 返回 101。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'validateHostOption(result.redirectHost,',
+    reason:
+      'Pingora direct live smoke 必须提前拒绝非法 redirect Location host 参数。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'validateHttpsBaseUrl(result.redirectBaseUrl,',
+    reason:
+      'Pingora direct live smoke 必须提前拒绝非法 redirect Location base URL 参数。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'parseRequiredPositiveInt',
+    reason:
+      'Pingora direct live smoke timeout 参数必须严格校验，不能静默回默认值。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'validateNoControlCharacters',
+    reason:
+      'Pingora direct live smoke 必须在发起 HTTPS / HTTP / WSS 请求前拒绝带控制字符的 URL、Host、token、路径和日志参数。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora direct live smoke 必须对带换行或 NUL 的现场参数给出明确错误。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'validateSafeAbsoluteFilePath',
+    reason:
+      'Pingora direct live smoke 的 access log 路径必须统一复核绝对路径、根目录和控制字符。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: '必须是布尔值 true/false 或 1/0',
+    reason:
+      'Pingora direct live smoke 布尔 env 必须严格校验，避免拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: '不能是文件系统根目录',
+    reason: 'Pingora direct live smoke 必须拒绝 Pingora access log 指向文件系统根目录。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live-guard.mjs',
+    includes: 'assertRejectsControlCharacter',
+    reason:
+      'Pingora direct live guard 必须动态覆盖控制字符参数在发起 live 请求前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live-guard.mjs',
+    includes: '--probe-token',
+    reason: 'Pingora direct live guard 必须覆盖 probe token 控制字符负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live-guard.mjs',
+    includes: '--pingora-access-log',
+    reason: 'Pingora direct live guard 必须覆盖 access log 路径控制字符负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'scripts/check-pingora-direct-live-guard.mjs',
+    reason:
+      'Pingora 聚合 readiness 必须执行 direct live 参数护栏，避免正式切换前漏掉脚本输入污染负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'readBoolEnv(',
+    reason:
+      'Pingora release readiness 直连布尔 env 必须统一严格解析，避免拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDirectLiveRejectsInvalidBoolEnv',
+    reason:
+      'Pingora release readiness plan 自测必须覆盖 direct live 非法布尔 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertReleaseReadinessRejectsInvalidDirectBoolEnv',
+    reason:
+      'Pingora release readiness plan 自测必须覆盖 release readiness 非法直连布尔 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertRequireDirectRejectsFilesystemRootPingoraAccessLog',
+    reason:
+      'Pingora release readiness plan 自测必须覆盖直连 Pingora access log 指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertRequireDirectRejectsFilesystemRootPreflightEnvFile',
+    reason:
+      'Pingora release readiness plan 自测必须覆盖直连 preflight env 文件指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertRequireDirectRejectsFilesystemRootHealthPatrolEnvFile',
+    reason:
+      'Pingora release readiness plan 自测必须覆盖直连 health patrol env 文件指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDirectLiveRejectsFilesystemRootAccessLog',
+    reason:
+      'Pingora release readiness plan 自测必须覆盖 direct live 单脚本日志路径指到 / 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDirectPreflightRejectsInvalidBoolEnv',
+    reason:
+      'Pingora release readiness plan 自测必须覆盖 direct preflight 非法布尔 env 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'assertDirectPreflightRejectsUnconfirmedMultiInstanceProtection',
+    reason:
+      'Pingora release readiness plan 自测必须覆盖未确认共享保护的多实例 direct preflight 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    reason: 'Pingora direct preflight 必须检查低端口 capability drop-in。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: '必须是布尔值 true/false 或 1/0',
+    reason:
+      'Pingora direct preflight 布尔 env 必须严格校验，避免检查项拼写错误静默降级。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN',
+    reason: 'Pingora direct preflight 必须检查直连 TLS env。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: '--check-ports-free',
+    reason: 'Pingora direct preflight 必须支持检查 80/443 是否已释放。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: '--check-service-user-cert-readable',
+    reason: 'Pingora direct preflight 必须支持检查 systemd 服务用户可读证书。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: '--check-service-env-file',
+    reason:
+      'Pingora direct preflight 必须支持检查 service EnvironmentFile 包含本次 env。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: '--check-service-binary-executable',
+    reason:
+      'Pingora direct preflight 必须支持检查 service ExecStart 二进制可执行。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'assertProtectionInstanceBoundary',
+    reason:
+      'Pingora direct preflight 必须检查多实例与进程内接流保护的边界。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1',
+    reason:
+      'Pingora direct preflight 多实例保护失败必须给出明确错误。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'ExecStart=',
+    reason:
+      'Pingora direct preflight 必须从 systemd service ExecStart 推导 current release 二进制路径。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'sudo',
+    reason:
+      'Pingora direct preflight 必须能以 systemd 服务用户身份验证 cert/key 可读性。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'fileURLToPath(import.meta.url)',
+    reason:
+      'Pingora direct preflight 默认路径必须从脚本所在 release root 推导，不能依赖 Jenkins 工作区。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'validateNoControlCharacters',
+    reason:
+      'Pingora direct preflight 必须在执行 systemctl 或 sudo 前拒绝带控制字符的路径和子命令参数。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora direct preflight 必须明确拒绝带换行或 NUL 的路径和子命令参数。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'function runCommand(command, args)',
+    reason:
+      'Pingora direct preflight 的 systemctl / sudo 子命令必须经统一执行前参数校验。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: "validateSafeAbsoluteFilePath(result.envFile, '--env-file')",
+    reason: 'Pingora direct preflight 必须拒绝 --env-file 指向文件系统根目录。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight-guard.mjs',
+    includes: 'assertRejectsEnvFileWithControlCharacters',
+    reason: 'Pingora direct preflight 自测必须覆盖 --env-file 控制字符负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight-guard.mjs',
+    includes: 'assertRejectsSystemdServiceWithControlCharactersBeforeSystemctl',
+    reason:
+      'Pingora direct preflight 自测必须覆盖 systemd service 控制字符在执行 systemctl 前失败。',
+  },
+  {
+    file: 'package.json',
+    includes: 'node scripts/check-pingora-direct-preflight-guard.mjs',
+    reason: 'Pingora direct preflight npm 自测入口必须执行控制字符负例护栏。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes: 'deploy/pingora/pingora-gateway.env.example',
+    reason:
+      'Pingora direct preflight 必须能从 release root 读取 deploy/pingora 配置。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-preflight.mjs',
+    includes:
+      '公网直连 Pingora 时 GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR 必须保持 false',
+    reason:
+      'Pingora direct preflight 必须阻断公网直连时误信任 X-Forwarded-For。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'assertDirectPreflightRejectsPublicForwardedForTrust',
+    reason:
+      'Pingora direct preflight 自测必须覆盖公网直连误信任 X-Forwarded-For 的负例。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--apply',
+    reason: 'Pingora 直连回退脚本默认必须是 dry-run，只能显式 apply 修改系统。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--apply 必须同时提供 --reload-nginx',
+    reason: 'Pingora 直连回退 apply 前必须强制 reload Nginx 并核验 active。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '${NGINX_BINARY} -t',
+    reason: 'Pingora 直连回退 reload Nginx 前必须先执行 nginx -t。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'drop-in 目录不能是符号链接',
+    reason:
+      'Pingora 直连回退脚本 apply 前必须拒绝符号链接 drop-in 目录，避免删除非预期 systemd 位置。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'drop-in 目标不能是符号链接',
+    reason:
+      'Pingora 直连回退脚本 apply 前必须拒绝符号链接 drop-in 目标，避免误以为已回退真实 drop-in。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'drop-in 目标已存在但不是普通文件',
+    reason: 'Pingora 直连回退脚本 apply 前必须拒绝非普通文件 drop-in 目标。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--apply 必须同时提供 --nginx-smoke-url',
+    reason: 'Pingora 直连回退 apply 前必须强制 Nginx 入口 smoke。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--nginx-smoke-url 指向本机地址时必须同时提供 --nginx-smoke-host',
+    reason:
+      'Pingora 直连回退本机 smoke 必须显式使用正式 Host，避免命中默认 vhost。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--nginx-smoke-expect-body',
+    reason:
+      'Pingora 直连回退必须支持 Nginx smoke 响应体证据片段，避免 HTTP 200 命中错误入口。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'nginx smoke evidence matched expected body fragment',
+    reason: 'Pingora 直连回退必须在 Nginx smoke 响应体匹配后输出证据摘要。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'Nginx smoke 响应缺少预期片段',
+    reason: 'Pingora 直连回退必须拒绝 Nginx smoke 响应体漂移。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '只能是 host 或 host:port',
+    reason: 'Pingora 直连回退必须拒绝非法 Nginx smoke Host。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--curl-binary',
+    reason:
+      'Pingora 直连回退必须支持覆盖 curl 可执行文件，便于测试和特殊环境。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--health-patrol-env-file',
+    reason: 'Pingora 直连回退必须支持可选复核 health patrol env 已切回 nginx。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--health-patrol-env-check-script',
+    reason:
+      'Pingora 直连回退 health patrol env 复核必须能固定 current release 随包脚本。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'node -- "${health_patrol_args[@]}"',
+    reason:
+      'Pingora 直连回退 health patrol env 复核必须用 node -- 分隔脚本参数，避免 Node 22 抢占业务 --env-file。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--require-empty-public-host',
+    reason: 'Pingora 直连回退 health patrol env 复核必须阻断 direct Host 覆盖残留。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--pingora-shadow-probe-url',
+    reason: 'Pingora 直连回退必须支持可选复核 shadow 高端口探针。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '--pingora-shadow-probe-token',
+    reason: 'Pingora 直连回退 shadow 探针复核必须使用 probe token。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'X-Genarrative-Pingora-Probe: <redacted>',
+    reason: 'Pingora 直连回退 shadow 探针命令日志必须隐藏 probe token。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'dry-run Pingora shadow probe 命令不应输出 probe token 原文',
+    reason: 'Pingora 直连回退自测必须覆盖 shadow probe token 不进命令日志。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'gateway=pingora-shadow',
+    reason: 'Pingora 直连回退 shadow 探针复核必须检查响应身份。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '${CURL_BINARY} --fail',
+    reason: 'Pingora 直连回退 reload Nginx 后必须执行 smoke URL 验证。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'systemctl daemon-reload',
+    reason: 'Pingora 直连回退移除 drop-in 后必须 reload systemd。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'genarrative-pingora-gateway.service',
+    reason: 'Pingora 直连回退脚本必须默认重启 Pingora 网关服务。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'direct-entry.conf',
+    reason: 'Pingora 直连回退脚本必须移除 direct-entry drop-in。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'systemctl cat ${SERVICE_NAME}',
+    reason: 'Pingora 直连回退 apply 后必须核验 systemd drop-in 最终已移除。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '仍显示 AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    reason: 'Pingora 直连回退 apply 后必须拒绝 AmbientCapabilities 残留。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '仍显示 CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+    reason: 'Pingora 直连回退 apply 后必须拒绝 CapabilityBoundingSet 残留。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'systemctl is-active ${NGINX_SERVICE}',
+    reason: 'Pingora 直连回退 reload Nginx 后必须核验 Nginx active 状态。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'Nginx reload 后状态不是 active',
+    reason: 'Pingora 直连回退必须拒绝 Nginx reload 后非 active 状态。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply',
+    reason: 'Pingora 直连启用脚本默认必须是 dry-run，只能显式 apply 修改系统。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'systemctl daemon-reload',
+    reason: 'Pingora 直连启用安装 drop-in 后必须 reload systemd。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'genarrative-pingora-gateway.service',
+    reason: 'Pingora 直连启用脚本必须默认重启 Pingora 网关服务。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+    reason:
+      'Pingora 直连启用脚本默认必须读取 current release 随包 direct-entry 模板，不能依赖 /etc 参考模板。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_CURRENT_RELEASE_AUDIT_SCRIPT',
+    reason:
+      'Pingora 直连启用脚本必须支持固定 current release 自审脚本，避免切换窗口依赖源码工作区。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'run_current_release_audit',
+    reason:
+      'Pingora 直连启用 apply 前必须先跑 current release 自包含自审，再修改 systemd。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--require-pingora-gateway',
+    reason:
+      'Pingora 直连启用 apply 前 current release 自审必须要求 Pingora 网关产物存在。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--systemd-show',
+    reason:
+      'Pingora 直连启用 apply 前 current release 自审必须核验 systemd ExecStart。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--service-unit-path',
+    reason:
+      'Pingora 直连启用脚本必须能固定随包主 service 模板作为 ExecStart 真相源。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager',
+    reason:
+      'Pingora 直连启用脚本 apply 后必须核验 systemd ExecStart 指向 current release 网关二进制。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'assertApplyFailsWhenCurrentReleaseAuditFailsBeforeInstall',
+    reason:
+      'Pingora 直连启用脚本自测必须覆盖 current release 自审失败时不安装 drop-in。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'assertApplyFailsWhenSystemdExecStartDiffers',
+    reason:
+      'Pingora 直连启用脚本自测必须覆盖 systemd ExecStart 指向旧 release 的负例。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '该脚本不写入 TLS env',
+    reason: 'Pingora 直连启用脚本不能隐式修改 TLS/env/证书边界。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --preflight-env-file',
+    reason: 'Pingora 直连启用 apply 前必须强制通过 env 预检。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --preflight-check-cert-readable',
+    reason: 'Pingora 直连启用 apply 前必须强制通过证书可读预检。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --preflight-check-service-env-file',
+    reason:
+      'Pingora 直连启用 apply 前必须强制通过 service EnvironmentFile 一致性预检。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'systemd_env_file_matches',
+    reason:
+      'Pingora 直连启用 apply 后必须精确核验 systemctl cat 中的 EnvironmentFile。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes:
+      '--apply 必须同时提供 --preflight-check-service-user-cert-readable',
+    reason: 'Pingora 直连启用 apply 前必须强制通过服务用户证书可读预检。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes:
+      '--apply 必须同时提供 --preflight-check-service-binary-executable',
+    reason: 'Pingora 直连启用 apply 前必须强制通过 service 二进制可执行预检。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --preflight-check-ports-free',
+    reason: 'Pingora 直连启用 apply 前必须强制通过端口释放预检。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --direct-https-base-url',
+    reason: 'Pingora 直连启用 apply 后必须强制验证 HTTPS 直连入口。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --direct-http-base-url',
+    reason: 'Pingora 直连启用 apply 后必须强制验证 HTTP redirect / ACME 入口。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --direct-host',
+    reason: 'Pingora 直连启用 apply 后必须用正式域名 Host/SNI 验证。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --direct-redirect-host',
+    reason: 'Pingora 直连启用 apply 后必须验证 redirect Location host。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--direct-redirect-base-url',
+    reason:
+      'Pingora 直连启用脚本必须支持把高端口 rehearsal 的 redirect base URL 透传给 direct live smoke。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --direct-spacetime-database',
+    reason: 'Pingora 直连启用 apply 后必须验证目标库 WSS subscribe。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'systemctl cat ${SERVICE_NAME}',
+    reason: 'Pingora 直连启用 apply 后必须核验 systemd drop-in 最终生效。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'systemctl is-active ${SERVICE_NAME}',
+    reason: 'Pingora 直连启用 apply 后必须核验服务已 active。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+    reason: 'Pingora 直连启用 apply 后必须核验 AmbientCapabilities。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+    reason: 'Pingora 直连启用 apply 后必须核验 CapabilityBoundingSet。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--require-wss-upgrade',
+    reason: 'Pingora 直连启用 apply 后 direct live smoke 必须强制 WSS 101。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'print_redacted_command node "${direct_live_args[@]}"',
+    reason: 'Pingora 直连启用脚本展示 direct live 命令时必须隐藏 probe token。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'dry-run 不应安装临时 drop-in 文件',
+    reason: 'Pingora 直连启用检查必须证明默认 dry-run 不修改 drop-in。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--probe-token <redacted>',
+    reason: 'Pingora 直连启用检查必须覆盖 direct live 命令 token 脱敏。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'dry-run 必须展示并执行 direct preflight',
+    reason: 'Pingora 直连启用检查必须证明可在启用前执行 direct preflight。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes:
+      'release current 目录中的 enable dry-run 必须默认读取随包携带的 direct-entry 模板',
+    reason:
+      'Pingora 直连启用检查必须证明从 /opt/genarrative/current 执行时默认使用发布包内 systemd 模板。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --preflight-env-file 必须被拒绝',
+    reason: 'Pingora 直连启用检查必须覆盖 apply 跳过 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --preflight-check-cert-readable 必须被拒绝',
+    reason:
+      'Pingora 直连启用检查必须覆盖 apply 跳过证书可读 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes:
+      '--apply 缺少 --preflight-check-service-user-cert-readable 必须被拒绝',
+    reason:
+      'Pingora 直连启用检查必须覆盖 apply 跳过服务用户证书可读 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes:
+      '--apply 缺少 --preflight-check-service-binary-executable 必须被拒绝',
+    reason:
+      'Pingora 直连启用检查必须覆盖 apply 跳过 service 二进制可执行 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --preflight-check-ports-free 必须被拒绝',
+    reason:
+      'Pingora 直连启用检查必须覆盖 apply 跳过端口释放 preflight 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'dry-run 必须展示启用后 systemd drop-in 生效核验',
+    reason: 'Pingora 直连启用检查必须覆盖启用后的 systemd 生效核验步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'dry-run 必须展示启用后 service active 核验',
+    reason: 'Pingora 直连启用检查必须覆盖启用后的 service active 核验。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --direct-https-base-url 必须被拒绝',
+    reason: 'Pingora 直连启用检查必须覆盖缺少 direct HTTPS 参数的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --direct-http-base-url 必须被拒绝',
+    reason: 'Pingora 直连启用检查必须覆盖缺少 direct HTTP 参数的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --direct-host 必须被拒绝',
+    reason: 'Pingora 直连启用检查必须覆盖缺少 direct Host/SNI 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --direct-redirect-host 必须被拒绝',
+    reason: 'Pingora 直连启用检查必须覆盖缺少 redirect host 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --direct-spacetime-database 必须被拒绝',
+    reason: 'Pingora 直连启用检查必须覆盖缺少 WSS 数据库名的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'direct live smoke 失败时 enable apply 必须失败',
+    reason: 'Pingora 直连启用检查必须覆盖 direct live smoke 失败负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'direct preflight 脚本缺失时 enable apply 必须失败',
+    reason: 'Pingora 直连启用检查必须覆盖 direct preflight 脚本缺失负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'direct live smoke 脚本缺失时 enable apply 必须失败',
+    reason: 'Pingora 直连启用检查必须覆盖 direct live smoke 脚本缺失负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--template-path 必须是绝对路径',
+    reason: 'Pingora 直连启用检查必须覆盖模板相对路径负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--dropin-path 必须是绝对路径',
+    reason: 'Pingora 直连启用检查必须覆盖 drop-in 相对路径负例。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'drop-in 目录不能是符号链接',
+    reason:
+      'Pingora 直连启用脚本 apply 前必须拒绝符号链接 drop-in 目录，避免写到非预期 systemd 位置。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'drop-in 目标不能是符号链接',
+    reason:
+      'Pingora 直连启用脚本 apply 前必须拒绝符号链接 drop-in 目标，避免覆盖非预期文件。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'reject_control_characters',
+    reason:
+      'Pingora 直连启用脚本必须在修改 systemd 前拒绝带换行或 NUL 的切换参数。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'reject_filesystem_root_path',
+    reason:
+      'Pingora 直连启用脚本必须在修改 systemd 前拒绝文件系统根目录路径参数。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora 直连启用脚本拒绝控制字符参数时必须给出明确错误。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '不能是文件系统根目录',
+    reason:
+      'Pingora 直连启用脚本拒绝文件系统根目录路径时必须给出明确错误。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'assertApplyRejectsSymlinkDropinDirectoryBeforeInstall',
+    reason: 'Pingora 直连启用检查必须覆盖符号链接 drop-in 目录负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'assertApplyRejectsSymlinkDropinFileBeforeInstall',
+    reason: 'Pingora 直连启用检查必须覆盖符号链接 drop-in 目标负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'assertRejectsControlCharacterInputsBeforeApply',
+    reason:
+      'Pingora 直连启用检查必须覆盖控制字符参数会在 apply 写 systemd 前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'assertFilesystemRootPathsRejected',
+    reason:
+      'Pingora 直连启用检查必须覆盖文件系统根目录路径会在 apply 写 systemd 前失败。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--preflight-script 必须是绝对路径',
+    reason:
+      'Pingora 直连启用脚本的 preflight 脚本路径必须固定为绝对路径，避免切换窗口受 cwd 影响。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--direct-live-script 必须是绝对路径',
+    reason:
+      'Pingora 直连启用脚本的 direct live smoke 脚本路径必须固定为绝对路径，避免切换窗口受 cwd 影响。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '相对路径 direct preflight 脚本必须被拒绝',
+    reason: 'Pingora 直连启用检查必须覆盖 direct preflight 脚本相对路径负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '相对路径 direct live smoke 脚本必须被拒绝',
+    reason: 'Pingora 直连启用检查必须覆盖 direct live smoke 脚本相对路径负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'dry-run 不应删除临时 drop-in 文件',
+    reason: 'Pingora 直连回退检查必须证明默认 dry-run 不修改 drop-in。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'dry-run 必须展示回退后 systemd drop-in 移除核验',
+    reason: 'Pingora 直连回退检查必须覆盖回退后的 systemd 移除核验步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'dry-run 必须展示回退后 ExecStart 指向核验',
+    reason: 'Pingora 直连回退检查必须覆盖回退后的 current release ExecStart 核验。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '回退脚本 ExecStart 核验必须以随包主 service 模板为真相源',
+    reason: 'Pingora 直连回退脚本必须以随包主 service 模板为 ExecStart 真相源。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'dry-run 必须展示 reload Nginx 后 active 核验',
+    reason: 'Pingora 直连回退检查必须覆盖 Nginx reload 后状态核验步骤。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'dry-run 必须展示 Nginx 入口 smoke',
+    reason: 'Pingora 直连回退检查必须覆盖 Nginx smoke dry-run 命令。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '--apply 缺少 --reload-nginx 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖 apply 跳过 Nginx reload 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'nginx -t 失败时 rollback apply 必须失败',
+    reason: 'Pingora 直连回退检查必须覆盖 Nginx 配置语法错误负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '--apply 缺少 --nginx-smoke-url 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖缺少 Nginx smoke URL 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '缺少 --nginx-smoke-host 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖 loopback smoke 缺少 Host 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '非法 --nginx-smoke-host 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖非法 smoke Host 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'Nginx smoke 失败时 rollback apply 必须失败',
+    reason: 'Pingora 直连回退检查必须覆盖 Nginx smoke 失败负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'Nginx smoke 响应体不匹配时 rollback apply 必须失败',
+    reason: 'Pingora 直连回退检查必须覆盖 Nginx smoke 响应体漂移负例。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover rollback apply 必须使用显式传入的 Nginx smoke body 片段',
+    reason:
+      'Pingora cutover runbook 自检必须覆盖 rollback Nginx smoke body 显式配置门禁。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'rollbackNginxSmokeExpectBody',
+    reason: 'Pingora cutover runbook 必须把 rollback Nginx smoke body 片段作为显式配置。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'dry-run 必须展示 health patrol env 回退后复核命令',
+    reason: 'Pingora 直连回退检查必须覆盖 health patrol env 复核 dry-run 命令。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '相对路径 --health-patrol-env-file 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖 health patrol env 相对路径负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'health patrol env 仍停留在 pingora-direct 时 rollback apply 必须失败',
+    reason: 'Pingora 直连回退检查必须覆盖巡检 env 未切回 nginx 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'dry-run 必须展示 Pingora shadow probe 命令且隐藏 token',
+    reason: 'Pingora 直连回退检查必须覆盖 shadow probe dry-run 命令并避免泄露 token。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'shadow probe URL 缺少 token 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖 shadow probe 参数成对出现。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'Pingora shadow probe body 错误时 rollback apply 必须失败',
+    reason: 'Pingora 直连回退检查必须覆盖 shadow probe 响应身份错误负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'systemctl show ExecStart 指向旧 release 时 rollback apply 必须失败',
+    reason: 'Pingora 直连回退检查必须覆盖 systemd ExecStart 漂到旧 release 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '--service-unit-path 必须是绝对路径',
+    reason: 'Pingora 直连回退检查必须覆盖主 service 模板相对路径负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '--dropin-path 必须是绝对路径',
+    reason: 'Pingora 直连回退检查必须覆盖相对路径负例。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'require_absolute_path_if_path_like "--nginx-binary"',
+    reason:
+      'Pingora 直连回退脚本覆盖 Nginx 二进制时，路径形式必须固定为绝对路径。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'require_absolute_path_if_path_like "--curl-binary"',
+    reason:
+      'Pingora 直连回退脚本覆盖 curl 二进制时，路径形式必须固定为绝对路径。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '相对路径 --nginx-binary 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖 Nginx 二进制相对路径负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '相对路径 --curl-binary 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖 curl 二进制相对路径负例。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'validate_http_url "--nginx-smoke-url"',
+    reason: 'Pingora 直连回退脚本必须在改 systemd 前拒绝非法 Nginx smoke URL。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'reject_control_characters',
+    reason:
+      'Pingora 直连回退脚本必须在 nginx -t、删除 drop-in 或 reload 前拒绝带换行或 NUL 的回退参数。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: 'reject_filesystem_root_path',
+    reason:
+      'Pingora 直连回退脚本必须在 nginx -t、删除 drop-in 或 reload 前拒绝文件系统根目录路径参数。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '不能包含换行或 NUL 字符',
+    reason:
+      'Pingora 直连回退脚本拒绝控制字符参数时必须给出明确错误。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-rollback.sh',
+    includes: '不能是文件系统根目录',
+    reason:
+      'Pingora 直连回退脚本拒绝文件系统根目录路径时必须给出明确错误。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: '非法 --nginx-smoke-url 必须被拒绝',
+    reason: 'Pingora 直连回退检查必须覆盖非法 Nginx smoke URL 负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'assertRejectsControlCharacterInputsBeforeApply',
+    reason:
+      'Pingora 直连回退检查必须覆盖控制字符参数会在 nginx -t 和删除 drop-in 前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'assertRejectsFilesystemRootPathsBeforeApply',
+    reason:
+      'Pingora 直连回退检查必须覆盖文件系统根目录路径会在 nginx -t 和删除 drop-in 前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'assertApplyRejectsSymlinkDropinDirectoryBeforeNginxTest',
+    reason: 'Pingora 直连回退检查必须覆盖符号链接 drop-in 目录会在 nginx -t 前失败。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'assertApplyRejectsSymlinkDropinFileBeforeRemoval',
+    reason: 'Pingora 直连回退检查必须覆盖符号链接 drop-in 目标不会删除真实目标文件。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-rollback.mjs',
+    includes: 'assertApplyRejectsDirectoryDropinTargetBeforeNginxTest',
+    reason: 'Pingora 直连回退检查必须覆盖目录型 drop-in 目标会在 nginx -t 前失败。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'scripts/deploy/pingora-direct-rollback.sh',
+    reason: 'API deploy 必须把 Pingora 直连回退脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'scripts/deploy/pingora-direct-enable.sh',
+    reason: 'API deploy 必须把 Pingora 直连启用脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'scripts/check-pingora-direct-preflight.mjs',
+    reason: 'API deploy 必须把 Pingora 直连预检脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'scripts/check-pingora-canary-live.mjs',
+    reason: 'API deploy 必须把 Pingora canary live smoke 脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'scripts/check-pingora-direct-live.mjs',
+    reason:
+      'API deploy 必须把 Pingora 直连 live smoke 脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'scripts/check-pingora-release-readiness.mjs',
+    reason:
+      'API deploy 必须把 Pingora release readiness 聚合门禁脚本复制到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'deploy/pingora',
+    reason: 'API deploy 必须把 Pingora 配置目录复制到 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'deploy/systemd',
+    reason:
+      'API deploy 必须把 systemd 配置目录复制到 current release，供直连预检读取主 service 和 drop-in 模板。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'ENV_DEPLOY_DIR_SOURCE',
+    reason: 'API deploy 必须从发布包内复制 deploy/env 示例目录。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/production-api-deploy.sh',
+    reason: 'API release build 动态烟测必须覆盖随产物执行的 deploy 脚本。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'API release README 必须说明随包携带 API Deploy 执行入口',
+    reason:
+      'API release build 动态烟测必须覆盖发布包 README 中的 deploy 执行入口说明。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/maintenance-on.sh',
+    reason: 'API release build 动态烟测必须覆盖 deploy 同目录维护开启脚本。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/maintenance-off.sh',
+    reason: 'API release build 动态烟测必须覆盖 deploy 同目录维护关闭脚本。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/pingora-direct-enable.sh',
+    reason: 'API release build 动态烟测必须覆盖直连启用脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/pingora-direct-rollback.sh',
+    reason: 'API release build 动态烟测必须覆盖直连回退脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason: 'API release build 动态烟测必须覆盖 health patrol env 切换脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'API release build 动态烟测必须覆盖 gateway env shadow 切换脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/check-pingora-direct-preflight.mjs',
+    reason: 'API release build 动态烟测必须覆盖直连预检脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/check-production-health-patrol-env.mjs',
+    reason:
+      'API release build 动态烟测必须覆盖健康巡检 env 复核脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/check-pingora-release-readiness.mjs',
+    reason:
+      'API release build 动态烟测必须覆盖 Pingora release readiness 聚合门禁脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/check-pingora-canary-live.mjs',
+    reason:
+      'API release build 动态烟测必须覆盖 canary live smoke 脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/check-pingora-direct-live.mjs',
+    reason:
+      'API release build 动态烟测必须覆盖直连 live smoke 脚本进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'deploy/systemd/genarrative-pingora-gateway.service',
+    reason: 'API release build 动态烟测必须覆盖 systemd 模板进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'deploy/pingora/pingora-gateway.env.example',
+    reason: 'API release build 动态烟测必须覆盖 Pingora 配置进入发布包。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: '--skip-api-build',
+    reason: 'API release build 动态烟测必须避免真实构建 Rust。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/deploy/production-api-deploy.sh',
+    reason: 'API deploy 动态烟测必须从发布产物内执行 deploy 脚本。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/deploy/maintenance-on.sh',
+    reason: 'API deploy 动态烟测必须覆盖 deploy 同目录维护开启脚本。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/deploy/maintenance-off.sh',
+    reason: 'API deploy 动态烟测必须覆盖 deploy 同目录维护关闭脚本。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/check-pingora-canary-live.mjs',
+    reason:
+      'API deploy 动态烟测必须覆盖 Pingora canary live smoke 脚本进入 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/check-pingora-release-readiness.mjs',
+    reason:
+      'API deploy 动态烟测必须覆盖 Pingora release readiness 聚合门禁脚本进入 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'release-manifest.json 缺少 pingora-gateway artifact',
+    reason:
+      'API deploy 必须阻断带 Pingora 二进制但 manifest 未登记 Pingora artifact 的发布包。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '发布产物缺少 release-manifest.json',
+    reason:
+      'API deploy 必须强制要求 release manifest，避免 current release 缺少产物证据根。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'require_absolute_path "${RELEASE_ROOT}" "--release-root"',
+    reason:
+      'API deploy 发布根目录必须是绝对路径，避免 Jenkins 工作目录影响 release 位置。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'require_absolute_path "${CURRENT_LINK}" "--current-link"',
+    reason:
+      'API deploy current 链接必须是绝对路径，避免相对路径切错入口。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'require_absolute_path "${API_ENV_FILE}" "--api-env-file"',
+    reason:
+      'API deploy 环境文件必须是绝对路径，避免相对路径写入工作区文件。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '^[0-9A-Za-z][0-9A-Za-z._-]*$',
+    reason:
+      'API deploy release version 必须以数字或字母开头，避免点目录或隐藏 staging 名称污染 release 根目录。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '--version 不能是点目录',
+    reason:
+      'API deploy 必须显式拒绝 . / .. 这类点目录版本名。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '.staging.$$',
+    reason:
+      'API deploy 必须先写 staging release，避免失败时污染正式 release 目录。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '目标 release 已存在，拒绝覆盖或合并旧文件',
+    reason:
+      'API deploy 必须拒绝同版本 release 目录复用，避免旧文件混入 current release。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '目标 release 在发布过程中出现，拒绝合并 staging',
+    reason:
+      'API deploy 在最终提升前必须再次拒绝同版本 release 竞态出现，避免把 staging 合并进旧目录。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'current 链接路径已存在但不是符号链接，拒绝覆盖',
+    reason:
+      'API deploy 必须拒绝目录型 current 路径，避免 ln 把新链接写进旧目录。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'ln -sfnT "${RELEASE_DIR}" "${CURRENT_LINK}"',
+    reason:
+      'API deploy 切换 current 必须用 -T 固定符号链接替换语义。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'mv -T "${STAGING_RELEASE_DIR}" "${RELEASE_DIR}"',
+    reason:
+      'API deploy 必须用非合并语义把 staging release 提升为正式 release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsPingoraArtifactMissingManifestEntry',
+    reason:
+      'API deploy 动态烟测必须覆盖 Pingora 二进制与 release manifest 漂移负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingReleaseManifestFails',
+    reason:
+      'API deploy 动态烟测必须覆盖缺少 release manifest 的失败维护模式。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertReleaseManifestMissingApiArtifactFails',
+    reason:
+      'API deploy 动态烟测必须覆盖 release manifest 缺少 api-server artifact 的负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsDotVersion',
+    reason:
+      'API deploy 动态烟测必须覆盖 . 版本名负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsDotDotVersion',
+    reason:
+      'API deploy 动态烟测必须覆盖 .. 版本名负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsVersionStartingWithDot',
+    reason:
+      'API deploy 动态烟测必须覆盖以点开头版本名负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsExistingReleaseDirectory',
+    reason:
+      'API deploy 动态烟测必须覆盖同版本 release 目录已存在时拒绝覆盖。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsDirectoryCurrentLink',
+    reason:
+      'API deploy 动态烟测必须覆盖 current 路径不是符号链接时拒绝覆盖。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsRelativeReleaseRoot',
+    reason:
+      'API deploy 动态烟测必须覆盖 release root 相对路径负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsRelativeCurrentLink',
+    reason:
+      'API deploy 动态烟测必须覆盖 current link 相对路径负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsRelativeApiEnvFile',
+    reason:
+      'API deploy 动态烟测必须覆盖 api env 文件相对路径负例。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployCleansStagingReleaseOnFailure',
+    reason:
+      'API deploy 动态烟测必须覆盖失败时清理 staging release 且不留下正式 release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsFinalReleaseRaceAndCleansStaging',
+    reason:
+      'API deploy 动态烟测必须覆盖最终提升前 release 目录竞态出现时拒绝合并并清理 staging。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingBackupScriptFails',
+    reason: 'API deploy 动态烟测必须覆盖缺少数据库备份脚本的失败维护模式。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingHealthPatrolScriptFails',
+    reason: 'API deploy 动态烟测必须覆盖缺少健康巡检脚本的失败维护模式。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertMissingHealthPatrolEnvCheckFails',
+    reason:
+      'API deploy 动态烟测必须覆盖缺少健康巡检 env 复核脚本的失败维护模式。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/check-pingora-direct-preflight.mjs',
+    reason: 'API deploy 动态烟测必须覆盖直连预检脚本进入 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/check-production-health-patrol-env.mjs',
+    reason:
+      'API deploy 动态烟测必须覆盖健康巡检 env 复核脚本进入 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason: 'API deploy 动态烟测必须覆盖 health patrol env 切换脚本进入 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'API deploy 动态烟测必须覆盖 gateway env shadow 切换脚本进入 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/check-pingora-direct-live.mjs',
+    reason:
+      'API deploy 动态烟测必须覆盖直连 live smoke 脚本进入 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'deploy/systemd/genarrative-pingora-gateway.service',
+    reason: 'API deploy 动态烟测必须覆盖 systemd 模板进入 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'deploy/pingora/pingora-gateway.env.example',
+    reason: 'API deploy 动态烟测必须覆盖 Pingora 配置进入 current release。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'fakeBin',
+    reason:
+      'API deploy 动态烟测必须使用 fake systemctl/curl，禁止触碰真实服务。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'scripts/deploy/pingora-direct-rollback.sh',
+    reason: 'API Build 归档必须包含 Pingora 直连回退脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'scripts/deploy/pingora-direct-enable.sh',
+    reason: 'API Build 归档必须包含 Pingora 直连启用脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'scripts/check-pingora-direct-preflight.mjs',
+    reason: 'API Build 归档必须包含 Pingora 直连预检脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'scripts/check-pingora-direct-live.mjs',
+    reason: 'API Build 归档必须包含 Pingora 直连 live smoke 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'deploy/pingora/**',
+    reason: 'API Build 归档必须包含 Pingora 配置目录。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'deploy/systemd/**',
+    reason: 'API Build 归档必须包含 systemd 配置目录。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'scripts/deploy/pingora-direct-rollback.sh',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 直连回退脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'scripts/deploy/pingora-direct-enable.sh',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 直连启用脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'scripts/check-pingora-direct-preflight.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 直连预检脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'scripts/check-pingora-direct-live.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 直连 live smoke 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'deploy/pingora/**',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 配置目录。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'deploy/systemd/**',
+    reason: 'API Deploy 复制上游产物时必须包含 systemd 配置目录。',
+  },
+  {
+    file: 'deploy/pingora/nginx-route-parity.matrix.json',
+    includes: 'spacetime_subscribe',
+    reason: 'Pingora 路由矩阵必须覆盖 SpacetimeDB WebSocket subscribe。',
+  },
+  {
+    file: 'scripts/check-pingora-route-parity.mjs',
+    includes: 'deploy/nginx/genarrative.conf',
+    reason: 'Pingora 路由矩阵检查必须覆盖生产 Nginx 模板。',
+  },
+  {
+    file: 'scripts/check-pingora-route-parity.mjs',
+    includes: 'deploy/nginx/genarrative-dev-http.conf',
+    reason: 'Pingora 路由矩阵检查必须覆盖开发服 Nginx 模板。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'ROUTE_PARITY_MATRIX_JSON',
+    reason: 'Pingora Rust 路由单测必须读取共享路由矩阵。',
+  },
+  {
+    file: 'scripts/check-nginx-pingora-canary.mjs',
+    includes: '--require-nginx',
+    reason:
+      'Pingora canary 校验脚本必须支持在有 Nginx 的环境强制执行 nginx -t。',
+  },
+  {
+    file: 'scripts/check-nginx-pingora-canary.mjs',
+    includes: 'proxy_set_header Upgrade $http_upgrade;',
+    reason:
+      'Pingora canary 校验脚本必须覆盖 SpacetimeDB WebSocket Upgrade 设置。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'SpacetimeDB WebSocket Upgrade',
+    reason: 'Pingora 网关 smoke 必须覆盖 SpacetimeDB WebSocket 代理。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'v2.bsatn.spacetimedb',
+    reason: 'Pingora 网关 smoke 必须覆盖 SpacetimeDB WSS 子协议透传。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'gzip 压缩响应',
+    reason: 'Pingora 网关 smoke 必须覆盖 gzip 响应压缩。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'gzip-only 压缩算法白名单',
+    reason: 'Pingora 网关 smoke 必须覆盖压缩算法白名单。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'gzip 最小长度不压缩小响应',
+    reason: 'Pingora 网关 smoke 必须覆盖 Nginx gzip_min_length parity。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'gzip types 不压缩图片资源',
+    reason: 'Pingora 网关 smoke 必须覆盖 Nginx gzip_types parity。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '主站指纹静态资源长缓存',
+    reason: 'Pingora 网关 smoke 必须覆盖 Vite 指纹资源 immutable 缓存头。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: "response.headers['cache-control'] === 'no-cache'",
+    reason: 'Pingora 网关 smoke 必须覆盖 HTML 和普通静态资源 no-cache 口径。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '静态资源 If-None-Match 返回 304',
+    reason: 'Pingora 网关 smoke 必须覆盖静态资源 ETag 协商缓存。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '静态资源 If-Modified-Since 返回 304',
+    reason: 'Pingora 网关 smoke 必须覆盖静态资源 Last-Modified 协商缓存。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '静态资源非读取方法返回 405',
+    reason: 'Pingora 网关 smoke 必须覆盖静态资源只允许 GET / HEAD。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'GET, HEAD',
+    reason: 'Pingora 静态响应必须对非读取方法返回 Allow: GET, HEAD。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '静态资源 Range 返回 206',
+    reason: 'Pingora 网关 smoke 必须覆盖静态资源单 Range 局部读取。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '静态资源 If-Range 日期匹配返回 206',
+    reason: 'Pingora 网关 smoke 必须覆盖静态资源 If-Range 匹配时继续返回局部内容。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '静态资源 If-Range 旧日期回完整文件',
+    reason: 'Pingora 网关 smoke 必须覆盖静态资源 If-Range 不匹配时回完整内容。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '静态资源越界 Range 返回 416',
+    reason: 'Pingora 网关 smoke 必须覆盖静态资源越界 Range 响应。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'access log 静态边界状态对账',
+    reason:
+      'Pingora 网关 smoke 必须按 request_id 对账静态 304 / 405 / 206 / 416 access log，避免直连证据链漏掉本地响应状态。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'entry.method === expected.method',
+    reason:
+      'Pingora 网关 smoke 必须按 request_id 对账静态 access log 的 method，避免 HEAD / POST 边界被状态码巧合掩盖。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'Accept-Ranges',
+    reason: 'Pingora 静态响应必须声明 bytes Range 能力。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'Content-Range',
+    reason: 'Pingora 静态 Range 响应必须写入 Content-Range。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'Last-Modified',
+    reason: 'Pingora 静态响应必须写入 Last-Modified，避免直连后协商缓存能力退化。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'if-none-match',
+    reason: 'Pingora 静态响应必须支持 ETag 条件请求返回 304。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL',
+    reason: 'Pingora 网关必须暴露指纹静态资源 Cache-Control 配置。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'has_fingerprinted_file_name',
+    reason: 'Pingora 网关必须按 Vite 指纹文件名区分长期缓存静态资源。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: '不能包含换行或 NUL 字符',
+    reason: 'Pingora 静态缓存头配置必须拒绝响应头注入字符。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL',
+    reason: 'Pingora 网关 smoke 必须覆盖 gzip 配置校验。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS',
+    reason: 'Pingora 网关 smoke 必须覆盖压缩算法配置校验。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'GATEWAY_CONCURRENCY_LIMITED',
+    reason: 'Pingora 网关 smoke 必须覆盖接流并发保护。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'PAYLOAD_TOO_LARGE',
+    reason: 'Pingora 网关 smoke 必须覆盖请求体大小限制。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'access log 落盘',
+    reason: 'Pingora 网关 smoke 必须覆盖 access log 文件写入。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '配置错误启动失败',
+    reason: 'Pingora 网关 smoke 必须覆盖不安全配置 fail-fast。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'SECRET_VALUE_FLAGS',
+    reason: 'Pingora 网关 smoke 必须集中维护敏感参数脱敏列表。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'redactSecretArgs(args).join',
+    reason: 'Pingora 网关 smoke 打印 direct live 命令时必须隐藏 probe token。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'GATEWAY_UPSTREAM_ERROR',
+    reason: 'Pingora 网关 smoke 必须覆盖上游断连时的稳定 JSON 错误。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'GATEWAY_UPSTREAM_TIMEOUT',
+    reason: 'Pingora 网关 smoke 必须覆盖上游超时时的稳定 JSON 错误。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'TLS 直连接口返回 index.html',
+    reason: 'Pingora 网关 smoke 必须覆盖可选 TLS 直连接口。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'HTTP 入口 301 到 HTTPS',
+    reason: 'Pingora 网关 smoke 必须覆盖可选 HTTP 到 HTTPS 重定向入口。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'direct-access-log',
+    reason: 'Pingora direct live smoke 必须覆盖 Pingora access log 落盘校验。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-static-asset',
+    reason:
+      'Pingora direct live smoke 必须自动发现并探测首页引用的静态资源，避免直连只验证 API / WSS 路径。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-static-asset-range',
+    reason:
+      'Pingora direct live smoke 必须验证首页静态资产 Range: bytes=0-0，避免直连后媒体/浏览器探测能力退化。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-static-asset-head',
+    reason:
+      'Pingora direct live smoke 必须验证首页静态资产 HEAD 行为，覆盖 curl -I、监控探针和 CDN 预检。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-static-fingerprinted-asset',
+    reason:
+      'Pingora direct live smoke 必须额外探测首页引用的 Vite 指纹静态资源。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'public, max-age=31536000, immutable',
+    reason:
+      'Pingora direct live smoke 必须验证指纹静态资源长期缓存头，避免直连后旧 tab chunk 缓存口径退化。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'pickEvidenceHeaders',
+    reason:
+      'Pingora direct live smoke 必须把静态响应头白名单写入 JSON 证据，便于切换证据包复盘。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: "'content-range'",
+    reason:
+      'Pingora direct live smoke 的静态响应头 JSON 证据必须包含 Content-Range。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-static-fingerprinted-asset-head',
+    reason:
+      'Pingora direct live smoke 必须验证指纹静态资源 HEAD 行为。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-static-fingerprinted-asset-range',
+    reason:
+      'Pingora direct live smoke 必须验证指纹静态资源 Range 行为。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-static-asset-etag-304',
+    reason:
+      'Pingora direct live smoke 必须验证首页静态资源 ETag 条件请求返回 304。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'https-static-fingerprinted-asset-etag-304',
+    reason:
+      'Pingora direct live smoke 必须验证指纹静态资源 ETag 条件请求返回 304。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '<script type="module" src="/assets/index-B4dmVw0r.js"></script>',
+    reason:
+      'Pingora 本地 smoke fixture 必须让 direct live 自动发现指纹静态资源。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'direct live 必须验证首页引用的指纹静态资源 GET 200。',
+    reason:
+      'Pingora 本地 smoke 必须从 direct live JSON 结构化确认指纹资源 GET 证据。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'direct live JSON 必须保留指纹静态资源 immutable Cache-Control 证据。',
+    reason:
+      'Pingora 本地 smoke 必须确认 direct live JSON 可复盘指纹资源长期缓存头。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'direct live JSON 必须保留指纹静态资源 Content-Range 证据。',
+    reason:
+      'Pingora 本地 smoke 必须确认 direct live JSON 可复盘指纹资源 Range 响应头。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'direct live access log 必须保留指纹静态 Range 的 method/path/status 明细。',
+    reason:
+      'Pingora 本地 smoke 必须确认指纹资源 Range 进入 access log method/path/status 证据。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'direct live 必须验证首页引用的指纹静态资源 ETag 304。',
+    reason:
+      'Pingora 本地 smoke 必须从 direct live JSON 结构化确认指纹资源 304 证据。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'direct live access log 必须保留指纹静态 ETag 304 的 method/path/status 明细。',
+    reason:
+      'Pingora 本地 smoke 必须确认指纹资源 304 进入 access log method/path/status 证据。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'Content-Range 不符合 bytes 0-0/<len>',
+    reason:
+      'Pingora direct live smoke 必须校验静态资产 Range 响应的 Content-Range。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'request_id',
+    reason: 'Pingora direct live smoke 必须按 request_id 反查 access log。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'matchedCount',
+    reason:
+      'Pingora direct live smoke 的 access log 证据必须记录匹配数量，便于证据包复盘。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'mismatches',
+    reason:
+      'Pingora direct live smoke 的 access log 证据必须保留 method/path/status 漂移明细。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'expectedMethod',
+    reason:
+      'Pingora direct live smoke 的 access log 反查必须记录每个 request_id 的预期 HTTP 方法。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'actualMethod',
+    reason:
+      'Pingora direct live smoke 的 access log 反查必须记录每个 request_id 的实际 HTTP 方法。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'expectedStatusCode',
+    reason:
+      'Pingora direct live smoke 的 access log 反查必须记录每个 request_id 的预期状态码。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-live.mjs',
+    includes: 'actualStatusCode',
+    reason:
+      'Pingora direct live smoke 的 access log 反查必须记录每个 request_id 的实际状态码。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'direct-access-log 检查必须保留 mismatches 明细数组。',
+    reason:
+      'Pingora 切流证据包自测必须防止 direct live access log JSON 明细退化。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'direct-access-log 检查必须保留已匹配 request_id 的预期方法。',
+    reason:
+      'Pingora 切流证据包自测必须防止 direct live access log method 明细退化。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'direct-live.json 必须保留指纹静态资源 Cache-Control 证据。',
+    reason:
+      'Pingora 切流证据包自测必须防止 direct live 静态响应头证据退化。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'direct-live.json 必须保留指纹静态资源 Content-Range 证据。',
+    reason:
+      'Pingora 切流证据包自测必须防止 direct live Range 响应头证据退化。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'directLiveStaticHeaders',
+    reason:
+      'Pingora 切流证据包 manifest 必须提升 direct live 静态响应头摘要，便于快速复盘。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'directLiveStaticHeaders?.ok',
+    reason:
+      'Pingora 切流证据包必须把静态响应头摘要完整性纳入 direct live 成功判定。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'ETag 304 statusCode 应为 304',
+    reason:
+      'Pingora 切流证据包必须诊断静态 ETag 304 证据缺失。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'Range statusCode 应为 206',
+    reason:
+      'Pingora 切流证据包必须诊断静态 Range 证据缺失。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'manifest 必须提升指纹静态资源 Content-Range 证据。',
+    reason:
+      'Pingora 切流证据包自测必须防止 manifest 静态响应头摘要退化。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertDirectLiveMissingStaticHeadersSummaryFails',
+    reason:
+      'Pingora 切流证据包自测必须覆盖 direct live JSON 缺少静态响应头证据的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertDirectLiveStaticHeaderDiagnosticsFails',
+    reason:
+      'Pingora 切流证据包自测必须覆盖静态 Range / 304 摘要不完整时失败。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'manifest 必须提升普通静态资源 ETag 304 证据。',
+    reason:
+      'Pingora 切流证据包自测必须防止 manifest 普通静态 304 摘要退化。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'summaryDirectLiveStaticHeaders',
+    reason:
+      'Pingora 证据根目录审计必须读取阶段 manifest 的 direct live 静态响应头摘要。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '--require-phase-pingora-env-shadow',
+    reason:
+      'Pingora 证据根目录审计必须支持强制校验 post-rollback Pingora env shadow 摘要。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'summaryPingoraEnvShadow',
+    reason:
+      'Pingora 证据根目录审计必须读取阶段 manifest 的 Pingora env shadow 摘要。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'tlsCertFile 必须为空',
+    reason:
+      'Pingora 证据根目录审计必须拒绝 post-rollback TLS 证书路径残留。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'shadowReady 必须为 true',
+    reason:
+      'Pingora 证据根目录审计必须拒绝 post-rollback 快照姿态不是 shadow 的证据。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'directLiveStaticHeaders: latest.summaryDirectLiveStaticHeaders',
+    reason:
+      'Pingora 证据根目录审计输出必须提升阶段 direct live 静态响应头摘要。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertRequirePhasePingoraEnvShadowFailsWhenDirectLowPortsRemain',
+    reason:
+      'Pingora 证据根目录审计自测必须覆盖 post-rollback 低端口 env 残留失败路径。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: '证据根审计输出必须提升 post-enable direct live 指纹静态 Cache-Control 摘要。',
+    reason:
+      'Pingora 证据根目录审计自测必须覆盖 direct live 静态响应头摘要输出。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: '证据根审计输出必须提升 post-enable direct live access log 摘要。',
+    reason:
+      'Pingora 证据根目录审计自测必须覆盖 direct live access log 摘要输出。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: '静态 GET / HEAD / 304 / Range 结果还必须在 `direct-live.json` 中保留白名单响应头',
+    reason:
+      'Pingora 试点文档必须说明 direct live JSON 会归档静态响应头白名单证据。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: '`cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`',
+    reason:
+      'Pingora 试点文档必须固定 direct live 静态响应头证据白名单。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: '静态摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 / Last-Modified 304 证据时，证据包都会直接记为 `CRITICAL`',
+    reason:
+      'Pingora 试点文档必须说明静态响应头证据不完整会让证据包失败。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: '总审计输出会把阶段 manifest 中的 `directLiveAccessLog` 与 `directLiveStaticHeaders` 一并带到对应 `phases[]` 项',
+    reason:
+      'Pingora 试点文档必须说明最终证据根审计会输出 direct live 摘要。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'direct live JSON 只给静态 GET / HEAD / 304 / Range 写入白名单 `headers`',
+    reason:
+      'Nginx README 必须说明 Pingora direct live 静态头部证据归档口径。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'manifest.summary.directLiveStaticHeaders',
+    reason:
+      'Nginx README 必须说明切流 manifest 会提升 direct live 静态响应头摘要。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '证据包会记为 `CRITICAL`',
+    reason:
+      'Nginx README 必须说明 direct live 静态响应头摘要缺关键证据时会阻断证据包。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: 'API / WSS 检查不落原始响应头',
+    reason:
+      '团队共享决策必须记录 direct live 只归档静态白名单响应头。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: 'directLiveStaticHeaders',
+    reason:
+      '团队共享决策必须记录切流 manifest 提升 direct live 静态响应头摘要。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: '静态头摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 / Last-Modified 304 证据时整包记为 `CRITICAL`',
+    reason:
+      '团队共享决策必须记录静态响应头摘要不完整会阻断证据包。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: '不要把 `direct-live.json` 当成只有状态码的摘要',
+    reason:
+      '团队共享踩坑必须提醒 direct live JSON 需要可复盘静态响应头证据。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: 'manifest.summary.directLiveStaticHeaders',
+    reason:
+      '团队共享踩坑必须提醒切流 manifest 需要可快速复盘静态响应头摘要。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: '摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，证据包会直接记为 `CRITICAL`',
+    reason:
+      '团队共享踩坑必须提醒静态响应头摘要不完整会阻断证据包。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'directLiveAccessLog',
+    reason:
+      'Pingora 切流证据包 manifest 必须提升 direct live access log 摘要，便于快速复盘。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'direct live JSON missing direct-access-log result',
+    reason:
+      'Pingora 切流证据包必须在 direct live JSON 缺少 access log 结果时标记 CRITICAL。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertDirectLiveMissingAccessLogSummaryFails',
+    reason:
+      'Pingora 切流证据包自测必须覆盖 direct live JSON 缺少 access log 结果的负例。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: '--apply 必须同时提供 --direct-pingora-access-log',
+    reason: 'Pingora 直连启用 apply 必须强制 access log 落盘校验参数。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'direct_live_args+=(--json)',
+    reason:
+      'Pingora 直连启用 apply 后必须用 JSON 模式运行 direct live，才能校验结构化接流证据。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'direct live JSON 缺少 direct-access-log 结构化结果',
+    reason:
+      'Pingora 直连启用 apply 必须拒绝缺少 direct-access-log 结构化结果的 direct live 输出。',
+  },
+  {
+    file: 'scripts/deploy/pingora-direct-enable.sh',
+    includes: 'direct-access-log evidence checked=',
+    reason:
+      'Pingora 直连启用 apply 必须在 direct access log 结构化证据通过后输出摘要。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: '--apply 缺少 --direct-pingora-access-log 必须被拒绝',
+    reason: 'Pingora 直连启用自测必须覆盖缺少 access log 参数的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-direct-enable.mjs',
+    includes: 'assertApplyFailsWhenDirectLiveAccessLogJsonMissing',
+    reason:
+      'Pingora 直连启用自测必须覆盖 direct live 退出 0 但缺少 access log JSON 证据的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: '--pingora-access-log',
+    reason: 'Pingora 本地网关 smoke 必须把临时 access log 传给 direct live smoke。',
+  },
+  {
+    file: 'server-rs/crates/pingora-gateway/src/main.rs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS',
+    reason:
+      'Pingora 网关必须暴露上游读取超时配置，避免正式切换时和 Nginx 超时口径漂移。',
+  },
   {
     file: 'scripts/deploy/production-api-deploy.sh',
     includes: 'production-health-patrol.mjs',
     reason: 'API deploy 必须把健康巡检脚本复制到 current release。',
   },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '发布产物缺少数据库备份脚本',
+    reason: 'API deploy 缺少数据库备份脚本时必须 fail-fast。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: '发布产物缺少生产健康巡检脚本',
+    reason: 'API deploy 缺少健康巡检脚本时必须 fail-fast。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    excludes: 'WORKSPACE_BACKUP_SCRIPT_SOURCE',
+    reason: 'API deploy 不应再从部署工作区兜底复制数据库备份脚本。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    excludes: 'WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE',
+    reason: 'API deploy 不应再从部署工作区兜底复制健康巡检脚本。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    excludes: '回退使用部署工作区脚本',
+    reason: 'API deploy 不应再用部署工作区脚本掩盖发布产物缺失。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'pingora-gateway.sha256',
+    reason: 'API deploy 看到 Pingora 影子网关产物时必须校验 checksum 后复制。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'ensure_pingora_shadow_service',
+    reason:
+      'API deploy 看到 Pingora 影子网关产物时必须先进入受控 shadow service 启动流程。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'systemctl cat "${service_name}"',
+    reason:
+      'API deploy 自动启动或重启 Pingora 前必须读取 systemd 最终配置。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'CAP_NET_BIND_SERVICE',
+    reason:
+      'API deploy 自动启动或重启 Pingora 前必须拒绝疑似 direct-entry 低端口 capability。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'Pingora 自动启动只允许 shadow 监听 127.0.0.1:18081',
+    reason:
+      'API deploy 自动启动 Pingora 时必须限制为本机 shadow 高端口，避免误拉起公网直连入口。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'systemctl restart "${service_name}"',
+    reason:
+      'API deploy 看到 Pingora 影子网关产物且 shadow 配置安全时必须随 current release 启动或重启。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRestartsActivePingoraWhenArtifactIncluded',
+    reason:
+      'API deploy 动态烟测必须覆盖 Pingora 产物发布后 active shadow service 自动重启。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployStartsInactivePingoraWhenArtifactIncluded',
+    reason:
+      'API deploy 动态烟测必须覆盖 Pingora shadow service inactive 但配置安全时会被主动拉起。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsPingoraDirectEntryWhenArtifactIncluded',
+    reason:
+      'API deploy 动态烟测必须覆盖 direct-entry capability 下不会自动拉起 Pingora。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertDeployRejectsPingoraPublicListenWhenArtifactIncluded',
+    reason:
+      'API deploy 动态烟测必须覆盖公网监听 env 下不会自动拉起 Pingora。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'assertApiReleaseCanIncludePingoraGatewayArtifact',
+    reason: 'API release 动态烟测必须覆盖显式 include Pingora 影子网关产物。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: '--skip-pingora-gateway-build',
+    reason: 'API release 动态烟测应能用假二进制快速覆盖 Pingora 产物布局。',
+  },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'assertPingoraEnvProductionDefaults',
+    reason: 'API release 动态烟测必须校验 Pingora env 的生产安全默认值。',
+  },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'assertPingoraEnvProductionDefaults',
+    reason: 'API deploy 动态烟测必须校验 current release 内 Pingora env 的生产安全默认值。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED',
+    reason: 'Pingora 网关配置示例必须保留接流保护总开关。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT=1',
+    reason: 'Pingora 网关配置示例必须显式保留默认单实例接流保护口径。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=false',
+    reason: 'Pingora 网关配置示例必须默认不确认共享保护层。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED',
+    reason: 'Pingora 网关配置示例必须暴露 gzip 总开关。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN',
+    reason: 'Pingora 网关配置示例必须暴露可选 TLS 直连入口。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+    reason: 'Pingora 网关配置示例必须暴露可选 HTTP 到 HTTPS 重定向入口。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip',
+    reason: 'Pingora 网关配置示例必须暴露压缩算法白名单。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'Pingora 正式化口径固定为 gzip-only',
+    reason: 'Pingora 网关配置示例必须明确当前正式化压缩口径。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'Brotli',
+    reason: 'Pingora 试点文档必须说明 Brotli 尚未进入 Pingora 的边界。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'Pingora 正式化口径固定为 gzip-only',
+    reason: 'Pingora 试点文档必须把 Brotli 取舍落成明确结论。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    excludes: '补齐 Brotli 取舍',
+    reason: 'Pingora 试点文档不能继续把 Brotli 取舍留成待办。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: 'Pingora Brotli 不能只看 Content-Encoding',
+    reason: '团队共享踩坑必须记录 Pingora Brotli 端到端解压风险。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5',
+    reason: 'Pingora 网关配置示例必须对齐 Nginx gzip 压缩等级。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024',
+    reason: 'Pingora 网关配置示例必须对齐 Nginx gzip_min_length。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL=no-cache',
+    reason: 'Pingora 网关配置示例必须暴露 HTML / SPA fallback 缓存头。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL=public, max-age=31536000, immutable',
+    reason: 'Pingora 网关配置示例必须暴露指纹静态资源长期缓存头。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'Vite 指纹静态资源',
+    reason: 'Pingora 试点文档必须说明直连静态缓存头口径。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes:
+      'GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS=3600',
+    reason: 'Pingora 网关配置示例必须保留上游 API 读取超时口径。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes:
+      'GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_LONG_READ_TIMEOUT_SECONDS=3600',
+    reason: 'Pingora 网关配置示例必须保留长连接读取超时口径。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_API_MAX_CONCURRENT',
+    reason: 'Pingora 网关配置示例必须保留通用 API 并发保护参数。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_RATE_PER_SECOND',
+    reason: 'Pingora 网关配置示例必须保留公开列表 RPS 保护参数。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE',
+    reason: 'Pingora 网关配置示例必须暴露 access log 文件路径。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'API 上游未收到 X-Forwarded-Host',
+    reason: 'Pingora gateway smoke 必须断言 API 上游收到 Nginx parity 的 X-Forwarded-Host。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-smoke.mjs',
+    includes: 'API 上游 X-Forwarded-For 未追加 TCP 对端 IP',
+    reason:
+      'Pingora gateway smoke 必须断言 X-Forwarded-For 追加真实 TCP 对端 IP。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'API 代理头',
+    reason: 'Pingora 试点文档必须说明 API 代理头 parity 门禁。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'X-Real-IP',
+    reason: 'Pingora 试点文档必须说明 X-Real-IP 的 TCP 对端 IP 口径。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG',
+    reason: 'Pingora direct live env 示例必须暴露 direct access log 复核路径。',
+  },
+  {
+    file: 'deploy/env/pingora-direct-live.env.example',
+    includes: 'GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES=2000',
+    reason: 'Pingora direct live env 示例必须暴露 direct access log tail 行数。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log',
+    reason: 'Nginx README 的 Pingora 直连 runbook 必须包含 access log 落盘校验参数。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: '--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log',
+    reason: 'Pingora 试点文档必须展示 direct access log 落盘校验参数。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: '--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log',
+    reason: '生产运维文档必须展示 Pingora 直连 access log 落盘校验参数。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: '直连日志证据补充',
+    reason: '团队共享决策必须记录 Pingora 直连 access log 证据门禁。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: '--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log',
+    reason: '团队共享踩坑必须记录 Pingora 直连 access log 参数。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: '启用后 `--require-direct --release-runtime-only` 复核不再要求端口空闲',
+    reason:
+      '生产运维文档必须明确 Pingora 启用后直连复核不再要求 80/443 空闲。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: '不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`',
+    reason:
+      '生产运维文档必须阻止回退 smoke 继续沿用旧的固定 healthz 响应片段。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: "--rollback-nginx-smoke-expect-body '<!doctype html>'",
+    reason: '生产运维文档必须展示来自真实 Nginx 首页的回退响应体片段示例。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: '`--require-direct` 用于 Pingora 已接管后的直连复核，不再要求 `--direct-preflight-check-ports-free`',
+    reason:
+      'Pingora 试点文档必须明确端口释放检查只属于切流前和启用 apply 阶段。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: "--rollback-nginx-smoke-expect-body '<!doctype html>'",
+    reason: 'Pingora 试点文档必须展示真实 Nginx 回退 smoke 响应体片段。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '启用后 `--require-direct` 复核不再要求端口空闲',
+    reason: 'Nginx README 必须记录 Pingora 启用后 direct 复核的端口语义。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: "--nginx-smoke-expect-body '<!doctype html>'",
+    reason: 'Nginx README 必须展示真实 Nginx 回退 smoke 响应体片段。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`',
+    reason: 'Nginx README 必须防止回退 smoke 示例回到旧 healthz 口径。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: '不再默认假定 `/healthz` 会返回 `"ok":true`',
+    reason: '团队共享决策必须记录回退 smoke 的真实 Nginx 入口要求。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: '启用后复核应看到端口由 Pingora 占用而不是空闲',
+    reason:
+      '团队共享决策必须记录启用后 --require-direct 不再检查端口空闲。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: '不要继续用固定 `/healthz` 与 `"ok":true`',
+    reason: '团队共享踩坑必须提醒回退 smoke 不能沿用旧 healthz 片段。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: '启用后 `--require-direct` 复核不再要求端口空闲',
+    reason: '团队共享踩坑必须提醒端口空闲只属于切流前门禁。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    excludes:
+      '--nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body \'"ok":true\'',
+    reason: 'Nginx README 不应再给出固定 healthz + ok:true 的回退命令。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    excludes:
+      '--nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body \'"ok":true\'',
+    reason: '生产运维文档不应再给出固定 healthz + ok:true 的回退命令。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    excludes: 'rollback-nginx-smoke-expect-body="ok":true',
+    reason: '生产运维 runbook 不应再默认展示 ok:true 作为回退响应体片段。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    excludes: 'rollback-nginx-smoke-expect-body="ok":true',
+    reason: 'Pingora 试点 runbook 不应再默认展示 ok:true 作为回退响应体片段。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    excludes:
+      '--nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名>',
+    reason: '团队共享踩坑不应再把固定本机 healthz 当成可执行回退示例。',
+  },
+  {
+    file: 'deploy/pingora/pingora-gateway.env.example',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED',
+    reason: 'Pingora 网关配置示例必须暴露 X-Forwarded-For 信任确认开关。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'Brotli',
+    reason: 'Pingora 试点文档必须明确 gzip 以外的压缩边界。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '直连 Pingora 时，不把 Brotli parity 作为切换门禁',
+    reason: 'Nginx 压缩文档必须明确 Pingora Brotli 不作为直连切换门禁。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes:
+      'Genarrative-Api-Deploy` 只能从上游构建归档复制并执行 `build/<version>/scripts/deploy/production-api-deploy.sh`',
+    reason: 'Pingora 试点文档必须明确 API Deploy 执行入口来自 build 产物。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1',
+    reason: 'Pingora 试点文档必须明确多实例接流保护确认边界。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1',
+    reason: '生产运维文档必须明确多实例 Pingora 与进程内保护的启动 / preflight 边界。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1',
+    reason: '团队共享决策必须记录 Pingora 多实例接流保护边界。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: '禁止继续执行部署工作区根部脚本',
+    reason: '团队共享决策必须记录 API Deploy 不再执行 workspace 根部脚本。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: 'API deploy 脚本本身也不能继续用部署工作区根部',
+    reason:
+      '团队共享踩坑必须记录 workspace 根部 deploy 脚本会掩盖发布包布局问题。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: '备份脚本、健康巡检脚本和 env 示例目录同样不能从部署工作区兜底',
+    reason: '团队共享踩坑必须记录备份/巡检脚本也不能使用 workspace fallback。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'Pingora 影子网关已通过',
+    reason: 'Nginx 压缩文档必须说明 Pingora gzip parity 口径。',
+  },
   {
     file: 'jenkins/Jenkinsfile.production-api-build',
     includes: 'scripts/ops/production-health-patrol.mjs',
     reason: 'API Build 归档必须包含健康巡检脚本。',
   },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-current-release-audit.mjs',
+    reason: 'API Build 归档必须包含 Pingora current release 自审脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-status-snapshot.mjs',
+    reason: 'API Build 归档必须包含 Pingora 切换状态快照脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    reason: 'API Build 归档必须包含 Pingora 切换证据包脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-command-evidence.mjs',
+    reason: 'API Build 归档必须包含 Pingora 切换命令证据脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-verify.mjs',
+    reason: 'API Build 归档必须包含 Pingora 切换证据验真脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-audit.mjs',
+    reason: 'API Build 归档必须包含 Pingora 切换证据根目录审计脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-production-health-patrol-env.mjs',
+    reason: 'API Build 归档必须包含健康巡检 env 复核脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-release-readiness.mjs',
+    reason: 'API Build 归档必须包含 Pingora release readiness 聚合门禁脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-canary-live.mjs',
+    reason: 'API Build 归档必须包含 Pingora canary live smoke 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-canary-access-log-parity.mjs',
+    reason: 'API Build 归档必须包含 Pingora canary access log 对账脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/production-api-deploy.sh',
+    reason: 'API Build 归档必须包含 build 产物内的 deploy 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/maintenance-on.sh',
+    reason: 'API Build 归档必须包含 build 产物内的维护开启脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/maintenance-off.sh',
+    reason: 'API Build 归档必须包含 build 产物内的维护关闭脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason: 'API Build 归档必须包含 Pingora health patrol env 切换脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'API Build 归档必须包含 Pingora gateway env shadow 切换脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh',
+    reason: 'API Build 归档必须包含 Pingora realpath canary 启用脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh',
+    reason: 'API Build 归档必须包含 Pingora realpath canary 关闭脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'build/${env.EFFECTIVE_BUILD_VERSION}/deploy/env/**',
+    reason: 'API Build 归档必须包含 env 示例目录。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'build/${env.EFFECTIVE_BUILD_VERSION}/deploy/nginx/**',
+    reason: 'API Build 归档必须包含 Nginx/Pingora canary snippet。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    excludes: ',scripts/deploy/production-api-deploy.sh',
+    reason: 'API Build 不应再归档工作区根部 deploy 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'INCLUDE_PINGORA_GATEWAY',
+    reason: 'API Build 必须保留 Pingora 影子网关可选构建参数。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: 'command -v cmake',
+    reason: 'API Build 勾选 Pingora 时必须前置检查 cmake。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes: '构建 Pingora 影子网关缺少 C++ 编译器',
+    reason: 'API Build 勾选 Pingora 时必须前置检查 C++ 编译器。',
+  },
   {
     file: 'jenkins/Jenkinsfile.production-api-deploy',
     includes: 'scripts/ops/production-health-patrol.mjs',
     reason: 'API Deploy 复制上游产物时必须包含健康巡检脚本。',
   },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/ops/pingora-current-release-audit.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora current release 自审脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-status-snapshot.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 切换状态快照脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 切换证据包脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-command-evidence.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 切换命令证据脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-verify.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 切换证据验真脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-audit.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora 切换证据根目录审计脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/check-production-health-patrol-env.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含健康巡检 env 复核脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/check-pingora-release-readiness.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora release readiness 聚合门禁脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/check-pingora-canary-live.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora canary live smoke 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/check-pingora-canary-access-log-parity.mjs',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora canary access log 对账脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora realpath canary 启用脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh',
+    reason: 'API Deploy 复制上游产物时必须包含 Pingora realpath canary 关闭脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/deploy/production-api-deploy.sh',
+    reason: 'API Deploy 必须复制并执行 build 产物内的 deploy 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      '"build/${BUILD_VERSION}/scripts/deploy/production-api-deploy.sh"',
+    reason: 'API Deploy 执行入口必须是 build 产物内的 deploy 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'build/${params.BUILD_VERSION}/scripts/deploy/maintenance-on.sh',
+    reason: 'API Deploy 必须复制 build 产物内的维护开启脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason: 'API Deploy 必须复制 build 产物内的 Pingora health patrol env 切换脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'API Deploy 必须复制 build 产物内的 Pingora gateway env shadow 切换脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'build/${params.BUILD_VERSION}/scripts/deploy/maintenance-off.sh',
+    reason: 'API Deploy 必须复制 build 产物内的维护关闭脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'build/${params.BUILD_VERSION}/deploy/env/**',
+    reason: 'API Deploy 必须从上游 build 产物复制 env 示例目录。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'build/${params.BUILD_VERSION}/deploy/nginx/**',
+    reason: 'API Deploy 必须从上游 build 产物复制 Nginx/Pingora canary snippet。',
+  },
+  {
+    file: 'scripts/deploy/production-api-deploy.sh',
+    includes: 'NGINX_DEPLOY_DIR_SOURCE',
+    reason: 'API Deploy 必须把发布产物内 deploy/nginx 复制到 current release。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    excludes: ',scripts/deploy/production-api-deploy.sh',
+    reason: 'API Deploy 不应再复制工作区根部 deploy 脚本。',
+  },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes: 'pingora-gateway.sha256',
+    reason:
+      'API Deploy 复制上游产物时必须保留 Pingora 影子网关可选 checksum 产物。',
+  },
+];
+
+const nodeEnvFileCommandFiles = [
+  'package.json',
+  'deploy/systemd/genarrative-database-backup.service',
+  'scripts/deploy/production-stdb-publish.sh',
+  'scripts/deploy/pingora-direct-enable.sh',
+  'scripts/deploy/pingora-direct-rollback.sh',
 ];
 
 let failed = false;
 
 for (const check of checks) {
   const content = readFileSync(check.file, 'utf8');
-  if (!content.includes(check.includes)) {
+  if (check.includes && !content.includes(check.includes)) {
     failed = true;
     console.error(
       `[check:production-ops] ${check.file} 缺少 ${check.includes}。${check.reason}`,
     );
   }
+  if (check.excludes && content.includes(check.excludes)) {
+    failed = true;
+    console.error(
+      `[check:production-ops] ${check.file} 不应包含 ${check.excludes}。${check.reason}`,
+    );
+  }
+}
+
+for (const file of nodeEnvFileCommandFiles) {
+  const content = readFileSync(file, 'utf8');
+  const commandText = content.replace(/\\\r?\n\s*/g, ' ');
+  const unsafeCommands = commandText.match(
+    /\bnode\b(?!\s+--)(?=[^;&|\n]*\.mjs)(?=[^;&|\n]*--env-file)[^;&|\n]*/g,
+  );
+  if (!unsafeCommands) {
+    continue;
+  }
+
+  failed = true;
+  for (const command of unsafeCommands) {
+    console.error(
+      `[check:production-ops] ${file} 中的 Node 命令必须用 node -- 分隔业务 --env-file 参数: ${command.trim()}`,
+    );
+  }
 }
 
 if (failed) {
diff --git a/scripts/database-backup-to-oss.mjs b/scripts/database-backup-to-oss.mjs
index b01cf5571..4c5587b3d 100644
--- a/scripts/database-backup-to-oss.mjs
+++ b/scripts/database-backup-to-oss.mjs
@@ -20,8 +20,8 @@ const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
 function usage() {
   console.log(`用法:
   npm run database:backup:oss -- [--data-dir <path>] [--work-dir <path>] [--bucket <bucket>] [--object-prefix <prefix>] [--keep-local]
-  node scripts/database-backup-to-oss.mjs [--stop-service spacetimedb.service] [--restart-service-after genarrative-api.service] [--defer-upload]
-  node scripts/database-backup-to-oss.mjs --upload-archive <path>
+  node -- scripts/database-backup-to-oss.mjs [--stop-service spacetimedb.service] [--restart-service-after genarrative-api.service] [--defer-upload]
+  node -- scripts/database-backup-to-oss.mjs --upload-archive <path>
 
 说明:
   将 SpacetimeDB 数据目录打包成 .tar.gz，并上传到阿里云 OSS 指定 bucket。
diff --git a/scripts/deploy/pingora-direct-enable.sh b/scripts/deploy/pingora-direct-enable.sh
new file mode 100644
index 000000000..55bfa52ff
--- /dev/null
+++ b/scripts/deploy/pingora-direct-enable.sh
@@ -0,0 +1,922 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+REPO_ROOT="$(cd -- "${SCRIPT_DIR}/../.." >/dev/null 2>&1 && pwd)"
+SERVICE_NAME="${GENARRATIVE_PINGORA_GATEWAY_SERVICE:-genarrative-pingora-gateway.service}"
+DEFAULT_SERVICE_UNIT_PATH="${REPO_ROOT}/deploy/systemd/genarrative-pingora-gateway.service"
+SERVICE_UNIT_PATH="${GENARRATIVE_PINGORA_DIRECT_SERVICE_UNIT_PATH:-${DEFAULT_SERVICE_UNIT_PATH}}"
+DEFAULT_TEMPLATE_PATH="${REPO_ROOT}/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf"
+TEMPLATE_PATH="${GENARRATIVE_PINGORA_DIRECT_TEMPLATE_PATH:-${DEFAULT_TEMPLATE_PATH}}"
+DROPIN_PATH="${GENARRATIVE_PINGORA_DIRECT_DROPIN_PATH:-/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf}"
+PREFLIGHT_SCRIPT="${GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SCRIPT:-${REPO_ROOT}/scripts/check-pingora-direct-preflight.mjs}"
+PREFLIGHT_ENV_FILE="${GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE:-}"
+CURRENT_RELEASE_AUDIT_SCRIPT="${GENARRATIVE_PINGORA_DIRECT_CURRENT_RELEASE_AUDIT_SCRIPT:-${REPO_ROOT}/scripts/ops/pingora-current-release-audit.mjs}"
+CURRENT_RELEASE_ROOT="${GENARRATIVE_PINGORA_DIRECT_CURRENT_RELEASE_ROOT:-${REPO_ROOT}}"
+CURRENT_RELEASE_AUDIT_TIMEOUT_MS="${GENARRATIVE_PINGORA_DIRECT_CURRENT_RELEASE_AUDIT_TIMEOUT_MS:-}"
+PREFLIGHT_SYSTEMD="false"
+PREFLIGHT_CHECK_CERT_READABLE="false"
+PREFLIGHT_CHECK_SERVICE_ENV_FILE="false"
+PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE="false"
+PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE="false"
+PREFLIGHT_CHECK_PORTS_FREE="false"
+DIRECT_LIVE_SCRIPT="${GENARRATIVE_PINGORA_DIRECT_LIVE_SCRIPT:-${REPO_ROOT}/scripts/check-pingora-direct-live.mjs}"
+DIRECT_HTTPS_BASE_URL="${GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL:-}"
+DIRECT_HTTP_BASE_URL="${GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL:-}"
+DIRECT_HOST="${GENARRATIVE_PINGORA_DIRECT_HOST:-}"
+DIRECT_REDIRECT_HOST="${GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST:-}"
+DIRECT_REDIRECT_BASE_URL="${GENARRATIVE_PINGORA_DIRECT_REDIRECT_BASE_URL:-}"
+DIRECT_PROBE_TOKEN="${GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN:-}"
+DIRECT_PINGORA_ACCESS_LOG="${GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG:-}"
+DIRECT_ACCESS_LOG_SINCE_LINES="${GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES:-}"
+DIRECT_SPACETIME_DATABASE="${GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE:-}"
+DIRECT_TIMEOUT_MS="${GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS:-}"
+APPLY="false"
+STATUS_AFTER="true"
+VERIFY_SYSTEMD_AFTER="true"
+
+usage() {
+  cat <<'EOF'
+用法:
+  scripts/deploy/pingora-direct-enable.sh [--apply] [--preflight-env-file <path>] [--preflight-systemd] [--preflight-check-cert-readable] [--preflight-check-service-env-file] [--preflight-check-service-user-cert-readable] [--preflight-check-service-binary-executable] [--preflight-check-ports-free]
+                                          [--direct-https-base-url <url>] [--direct-http-base-url <url>] [--direct-host <host>] [--direct-redirect-host <host>] [--direct-redirect-base-url <url>]
+                                          [--direct-spacetime-database <name>] [--direct-probe-token <token>] [--direct-pingora-access-log <path>] [--direct-access-log-since-lines <count>] [--direct-timeout-ms <ms>] [--direct-live-script <path>] [--no-postcheck]
+                                          [--current-release-audit-script <path>] [--current-release-root <path>] [--current-release-audit-timeout-ms <ms>]
+                                          [--service <name>] [--service-unit-path <path>] [--template-path <path>] [--dropin-path <path>]
+
+说明:
+  启用 Pingora 直连低端口入口：把已准备好的 direct-entry systemd drop-in 模板安装到
+  genarrative-pingora-gateway.service.d/direct-entry.conf，执行 daemon-reload，
+  重启 genarrative-pingora-gateway.service，让服务具备绑定 80/443 的最小 capability。
+
+默认是 dry-run，只打印将执行的命令；必须显式传 --apply 才会修改系统状态。
+该脚本不写入 TLS env、不复制证书、不停止 Nginx；--apply 会先执行 current release 自包含自审，
+确认发布包已携带 Pingora 网关且 systemd ExecStart 指向随包二进制；--apply 时必须提供 --preflight-env-file、
+--preflight-check-cert-readable、--preflight-check-service-env-file、--preflight-check-service-user-cert-readable、--preflight-check-service-binary-executable、--preflight-check-ports-free 和 direct live smoke 参数，
+先通过 direct preflight，安装并重启 Pingora，再通过 direct live smoke 后才视为启用成功。
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --apply)
+      APPLY="true"
+      shift
+      ;;
+    --no-status)
+      STATUS_AFTER="false"
+      shift
+      ;;
+    --no-postcheck)
+      VERIFY_SYSTEMD_AFTER="false"
+      shift
+      ;;
+    --service)
+      SERVICE_NAME="${2:-}"
+      if [[ -z "${SERVICE_NAME}" ]]; then
+        echo "[pingora-direct-enable] --service 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --service-unit-path)
+      SERVICE_UNIT_PATH="${2:-}"
+      if [[ -z "${SERVICE_UNIT_PATH}" ]]; then
+        echo "[pingora-direct-enable] --service-unit-path 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --template-path)
+      TEMPLATE_PATH="${2:-}"
+      if [[ -z "${TEMPLATE_PATH}" ]]; then
+        echo "[pingora-direct-enable] --template-path 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --dropin-path)
+      DROPIN_PATH="${2:-}"
+      if [[ -z "${DROPIN_PATH}" ]]; then
+        echo "[pingora-direct-enable] --dropin-path 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --preflight-script)
+      PREFLIGHT_SCRIPT="${2:-}"
+      if [[ -z "${PREFLIGHT_SCRIPT}" ]]; then
+        echo "[pingora-direct-enable] --preflight-script 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --preflight-env-file)
+      PREFLIGHT_ENV_FILE="${2:-}"
+      if [[ -z "${PREFLIGHT_ENV_FILE}" ]]; then
+        echo "[pingora-direct-enable] --preflight-env-file 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --current-release-audit-script)
+      CURRENT_RELEASE_AUDIT_SCRIPT="${2:-}"
+      if [[ -z "${CURRENT_RELEASE_AUDIT_SCRIPT}" ]]; then
+        echo "[pingora-direct-enable] --current-release-audit-script 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --current-release-root)
+      CURRENT_RELEASE_ROOT="${2:-}"
+      if [[ -z "${CURRENT_RELEASE_ROOT}" ]]; then
+        echo "[pingora-direct-enable] --current-release-root 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --current-release-audit-timeout-ms)
+      CURRENT_RELEASE_AUDIT_TIMEOUT_MS="${2:-}"
+      if [[ -z "${CURRENT_RELEASE_AUDIT_TIMEOUT_MS}" ]]; then
+        echo "[pingora-direct-enable] --current-release-audit-timeout-ms 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --preflight-systemd)
+      PREFLIGHT_SYSTEMD="true"
+      shift
+      ;;
+    --preflight-check-cert-readable)
+      PREFLIGHT_CHECK_CERT_READABLE="true"
+      shift
+      ;;
+    --preflight-check-service-env-file)
+      PREFLIGHT_CHECK_SERVICE_ENV_FILE="true"
+      shift
+      ;;
+    --preflight-check-service-user-cert-readable)
+      PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE="true"
+      shift
+      ;;
+    --preflight-check-service-binary-executable)
+      PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE="true"
+      shift
+      ;;
+    --preflight-check-ports-free)
+      PREFLIGHT_CHECK_PORTS_FREE="true"
+      shift
+      ;;
+    --direct-live-script)
+      DIRECT_LIVE_SCRIPT="${2:-}"
+      if [[ -z "${DIRECT_LIVE_SCRIPT}" ]]; then
+        echo "[pingora-direct-enable] --direct-live-script 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-https-base-url)
+      DIRECT_HTTPS_BASE_URL="${2:-}"
+      if [[ -z "${DIRECT_HTTPS_BASE_URL}" ]]; then
+        echo "[pingora-direct-enable] --direct-https-base-url 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-http-base-url)
+      DIRECT_HTTP_BASE_URL="${2:-}"
+      if [[ -z "${DIRECT_HTTP_BASE_URL}" ]]; then
+        echo "[pingora-direct-enable] --direct-http-base-url 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-host)
+      DIRECT_HOST="${2:-}"
+      if [[ -z "${DIRECT_HOST}" ]]; then
+        echo "[pingora-direct-enable] --direct-host 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-redirect-host)
+      DIRECT_REDIRECT_HOST="${2:-}"
+      if [[ -z "${DIRECT_REDIRECT_HOST}" ]]; then
+        echo "[pingora-direct-enable] --direct-redirect-host 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-redirect-base-url)
+      DIRECT_REDIRECT_BASE_URL="${2:-}"
+      if [[ -z "${DIRECT_REDIRECT_BASE_URL}" ]]; then
+        echo "[pingora-direct-enable] --direct-redirect-base-url 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-probe-token)
+      DIRECT_PROBE_TOKEN="${2:-}"
+      if [[ -z "${DIRECT_PROBE_TOKEN}" ]]; then
+        echo "[pingora-direct-enable] --direct-probe-token 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-pingora-access-log)
+      DIRECT_PINGORA_ACCESS_LOG="${2:-}"
+      if [[ -z "${DIRECT_PINGORA_ACCESS_LOG}" ]]; then
+        echo "[pingora-direct-enable] --direct-pingora-access-log 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-access-log-since-lines)
+      DIRECT_ACCESS_LOG_SINCE_LINES="${2:-}"
+      if [[ -z "${DIRECT_ACCESS_LOG_SINCE_LINES}" ]]; then
+        echo "[pingora-direct-enable] --direct-access-log-since-lines 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-spacetime-database)
+      DIRECT_SPACETIME_DATABASE="${2:-}"
+      if [[ -z "${DIRECT_SPACETIME_DATABASE}" ]]; then
+        echo "[pingora-direct-enable] --direct-spacetime-database 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --direct-timeout-ms)
+      DIRECT_TIMEOUT_MS="${2:-}"
+      if [[ -z "${DIRECT_TIMEOUT_MS}" ]]; then
+        echo "[pingora-direct-enable] --direct-timeout-ms 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    *)
+      echo "[pingora-direct-enable] 未知参数: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+reject_control_characters() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" == *$'\n'* || "${value}" == *$'\r'* ]]; then
+    echo "[pingora-direct-enable] ${label} 不能包含换行或 NUL 字符。" >&2
+    exit 1
+  fi
+}
+
+is_filesystem_root_path() {
+  local value="$1"
+  local without_slashes="${value//\//}"
+  [[ -n "${value}" && -z "${without_slashes}" ]]
+}
+
+reject_filesystem_root_path() {
+  local label="$1"
+  local value="$2"
+  if is_filesystem_root_path "${value}"; then
+    echo "[pingora-direct-enable] ${label} 不能是文件系统根目录。" >&2
+    exit 1
+  fi
+}
+
+reject_control_characters "--service" "${SERVICE_NAME}"
+reject_control_characters "--service-unit-path" "${SERVICE_UNIT_PATH}"
+reject_control_characters "--template-path" "${TEMPLATE_PATH}"
+reject_control_characters "--dropin-path" "${DROPIN_PATH}"
+reject_control_characters "--preflight-script" "${PREFLIGHT_SCRIPT}"
+reject_control_characters "--preflight-env-file" "${PREFLIGHT_ENV_FILE}"
+reject_control_characters "--current-release-audit-script" "${CURRENT_RELEASE_AUDIT_SCRIPT}"
+reject_control_characters "--current-release-root" "${CURRENT_RELEASE_ROOT}"
+reject_control_characters "--current-release-audit-timeout-ms" "${CURRENT_RELEASE_AUDIT_TIMEOUT_MS}"
+reject_control_characters "--direct-live-script" "${DIRECT_LIVE_SCRIPT}"
+reject_control_characters "--direct-https-base-url" "${DIRECT_HTTPS_BASE_URL}"
+reject_control_characters "--direct-http-base-url" "${DIRECT_HTTP_BASE_URL}"
+reject_control_characters "--direct-host" "${DIRECT_HOST}"
+reject_control_characters "--direct-redirect-host" "${DIRECT_REDIRECT_HOST}"
+reject_control_characters "--direct-redirect-base-url" "${DIRECT_REDIRECT_BASE_URL}"
+reject_control_characters "--direct-probe-token" "${DIRECT_PROBE_TOKEN}"
+reject_control_characters "--direct-pingora-access-log" "${DIRECT_PINGORA_ACCESS_LOG}"
+reject_control_characters "--direct-access-log-since-lines" "${DIRECT_ACCESS_LOG_SINCE_LINES}"
+reject_control_characters "--direct-spacetime-database" "${DIRECT_SPACETIME_DATABASE}"
+reject_control_characters "--direct-timeout-ms" "${DIRECT_TIMEOUT_MS}"
+
+reject_filesystem_root_path "--service-unit-path" "${SERVICE_UNIT_PATH}"
+reject_filesystem_root_path "--template-path" "${TEMPLATE_PATH}"
+reject_filesystem_root_path "--dropin-path" "${DROPIN_PATH}"
+reject_filesystem_root_path "--preflight-env-file" "${PREFLIGHT_ENV_FILE}"
+reject_filesystem_root_path "--preflight-script" "${PREFLIGHT_SCRIPT}"
+reject_filesystem_root_path "--current-release-audit-script" "${CURRENT_RELEASE_AUDIT_SCRIPT}"
+reject_filesystem_root_path "--current-release-root" "${CURRENT_RELEASE_ROOT}"
+reject_filesystem_root_path "--direct-live-script" "${DIRECT_LIVE_SCRIPT}"
+reject_filesystem_root_path "--direct-pingora-access-log" "${DIRECT_PINGORA_ACCESS_LOG}"
+
+if [[ "${TEMPLATE_PATH}" != /* ]]; then
+  echo "[pingora-direct-enable] --template-path 必须是绝对路径: ${TEMPLATE_PATH}" >&2
+  exit 1
+fi
+
+if [[ "${SERVICE_UNIT_PATH}" != /* ]]; then
+  echo "[pingora-direct-enable] --service-unit-path 必须是绝对路径: ${SERVICE_UNIT_PATH}" >&2
+  exit 1
+fi
+
+if [[ "${DROPIN_PATH}" != /* ]]; then
+  echo "[pingora-direct-enable] --dropin-path 必须是绝对路径: ${DROPIN_PATH}" >&2
+  exit 1
+fi
+
+if [[ -n "${PREFLIGHT_ENV_FILE}" && "${PREFLIGHT_ENV_FILE}" != /* ]]; then
+  echo "[pingora-direct-enable] --preflight-env-file 必须是绝对路径: ${PREFLIGHT_ENV_FILE}" >&2
+  exit 1
+fi
+
+if [[ "${PREFLIGHT_SCRIPT}" != /* ]]; then
+  echo "[pingora-direct-enable] --preflight-script 必须是绝对路径: ${PREFLIGHT_SCRIPT}" >&2
+  exit 1
+fi
+
+if [[ "${CURRENT_RELEASE_AUDIT_SCRIPT}" != /* ]]; then
+  echo "[pingora-direct-enable] --current-release-audit-script 必须是绝对路径: ${CURRENT_RELEASE_AUDIT_SCRIPT}" >&2
+  exit 1
+fi
+
+if [[ "${CURRENT_RELEASE_ROOT}" != /* ]]; then
+  echo "[pingora-direct-enable] --current-release-root 必须是绝对路径: ${CURRENT_RELEASE_ROOT}" >&2
+  exit 1
+fi
+
+if [[ "${DIRECT_LIVE_SCRIPT}" != /* ]]; then
+  echo "[pingora-direct-enable] --direct-live-script 必须是绝对路径: ${DIRECT_LIVE_SCRIPT}" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${PREFLIGHT_ENV_FILE}" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --preflight-env-file，避免跳过直连 env / 证书预检。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && "${PREFLIGHT_CHECK_CERT_READABLE}" != "true" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --preflight-check-cert-readable，避免跳过 TLS 证书和私钥可读预检。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && "${PREFLIGHT_CHECK_SERVICE_ENV_FILE}" != "true" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --preflight-check-service-env-file，避免检查的 env 文件和 systemd service 实际读取的 EnvironmentFile 不一致。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && "${PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE}" != "true" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --preflight-check-service-user-cert-readable，避免跳过 systemd 服务用户读取 TLS 证书和私钥预检。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && "${PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE}" != "true" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --preflight-check-service-binary-executable，避免 current release 缺少可执行 pingora-gateway 时才在重启阶段失败。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && "${PREFLIGHT_CHECK_PORTS_FREE}" != "true" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --preflight-check-ports-free，避免 Nginx 或其它进程仍占用 80/443。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${DIRECT_HTTPS_BASE_URL}" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --direct-https-base-url，启用后验证 Pingora HTTPS 直连入口。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${DIRECT_HTTP_BASE_URL}" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --direct-http-base-url，启用后验证 HTTP redirect / ACME 入口。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${DIRECT_HOST}" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --direct-host，启用后用正式域名 Host/SNI 验证直连入口。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${DIRECT_REDIRECT_HOST}" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --direct-redirect-host，启用后验证 HTTP redirect Location host。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${DIRECT_PINGORA_ACCESS_LOG}" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --direct-pingora-access-log，启用后验证直连请求已写入 Pingora access log。" >&2
+  exit 1
+fi
+
+if [[ -n "${DIRECT_PINGORA_ACCESS_LOG}" && "${DIRECT_PINGORA_ACCESS_LOG}" != /* ]]; then
+  echo "[pingora-direct-enable] --direct-pingora-access-log 必须是绝对路径: ${DIRECT_PINGORA_ACCESS_LOG}" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${DIRECT_SPACETIME_DATABASE}" ]]; then
+  echo "[pingora-direct-enable] --apply 必须同时提供 --direct-spacetime-database，启用后验证目标库 WSS subscribe。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && ! -f "${TEMPLATE_PATH}" ]]; then
+  echo "[pingora-direct-enable] direct-entry 模板不存在: ${TEMPLATE_PATH}" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && ! -f "${SERVICE_UNIT_PATH}" ]]; then
+  echo "[pingora-direct-enable] 主 service 模板不存在: ${SERVICE_UNIT_PATH}" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && ! -f "${CURRENT_RELEASE_AUDIT_SCRIPT}" ]]; then
+  echo "[pingora-direct-enable] current release 自审脚本不存在: ${CURRENT_RELEASE_AUDIT_SCRIPT}" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && ! -f "${PREFLIGHT_SCRIPT}" ]]; then
+  echo "[pingora-direct-enable] direct preflight 脚本不存在: ${PREFLIGHT_SCRIPT}" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && ! -f "${DIRECT_LIVE_SCRIPT}" ]]; then
+  echo "[pingora-direct-enable] direct live smoke 脚本不存在: ${DIRECT_LIVE_SCRIPT}" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" ]]; then
+  DROPIN_DIR="$(dirname "${DROPIN_PATH}")"
+  if [[ -L "${DROPIN_DIR}" ]]; then
+    echo "[pingora-direct-enable] drop-in 目录不能是符号链接: ${DROPIN_DIR}" >&2
+    exit 1
+  fi
+  if [[ -e "${DROPIN_DIR}" && ! -d "${DROPIN_DIR}" ]]; then
+    echo "[pingora-direct-enable] drop-in 父路径必须是目录: ${DROPIN_DIR}" >&2
+    exit 1
+  fi
+  if [[ -L "${DROPIN_PATH}" ]]; then
+    echo "[pingora-direct-enable] drop-in 目标不能是符号链接: ${DROPIN_PATH}" >&2
+    exit 1
+  fi
+  if [[ -e "${DROPIN_PATH}" && ! -f "${DROPIN_PATH}" ]]; then
+    echo "[pingora-direct-enable] drop-in 目标已存在但不是普通文件: ${DROPIN_PATH}" >&2
+    exit 1
+  fi
+fi
+
+run_cmd() {
+  echo "+ $*"
+  if [[ "${APPLY}" == "true" ]]; then
+    "$@"
+  fi
+}
+
+print_redacted_command() {
+  local previous="" output=()
+  for arg in "$@"; do
+    if [[ "${previous}" == "--probe-token" || "${previous}" == "--direct-probe-token" ]]; then
+      output+=("<redacted>")
+    else
+      output+=("${arg}")
+    fi
+    previous="${arg}"
+  done
+  echo "+ ${output[*]}"
+}
+
+run_systemctl() {
+  if [[ "${APPLY}" != "true" ]]; then
+    run_cmd systemctl "$@"
+    return
+  fi
+  if command -v systemctl >/dev/null 2>&1; then
+    run_cmd systemctl "$@"
+  else
+    echo "[pingora-direct-enable] 未找到 systemctl，无法执行: systemctl $*" >&2
+    exit 1
+  fi
+}
+
+run_preflight() {
+  if [[ -z "${PREFLIGHT_ENV_FILE}" ]]; then
+    echo "[pingora-direct-enable] 未提供 --preflight-env-file，仅执行脚本 dry-run；--apply 会强制要求预检。"
+    return
+  fi
+
+  preflight_args=(
+    "${PREFLIGHT_SCRIPT}"
+    --env-file "${PREFLIGHT_ENV_FILE}"
+    --require-live-env
+  )
+  if [[ "${PREFLIGHT_SYSTEMD}" == "true" ]]; then
+    preflight_args+=(--systemd-cat)
+  fi
+  if [[ "${PREFLIGHT_CHECK_CERT_READABLE}" == "true" ]]; then
+    preflight_args+=(--check-cert-readable)
+  fi
+  if [[ "${PREFLIGHT_CHECK_SERVICE_ENV_FILE}" == "true" ]]; then
+    preflight_args+=(--check-service-env-file)
+  fi
+  if [[ "${PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE}" == "true" ]]; then
+    preflight_args+=(--check-service-user-cert-readable)
+  fi
+  if [[ "${PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE}" == "true" ]]; then
+    preflight_args+=(--check-service-binary-executable)
+  fi
+  if [[ "${PREFLIGHT_CHECK_PORTS_FREE}" == "true" ]]; then
+    preflight_args+=(--check-ports-free)
+  fi
+
+  echo "+ node -- ${preflight_args[*]}"
+  node -- "${preflight_args[@]}"
+}
+
+run_current_release_audit() {
+  audit_args=(
+    "${CURRENT_RELEASE_AUDIT_SCRIPT}"
+    --release-root "${CURRENT_RELEASE_ROOT}"
+    --require-pingora-gateway
+    --systemd-show
+    --systemd-service "${SERVICE_NAME}"
+  )
+  if [[ -n "${CURRENT_RELEASE_AUDIT_TIMEOUT_MS}" ]]; then
+    audit_args+=(--timeout-ms "${CURRENT_RELEASE_AUDIT_TIMEOUT_MS}")
+  fi
+
+  echo "+ node -- ${audit_args[*]}"
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "[pingora-direct-enable] dry-run：--apply 前会先执行 current release 自包含自审。"
+    return
+  fi
+
+  node -- "${audit_args[@]}"
+}
+
+systemd_env_file_matches() {
+  local expected="$1"
+  local line value word normalized
+  while IFS= read -r line; do
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [[ "${line}" == EnvironmentFile=* ]] || continue
+    value="${line#EnvironmentFile=}"
+    [[ -n "${value}" ]] || continue
+    for word in ${value}; do
+      normalized="${word%\"}"
+      normalized="${normalized#\"}"
+      normalized="${normalized%\'}"
+      normalized="${normalized#\'}"
+      normalized="${normalized#-}"
+      if [[ "${normalized}" == "${expected}" ]]; then
+        return 0
+      fi
+    done
+  done <<<"${unit_content}"
+  return 1
+}
+
+read_expected_exec_start() {
+  local line value
+  if [[ ! -f "${SERVICE_UNIT_PATH}" ]]; then
+    return 1
+  fi
+  while IFS= read -r line; do
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [[ "${line}" == ExecStart=* ]] || continue
+    value="${line#ExecStart=}"
+    [[ -n "${value}" ]] || continue
+    printf '%s\n' "${value}"
+    return 0
+  done <"${SERVICE_UNIT_PATH}"
+  return 1
+}
+
+first_exec_word() {
+  local value="$1"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  if [[ "${value}" == \"* ]]; then
+    value="${value#\"}"
+    printf '%s\n' "${value%%\"*}"
+    return
+  fi
+  printf '%s\n' "${value%%[[:space:]]*}"
+}
+
+systemd_show_exec_start_matches() {
+  local expected_exec="$1"
+  local expected_binary actual_show actual_binary
+  expected_binary="$(first_exec_word "${expected_exec}")"
+  [[ -n "${expected_binary}" ]] || return 1
+  actual_show="$(systemctl show "${SERVICE_NAME}" --property=ExecStart --value --no-pager)"
+  actual_binary="${actual_show}"
+  if [[ "${actual_show}" == *"path="* ]]; then
+    actual_binary="${actual_show#*path=}"
+    actual_binary="${actual_binary%% ;*}"
+  elif [[ "${actual_show}" == ExecStart=* ]]; then
+    actual_binary="${actual_show#ExecStart=}"
+    actual_binary="$(first_exec_word "${actual_binary}")"
+  else
+    actual_binary="$(first_exec_word "${actual_binary}")"
+  fi
+  [[ "${actual_binary}" == "${expected_binary}" ]]
+}
+
+verify_systemd_exec_start() {
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-enable] 已跳过 Pingora ExecStart 指向核验。"
+    return
+  fi
+
+  expected_exec_start="$(read_expected_exec_start || true)"
+  if [[ -z "${expected_exec_start}" ]]; then
+    echo "[pingora-direct-enable] 无法从主 service 模板读取 ExecStart: ${SERVICE_UNIT_PATH}" >&2
+    exit 1
+  fi
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager"
+    echo "[pingora-direct-enable] dry-run：--apply 后会核验 systemd ExecStart 指向主 service 模板中的 ${expected_exec_start}。"
+    return
+  fi
+
+  if ! command -v systemctl >/dev/null 2>&1; then
+    echo "[pingora-direct-enable] 未找到 systemctl，无法核验 Pingora ExecStart。" >&2
+    exit 1
+  fi
+
+  echo "+ systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager"
+  if ! systemd_show_exec_start_matches "${expected_exec_start}"; then
+    echo "[pingora-direct-enable] systemctl show ExecStart 未指向主 service 模板中的 ${expected_exec_start}，请先修正 ${SERVICE_NAME} 指向 current release 网关二进制。" >&2
+    exit 1
+  fi
+}
+
+verify_systemd_dropin() {
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-enable] 已跳过 systemd drop-in 生效核验。"
+    return
+  fi
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ systemctl cat ${SERVICE_NAME}"
+    echo "[pingora-direct-enable] dry-run：--apply 后会校验 systemd 最终配置包含 CAP_NET_BIND_SERVICE。"
+    return
+  fi
+
+  if ! command -v systemctl >/dev/null 2>&1; then
+    echo "[pingora-direct-enable] 未找到 systemctl，无法核验 drop-in 是否生效。" >&2
+    exit 1
+  fi
+
+  echo "+ systemctl cat ${SERVICE_NAME}"
+  unit_content="$(systemctl cat "${SERVICE_NAME}")"
+  if [[ "${unit_content}" != *"AmbientCapabilities=CAP_NET_BIND_SERVICE"* ]]; then
+    echo "[pingora-direct-enable] systemctl cat 未显示 AmbientCapabilities=CAP_NET_BIND_SERVICE，direct-entry drop-in 未生效。" >&2
+    exit 1
+  fi
+  if [[ "${unit_content}" != *"CapabilityBoundingSet=CAP_NET_BIND_SERVICE"* ]]; then
+    echo "[pingora-direct-enable] systemctl cat 未显示 CapabilityBoundingSet=CAP_NET_BIND_SERVICE，direct-entry drop-in 未生效。" >&2
+    exit 1
+  fi
+  if [[ "${PREFLIGHT_CHECK_SERVICE_ENV_FILE}" == "true" && -n "${PREFLIGHT_ENV_FILE}" ]]; then
+    if ! systemd_env_file_matches "${PREFLIGHT_ENV_FILE}"; then
+      echo "[pingora-direct-enable] systemctl cat 未显示 EnvironmentFile=${PREFLIGHT_ENV_FILE}，service 实际读取的 env 与 preflight env 不一致。" >&2
+      exit 1
+    fi
+  fi
+}
+
+verify_service_active_after_restart() {
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-enable] 已跳过 Pingora 重启后状态核验。"
+    return
+  fi
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ systemctl is-active ${SERVICE_NAME}"
+    echo "[pingora-direct-enable] dry-run：--apply 后会校验 Pingora service 为 active。"
+    return
+  fi
+
+  if ! command -v systemctl >/dev/null 2>&1; then
+    echo "[pingora-direct-enable] 未找到 systemctl，无法核验 Pingora 重启后状态。" >&2
+    exit 1
+  fi
+
+  echo "+ systemctl is-active ${SERVICE_NAME}"
+  service_state="$(systemctl is-active "${SERVICE_NAME}")"
+  if [[ "${service_state}" != "active" ]]; then
+    echo "[pingora-direct-enable] Pingora 重启后状态不是 active: ${service_state}" >&2
+    exit 1
+  fi
+}
+
+run_direct_live_smoke_after_enable() {
+  if [[ -z "${DIRECT_HTTPS_BASE_URL}" ]]; then
+    echo "+ node ${DIRECT_LIVE_SCRIPT} --https-base-url <direct-https-base-url> --http-base-url <direct-http-base-url> --host <direct-host> --redirect-host <direct-redirect-host> --spacetime-database <database> --require-wss-upgrade"
+    echo "[pingora-direct-enable] dry-run：--apply 后会执行 direct live smoke；--apply 会强制要求 direct live 参数。"
+    return
+  fi
+
+  direct_live_args=(
+    "${DIRECT_LIVE_SCRIPT}"
+    --https-base-url "${DIRECT_HTTPS_BASE_URL}"
+  )
+  if [[ -n "${DIRECT_HTTP_BASE_URL}" ]]; then
+    direct_live_args+=(--http-base-url "${DIRECT_HTTP_BASE_URL}")
+  fi
+  if [[ -n "${DIRECT_HOST}" ]]; then
+    direct_live_args+=(--host "${DIRECT_HOST}")
+  fi
+  if [[ -n "${DIRECT_REDIRECT_HOST}" ]]; then
+    direct_live_args+=(--redirect-host "${DIRECT_REDIRECT_HOST}")
+  fi
+  if [[ -n "${DIRECT_REDIRECT_BASE_URL}" ]]; then
+    direct_live_args+=(--redirect-base-url "${DIRECT_REDIRECT_BASE_URL}")
+  fi
+  if [[ -n "${DIRECT_PROBE_TOKEN}" ]]; then
+    direct_live_args+=(--probe-token "${DIRECT_PROBE_TOKEN}")
+  fi
+  if [[ -n "${DIRECT_PINGORA_ACCESS_LOG}" ]]; then
+    direct_live_args+=(--pingora-access-log "${DIRECT_PINGORA_ACCESS_LOG}")
+  fi
+  if [[ -n "${DIRECT_ACCESS_LOG_SINCE_LINES}" ]]; then
+    direct_live_args+=(--access-log-since-lines "${DIRECT_ACCESS_LOG_SINCE_LINES}")
+  fi
+  if [[ -n "${DIRECT_SPACETIME_DATABASE}" ]]; then
+    direct_live_args+=(--spacetime-database "${DIRECT_SPACETIME_DATABASE}")
+  fi
+  direct_live_args+=(--require-wss-upgrade)
+  if [[ -n "${DIRECT_TIMEOUT_MS}" ]]; then
+    direct_live_args+=(--timeout-ms "${DIRECT_TIMEOUT_MS}")
+  fi
+  direct_live_args+=(--json)
+
+  print_redacted_command node "${direct_live_args[@]}"
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "[pingora-direct-enable] dry-run：--apply 后会验证 Pingora HTTPS / HTTP redirect / WSS 直连入口，并解析 direct-access-log 结构化证据。"
+    return
+  fi
+
+  set +e
+  direct_live_output="$(node "${direct_live_args[@]}")"
+  direct_live_status=$?
+  set -e
+  printf '%s\n' "${direct_live_output}"
+  if [[ "${direct_live_status}" -ne 0 ]]; then
+    exit "${direct_live_status}"
+  fi
+  DIRECT_LIVE_OUTPUT="${direct_live_output}" node -- <<'NODE'
+const stdout = process.env.DIRECT_LIVE_OUTPUT || '';
+
+const jsonText = extractFirstJsonObject(stdout);
+if (!jsonText) {
+  console.error(
+    '[pingora-direct-enable] direct live stdout 中未找到 JSON 结果对象，无法确认 direct-access-log 结构化证据。',
+  );
+  process.exit(1);
+}
+
+let parsed;
+try {
+  parsed = JSON.parse(jsonText);
+} catch (error) {
+  console.error(
+    `[pingora-direct-enable] direct live JSON 解析失败: ${error.message}`,
+  );
+  process.exit(1);
+}
+
+const accessLogCheck = parsed?.results?.find(
+  (item) => item?.name === 'direct-access-log',
+);
+if (!accessLogCheck) {
+  console.error(
+    '[pingora-direct-enable] direct live JSON 缺少 direct-access-log 结构化结果。',
+  );
+  process.exit(1);
+}
+
+const checked = toNonNegativeInteger(accessLogCheck.checked);
+const matchedCount = toNonNegativeInteger(accessLogCheck.matchedCount);
+const missingCount = toNonNegativeInteger(accessLogCheck.missingCount);
+const mismatchCount = toNonNegativeInteger(accessLogCheck.mismatchCount);
+const missingDetailsCount = Array.isArray(accessLogCheck.missing)
+  ? accessLogCheck.missing.length
+  : null;
+const mismatchDetailsCount = Array.isArray(accessLogCheck.mismatches)
+  ? accessLogCheck.mismatches.length
+  : null;
+
+if (
+  checked === null ||
+  matchedCount === null ||
+  missingCount !== 0 ||
+  mismatchCount !== 0 ||
+  matchedCount !== checked ||
+  missingDetailsCount !== 0 ||
+  mismatchDetailsCount !== 0
+) {
+  console.error(
+    `[pingora-direct-enable] direct-access-log 结构化证据未通过: checked=${checked ?? '-'} matched=${matchedCount ?? '-'} missing=${missingCount ?? '-'} mismatches=${mismatchCount ?? '-'}`,
+  );
+  process.exit(1);
+}
+
+console.log(
+  `[pingora-direct-enable] direct-access-log evidence checked=${checked} matched=${matchedCount} missing=0 mismatches=0`,
+);
+
+function extractFirstJsonObject(text) {
+  const startIndex = text.indexOf('{');
+  if (startIndex < 0) {
+    return '';
+  }
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let index = startIndex; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === '{') {
+      depth += 1;
+      continue;
+    }
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        return text.slice(startIndex, index + 1);
+      }
+    }
+  }
+  return '';
+}
+
+function toNonNegativeInteger(value) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0) {
+    return null;
+  }
+  return number;
+}
+NODE
+}
+
+echo "[pingora-direct-enable] apply=${APPLY} service=${SERVICE_NAME} template=${TEMPLATE_PATH} dropin=${DROPIN_PATH}"
+
+if [[ "${APPLY}" != "true" ]]; then
+  echo "[pingora-direct-enable] 当前是 dry-run；确认 preflight 通过后追加 --apply。"
+  if [[ ! -f "${TEMPLATE_PATH}" ]]; then
+    echo "[pingora-direct-enable] dry-run 提示：当前模板不存在，--apply 会失败: ${TEMPLATE_PATH}" >&2
+  fi
+fi
+
+run_current_release_audit
+run_preflight
+run_cmd install -d -m 0755 "$(dirname "${DROPIN_PATH}")"
+run_cmd install -m 0644 "${TEMPLATE_PATH}" "${DROPIN_PATH}"
+run_systemctl daemon-reload
+run_systemctl restart "${SERVICE_NAME}"
+verify_systemd_dropin
+verify_systemd_exec_start
+verify_service_active_after_restart
+run_direct_live_smoke_after_enable
+
+if [[ "${STATUS_AFTER}" == "true" ]]; then
+  run_systemctl status "${SERVICE_NAME}" --no-pager
+fi
+
+cat <<EOF
+[pingora-direct-enable] 完成。后续请确认：
+- systemctl cat ${SERVICE_NAME} 包含 AmbientCapabilities=CAP_NET_BIND_SERVICE
+- systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager 指向 current release 的 pingora-gateway
+- systemctl is-active ${SERVICE_NAME} 为 active
+- node ${CURRENT_RELEASE_AUDIT_SCRIPT} --release-root ${CURRENT_RELEASE_ROOT} --require-pingora-gateway --systemd-show --systemd-service ${SERVICE_NAME} 已通过
+- npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free 已通过
+- node ${DIRECT_LIVE_SCRIPT} --https-base-url ${DIRECT_HTTPS_BASE_URL:-<direct-https-base-url>} --http-base-url ${DIRECT_HTTP_BASE_URL:-<direct-http-base-url>} --host ${DIRECT_HOST:-<direct-host>} --redirect-host ${DIRECT_REDIRECT_HOST:-<direct-redirect-host>} ${DIRECT_REDIRECT_BASE_URL:+--redirect-base-url ${DIRECT_REDIRECT_BASE_URL} }--pingora-access-log ${DIRECT_PINGORA_ACCESS_LOG:-<pingora-access-log>} --spacetime-database ${DIRECT_SPACETIME_DATABASE:-<database>} --require-wss-upgrade --json 已通过，且 direct-access-log 结构化证据 matched=checked、missing=0、mismatches=0
+EOF
diff --git a/scripts/deploy/pingora-direct-rollback.sh b/scripts/deploy/pingora-direct-rollback.sh
new file mode 100644
index 000000000..f5b56ba8a
--- /dev/null
+++ b/scripts/deploy/pingora-direct-rollback.sh
@@ -0,0 +1,768 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SERVICE_NAME="${GENARRATIVE_PINGORA_GATEWAY_SERVICE:-genarrative-pingora-gateway.service}"
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd -- "${SCRIPT_DIR}/../.." && pwd -P)"
+DEFAULT_SERVICE_UNIT_PATH="${REPO_ROOT}/deploy/systemd/genarrative-pingora-gateway.service"
+SERVICE_UNIT_PATH="${GENARRATIVE_PINGORA_ROLLBACK_SERVICE_UNIT_PATH:-${DEFAULT_SERVICE_UNIT_PATH}}"
+DROPIN_PATH="${GENARRATIVE_PINGORA_DIRECT_DROPIN_PATH:-/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf}"
+NGINX_SERVICE="${GENARRATIVE_NGINX_SERVICE:-nginx.service}"
+NGINX_BINARY="${GENARRATIVE_NGINX_BINARY:-nginx}"
+NGINX_SMOKE_URL="${GENARRATIVE_NGINX_ROLLBACK_SMOKE_URL:-}"
+NGINX_SMOKE_HOST="${GENARRATIVE_NGINX_ROLLBACK_SMOKE_HOST:-}"
+NGINX_SMOKE_EXPECT_BODY="${GENARRATIVE_NGINX_ROLLBACK_SMOKE_EXPECT_BODY:-}"
+CURL_BINARY="${GENARRATIVE_CURL_BINARY:-curl}"
+HEALTH_PATROL_ENV_FILE="${GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_ENV_FILE:-}"
+HEALTH_PATROL_ENV_CHECK_SCRIPT="${GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_ENV_CHECK_SCRIPT:-}"
+HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL="${GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL:-}"
+HEALTH_PATROL_EXPECTED_PUBLIC_HOST="${GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_EXPECTED_PUBLIC_HOST:-}"
+HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST="${GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST:-auto}"
+PINGORA_SHADOW_PROBE_URL="${GENARRATIVE_PINGORA_ROLLBACK_SHADOW_PROBE_URL:-}"
+PINGORA_SHADOW_PROBE_TOKEN="${GENARRATIVE_PINGORA_ROLLBACK_SHADOW_PROBE_TOKEN:-}"
+APPLY="false"
+RELOAD_NGINX="false"
+STATUS_AFTER="true"
+VERIFY_SYSTEMD_AFTER="true"
+
+usage() {
+  cat <<'EOF'
+用法:
+  scripts/deploy/pingora-direct-rollback.sh [--apply] [--reload-nginx] [--nginx-smoke-url <url>] [--nginx-smoke-host <host>] [--nginx-smoke-expect-body <text>] [--curl-binary <path>] [--health-patrol-env-file <path>] [--health-patrol-env-check-script <path>] [--health-patrol-expected-public-base-url <url>] [--health-patrol-expected-public-host <host>|--health-patrol-require-empty-public-host] [--pingora-shadow-probe-url <url>] [--pingora-shadow-probe-token <token>] [--no-postcheck] [--service <name>] [--service-unit-path <path>] [--dropin-path <path>] [--nginx-service <name>] [--nginx-binary <path>]
+
+说明:
+  回退 Pingora 直连低端口入口：移除 direct-entry systemd drop-in，执行 daemon-reload，
+  重启 genarrative-pingora-gateway.service，让服务回到 shadow/high-port 口径。
+
+默认是 dry-run，只打印将执行的命令；必须显式传 --apply 才会修改系统状态。
+--apply 必须同时传 --reload-nginx，让脚本执行 nginx reload，
+脚本会先运行 nginx -t，通过后再 reload，并在 reload 后确认 Nginx 仍处于 active 状态。
+--apply 还必须提供 --nginx-smoke-url，reload 后用 curl 验证 Nginx 入口已经真实响应。
+若提供 --nginx-smoke-expect-body，脚本会要求 smoke 响应体包含该片段，避免 HTTP 200 命中错误入口。
+脚本会以 current release 随包主 service 模板的 ExecStart 为真相源，
+在重启 Pingora 后核验 systemd 最终 ExecStart 仍指向同一个 pingora-gateway 二进制。
+如果提供 --health-patrol-env-file，脚本会在 Nginx smoke 之后复核 health patrol 已切回 nginx 模式，
+并可校验回退后的 public base URL / Host 是否恢复为切换前记录值。
+如果同时提供 --pingora-shadow-probe-url 与 --pingora-shadow-probe-token，脚本会在回退后
+验证 Pingora shadow 高端口探针仍返回 gateway=pingora-shadow。
+EOF
+}
+
+resolve_default_health_patrol_env_check_script() {
+  printf '%s\n' "${REPO_ROOT}/scripts/check-production-health-patrol-env.mjs"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --apply)
+      APPLY="true"
+      shift
+      ;;
+    --reload-nginx)
+      RELOAD_NGINX="true"
+      shift
+      ;;
+    --no-status)
+      STATUS_AFTER="false"
+      shift
+      ;;
+    --no-postcheck)
+      VERIFY_SYSTEMD_AFTER="false"
+      shift
+      ;;
+    --service)
+      SERVICE_NAME="${2:-}"
+      if [[ -z "${SERVICE_NAME}" ]]; then
+        echo "[pingora-direct-rollback] --service 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --service-unit-path)
+      SERVICE_UNIT_PATH="${2:-}"
+      if [[ -z "${SERVICE_UNIT_PATH}" ]]; then
+        echo "[pingora-direct-rollback] --service-unit-path 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --dropin-path)
+      DROPIN_PATH="${2:-}"
+      if [[ -z "${DROPIN_PATH}" ]]; then
+        echo "[pingora-direct-rollback] --dropin-path 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-service)
+      NGINX_SERVICE="${2:-}"
+      if [[ -z "${NGINX_SERVICE}" ]]; then
+        echo "[pingora-direct-rollback] --nginx-service 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-binary)
+      NGINX_BINARY="${2:-}"
+      if [[ -z "${NGINX_BINARY}" ]]; then
+        echo "[pingora-direct-rollback] --nginx-binary 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-smoke-url)
+      NGINX_SMOKE_URL="${2:-}"
+      if [[ -z "${NGINX_SMOKE_URL}" ]]; then
+        echo "[pingora-direct-rollback] --nginx-smoke-url 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-smoke-host)
+      NGINX_SMOKE_HOST="${2:-}"
+      if [[ -z "${NGINX_SMOKE_HOST}" ]]; then
+        echo "[pingora-direct-rollback] --nginx-smoke-host 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-smoke-expect-body)
+      NGINX_SMOKE_EXPECT_BODY="${2:-}"
+      if [[ -z "${NGINX_SMOKE_EXPECT_BODY}" ]]; then
+        echo "[pingora-direct-rollback] --nginx-smoke-expect-body 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --curl-binary)
+      CURL_BINARY="${2:-}"
+      if [[ -z "${CURL_BINARY}" ]]; then
+        echo "[pingora-direct-rollback] --curl-binary 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --health-patrol-env-file)
+      HEALTH_PATROL_ENV_FILE="${2:-}"
+      if [[ -z "${HEALTH_PATROL_ENV_FILE}" ]]; then
+        echo "[pingora-direct-rollback] --health-patrol-env-file 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --health-patrol-env-check-script)
+      HEALTH_PATROL_ENV_CHECK_SCRIPT="${2:-}"
+      if [[ -z "${HEALTH_PATROL_ENV_CHECK_SCRIPT}" ]]; then
+        echo "[pingora-direct-rollback] --health-patrol-env-check-script 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --health-patrol-expected-public-base-url)
+      HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL="${2:-}"
+      if [[ -z "${HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL}" ]]; then
+        echo "[pingora-direct-rollback] --health-patrol-expected-public-base-url 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --health-patrol-expected-public-host)
+      HEALTH_PATROL_EXPECTED_PUBLIC_HOST="${2:-}"
+      if [[ -z "${HEALTH_PATROL_EXPECTED_PUBLIC_HOST}" ]]; then
+        echo "[pingora-direct-rollback] --health-patrol-expected-public-host 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --health-patrol-require-empty-public-host)
+      HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST="true"
+      shift
+      ;;
+    --pingora-shadow-probe-url)
+      PINGORA_SHADOW_PROBE_URL="${2:-}"
+      if [[ -z "${PINGORA_SHADOW_PROBE_URL}" ]]; then
+        echo "[pingora-direct-rollback] --pingora-shadow-probe-url 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --pingora-shadow-probe-token)
+      PINGORA_SHADOW_PROBE_TOKEN="${2:-}"
+      if [[ -z "${PINGORA_SHADOW_PROBE_TOKEN}" ]]; then
+        echo "[pingora-direct-rollback] --pingora-shadow-probe-token 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    *)
+      echo "[pingora-direct-rollback] 未知参数: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -n "${HEALTH_PATROL_ENV_FILE}" && -z "${HEALTH_PATROL_ENV_CHECK_SCRIPT}" ]]; then
+  HEALTH_PATROL_ENV_CHECK_SCRIPT="$(resolve_default_health_patrol_env_check_script)"
+fi
+
+reject_control_characters() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" == *$'\n'* || "${value}" == *$'\r'* ]]; then
+    echo "[pingora-direct-rollback] ${label} 不能包含换行或 NUL 字符。" >&2
+    exit 1
+  fi
+}
+
+is_filesystem_root_path() {
+  local value="$1"
+  local without_slashes="${value//\//}"
+  [[ -n "${value}" && -z "${without_slashes}" ]]
+}
+
+reject_filesystem_root_path() {
+  local label="$1"
+  local value="$2"
+  if is_filesystem_root_path "${value}"; then
+    echo "[pingora-direct-rollback] ${label} 不能是文件系统根目录。" >&2
+    exit 1
+  fi
+}
+
+reject_control_characters "--service" "${SERVICE_NAME}"
+reject_control_characters "--service-unit-path" "${SERVICE_UNIT_PATH}"
+reject_control_characters "--dropin-path" "${DROPIN_PATH}"
+reject_control_characters "--nginx-service" "${NGINX_SERVICE}"
+reject_control_characters "--nginx-binary" "${NGINX_BINARY}"
+reject_control_characters "--nginx-smoke-url" "${NGINX_SMOKE_URL}"
+reject_control_characters "--nginx-smoke-host" "${NGINX_SMOKE_HOST}"
+reject_control_characters "--nginx-smoke-expect-body" "${NGINX_SMOKE_EXPECT_BODY}"
+reject_control_characters "--curl-binary" "${CURL_BINARY}"
+reject_control_characters "--health-patrol-env-file" "${HEALTH_PATROL_ENV_FILE}"
+reject_control_characters "--health-patrol-env-check-script" "${HEALTH_PATROL_ENV_CHECK_SCRIPT}"
+reject_control_characters "--health-patrol-expected-public-base-url" "${HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL}"
+reject_control_characters "--health-patrol-expected-public-host" "${HEALTH_PATROL_EXPECTED_PUBLIC_HOST}"
+reject_control_characters "--health-patrol-require-empty-public-host" "${HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST}"
+reject_control_characters "--pingora-shadow-probe-url" "${PINGORA_SHADOW_PROBE_URL}"
+reject_control_characters "--pingora-shadow-probe-token" "${PINGORA_SHADOW_PROBE_TOKEN}"
+
+reject_filesystem_root_path "--service-unit-path" "${SERVICE_UNIT_PATH}"
+reject_filesystem_root_path "--dropin-path" "${DROPIN_PATH}"
+reject_filesystem_root_path "--nginx-binary" "${NGINX_BINARY}"
+reject_filesystem_root_path "--curl-binary" "${CURL_BINARY}"
+reject_filesystem_root_path "--health-patrol-env-file" "${HEALTH_PATROL_ENV_FILE}"
+reject_filesystem_root_path "--health-patrol-env-check-script" "${HEALTH_PATROL_ENV_CHECK_SCRIPT}"
+
+if [[ "${DROPIN_PATH}" != /* ]]; then
+  echo "[pingora-direct-rollback] --dropin-path 必须是绝对路径: ${DROPIN_PATH}" >&2
+  exit 1
+fi
+
+if [[ "${SERVICE_UNIT_PATH}" != /* ]]; then
+  echo "[pingora-direct-rollback] --service-unit-path 必须是绝对路径: ${SERVICE_UNIT_PATH}" >&2
+  exit 1
+fi
+
+if [[ -n "${HEALTH_PATROL_ENV_FILE}" && "${HEALTH_PATROL_ENV_FILE}" != /* ]]; then
+  echo "[pingora-direct-rollback] --health-patrol-env-file 必须是绝对路径: ${HEALTH_PATROL_ENV_FILE}" >&2
+  exit 1
+fi
+
+if [[ -n "${HEALTH_PATROL_ENV_CHECK_SCRIPT}" && "${HEALTH_PATROL_ENV_CHECK_SCRIPT}" != /* ]]; then
+  echo "[pingora-direct-rollback] --health-patrol-env-check-script 必须是绝对路径: ${HEALTH_PATROL_ENV_CHECK_SCRIPT}" >&2
+  exit 1
+fi
+
+require_absolute_path_if_path_like() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" == */* && "${value}" != /* ]]; then
+    echo "[pingora-direct-rollback] ${label} 包含路径分隔符时必须是绝对路径: ${value}" >&2
+    exit 1
+  fi
+}
+
+require_absolute_path_if_path_like "--nginx-binary" "${NGINX_BINARY}"
+require_absolute_path_if_path_like "--curl-binary" "${CURL_BINARY}"
+
+if [[ -n "${PINGORA_SHADOW_PROBE_URL}" && -z "${PINGORA_SHADOW_PROBE_TOKEN}" ]]; then
+  echo "[pingora-direct-rollback] --pingora-shadow-probe-url 必须同时提供 --pingora-shadow-probe-token。" >&2
+  exit 1
+fi
+
+if [[ -n "${PINGORA_SHADOW_PROBE_TOKEN}" && -z "${PINGORA_SHADOW_PROBE_URL}" ]]; then
+  echo "[pingora-direct-rollback] --pingora-shadow-probe-token 必须同时提供 --pingora-shadow-probe-url。" >&2
+  exit 1
+fi
+
+if [[ -n "${HEALTH_PATROL_EXPECTED_PUBLIC_HOST}" && "${HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST}" == "true" ]]; then
+  echo "[pingora-direct-rollback] --health-patrol-expected-public-host 和 --health-patrol-require-empty-public-host 不能同时使用。" >&2
+  exit 1
+fi
+
+validate_nginx_smoke_host() {
+  validate_host_value "--nginx-smoke-host" "${NGINX_SMOKE_HOST}"
+}
+
+validate_host_value() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" == *"://"* || "${value}" == */* || "${value}" == *\?* || "${value}" == *"#"* || "${value}" =~ [[:space:]] ]]; then
+    echo "[pingora-direct-rollback] ${label} 只能是 host 或 host:port，不能包含 URL、路径、查询、片段或空白字符: ${value}" >&2
+    exit 1
+  fi
+}
+
+is_loopback_smoke_url() {
+  local url="$1"
+  local authority host
+  case "${url}" in
+    http://*|https://*) ;;
+    *) return 1 ;;
+  esac
+  authority="${url#*://}"
+  authority="${authority%%/*}"
+  authority="${authority%%\?*}"
+  authority="${authority%%#*}"
+  authority="${authority##*@}"
+  if [[ "${authority}" == \[*\]* ]]; then
+    host="${authority#\[}"
+    host="${host%%\]*}"
+  else
+    host="${authority%%:*}"
+  fi
+  host="${host,,}"
+  [[ "${host}" == "localhost" || "${host}" == "127."* || "${host}" == "::1" ]]
+}
+
+validate_http_url() {
+  local label="$1"
+  local url="$2"
+  case "${url}" in
+    http://*|https://*) ;;
+    *)
+      echo "[pingora-direct-rollback] ${label} 必须是 http(s) URL: ${url}" >&2
+      exit 1
+      ;;
+  esac
+}
+
+if [[ -n "${NGINX_SMOKE_HOST}" ]]; then
+  validate_nginx_smoke_host
+fi
+
+if [[ -n "${HEALTH_PATROL_EXPECTED_PUBLIC_HOST}" ]]; then
+  validate_host_value "--health-patrol-expected-public-host" "${HEALTH_PATROL_EXPECTED_PUBLIC_HOST}"
+fi
+
+if [[ -n "${PINGORA_SHADOW_PROBE_URL}" ]]; then
+  validate_http_url "--pingora-shadow-probe-url" "${PINGORA_SHADOW_PROBE_URL}"
+fi
+
+if [[ -n "${NGINX_SMOKE_URL}" ]]; then
+  validate_http_url "--nginx-smoke-url" "${NGINX_SMOKE_URL}"
+fi
+
+if [[ -n "${HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL}" ]]; then
+  validate_http_url "--health-patrol-expected-public-base-url" "${HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL}"
+fi
+
+if [[ "${APPLY}" == "true" && "${RELOAD_NGINX}" != "true" ]]; then
+  echo "[pingora-direct-rollback] --apply 必须同时提供 --reload-nginx，确保回退后 Nginx 公网入口重新加载并保持 active。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${NGINX_SMOKE_URL}" ]]; then
+  echo "[pingora-direct-rollback] --apply 必须同时提供 --nginx-smoke-url，确保回退后 Nginx 入口真实可访问。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" == "true" && -z "${NGINX_SMOKE_HOST}" ]] && is_loopback_smoke_url "${NGINX_SMOKE_URL}"; then
+  echo "[pingora-direct-rollback] --nginx-smoke-url 指向本机地址时必须同时提供 --nginx-smoke-host，避免回退 smoke 命中默认 vhost。" >&2
+  exit 1
+fi
+
+run_cmd() {
+  echo "+ $*"
+  if [[ "${APPLY}" == "true" ]]; then
+    "$@"
+  fi
+}
+
+run_systemctl() {
+  if [[ "${APPLY}" != "true" ]]; then
+    run_cmd systemctl "$@"
+    return
+  fi
+  if command -v systemctl >/dev/null 2>&1; then
+    run_cmd systemctl "$@"
+  else
+    echo "[pingora-direct-rollback] 未找到 systemctl，无法执行: systemctl $*" >&2
+    exit 1
+  fi
+}
+
+read_expected_exec_start() {
+  local line value
+  if [[ ! -f "${SERVICE_UNIT_PATH}" ]]; then
+    return 1
+  fi
+  while IFS= read -r line; do
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [[ "${line}" == ExecStart=* ]] || continue
+    value="${line#ExecStart=}"
+    [[ -n "${value}" ]] || continue
+    printf '%s\n' "${value}"
+    return 0
+  done <"${SERVICE_UNIT_PATH}"
+  return 1
+}
+
+first_exec_word() {
+  local value="$1"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  if [[ "${value}" == \"* ]]; then
+    value="${value#\"}"
+    printf '%s\n' "${value%%\"*}"
+    return
+  fi
+  printf '%s\n' "${value%%[[:space:]]*}"
+}
+
+systemd_show_exec_start_matches() {
+  local expected_exec="$1"
+  local expected_binary actual_show actual_binary
+  expected_binary="$(first_exec_word "${expected_exec}")"
+  [[ -n "${expected_binary}" ]] || return 1
+  actual_show="$(systemctl show "${SERVICE_NAME}" --property=ExecStart --value --no-pager)"
+  actual_binary="${actual_show}"
+  if [[ "${actual_show}" == *"path="* ]]; then
+    actual_binary="${actual_show#*path=}"
+    actual_binary="${actual_binary%% ;*}"
+  elif [[ "${actual_show}" == ExecStart=* ]]; then
+    actual_binary="${actual_show#ExecStart=}"
+    actual_binary="$(first_exec_word "${actual_binary}")"
+  else
+    actual_binary="$(first_exec_word "${actual_binary}")"
+  fi
+  [[ "${actual_binary}" == "${expected_binary}" ]]
+}
+
+verify_systemd_exec_start_after_rollback() {
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-rollback] 已跳过 Pingora ExecStart 指向核验。"
+    return
+  fi
+
+  expected_exec_start="$(read_expected_exec_start || true)"
+  if [[ -z "${expected_exec_start}" ]]; then
+    echo "[pingora-direct-rollback] 无法从主 service 模板读取 ExecStart: ${SERVICE_UNIT_PATH}" >&2
+    exit 1
+  fi
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager"
+    echo "[pingora-direct-rollback] dry-run：--apply 后会核验 systemd ExecStart 指向主 service 模板中的 ${expected_exec_start}。"
+    return
+  fi
+
+  if ! command -v systemctl >/dev/null 2>&1; then
+    echo "[pingora-direct-rollback] 未找到 systemctl，无法核验 Pingora ExecStart。" >&2
+    exit 1
+  fi
+
+  echo "+ systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager"
+  if ! systemd_show_exec_start_matches "${expected_exec_start}"; then
+    echo "[pingora-direct-rollback] systemctl show ExecStart 未指向主 service 模板中的 ${expected_exec_start}，请先修正 ${SERVICE_NAME} 指向 current release 网关二进制。" >&2
+    exit 1
+  fi
+}
+
+verify_systemd_dropin_removed() {
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-rollback] 已跳过 systemd drop-in 移除核验。"
+    return
+  fi
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ systemctl cat ${SERVICE_NAME}"
+    echo "[pingora-direct-rollback] dry-run：--apply 后会校验 systemd 最终配置不再包含 CAP_NET_BIND_SERVICE。"
+    return
+  fi
+
+  if ! command -v systemctl >/dev/null 2>&1; then
+    echo "[pingora-direct-rollback] 未找到 systemctl，无法核验 drop-in 是否已移除。" >&2
+    exit 1
+  fi
+
+  echo "+ systemctl cat ${SERVICE_NAME}"
+  unit_content="$(systemctl cat "${SERVICE_NAME}")"
+  if [[ "${unit_content}" == *"AmbientCapabilities=CAP_NET_BIND_SERVICE"* ]]; then
+    echo "[pingora-direct-rollback] systemctl cat 仍显示 AmbientCapabilities=CAP_NET_BIND_SERVICE，direct-entry drop-in 未移除。" >&2
+    exit 1
+  fi
+  if [[ "${unit_content}" == *"CapabilityBoundingSet=CAP_NET_BIND_SERVICE"* ]]; then
+    echo "[pingora-direct-rollback] systemctl cat 仍显示 CapabilityBoundingSet=CAP_NET_BIND_SERVICE，direct-entry drop-in 未移除。" >&2
+    exit 1
+  fi
+}
+
+verify_nginx_active_after_reload() {
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-rollback] 已跳过 Nginx reload 后状态核验。"
+    return
+  fi
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ systemctl is-active ${NGINX_SERVICE}"
+    echo "[pingora-direct-rollback] dry-run：--apply --reload-nginx 后会 reload Nginx 并校验 service 仍为 active。"
+    return
+  fi
+
+  if ! command -v systemctl >/dev/null 2>&1; then
+    echo "[pingora-direct-rollback] 未找到 systemctl，无法核验 Nginx reload 后状态。" >&2
+    exit 1
+  fi
+
+  echo "+ systemctl is-active ${NGINX_SERVICE}"
+  nginx_state="$(systemctl is-active "${NGINX_SERVICE}")"
+  if [[ "${nginx_state}" != "active" ]]; then
+    echo "[pingora-direct-rollback] Nginx reload 后状态不是 active: ${nginx_state}" >&2
+    exit 1
+  fi
+}
+
+verify_nginx_smoke_after_reload() {
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-rollback] 已跳过 Nginx reload 后 smoke 核验。"
+    return
+  fi
+
+  if [[ -z "${NGINX_SMOKE_URL}" ]]; then
+    echo "+ ${CURL_BINARY} --fail --silent --show-error --max-time 5 <nginx-smoke-url>"
+    echo "[pingora-direct-rollback] dry-run：--apply --reload-nginx 后会用 --nginx-smoke-url 验证 Nginx 入口。"
+    return
+  fi
+
+  smoke_args=(
+    --fail
+    --silent
+    --show-error
+    --max-time
+    5
+  )
+  if [[ -n "${NGINX_SMOKE_HOST}" ]]; then
+    smoke_args+=(-H "Host: ${NGINX_SMOKE_HOST}")
+  fi
+  smoke_args+=("${NGINX_SMOKE_URL}")
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ ${CURL_BINARY} ${smoke_args[*]}"
+    if [[ -n "${NGINX_SMOKE_EXPECT_BODY}" ]]; then
+      echo "[pingora-direct-rollback] dry-run：--apply --reload-nginx 后会验证 Nginx smoke URL 可访问，且响应体包含预期片段。"
+    else
+      echo "[pingora-direct-rollback] dry-run：--apply --reload-nginx 后会验证 Nginx smoke URL 可访问。"
+    fi
+    return
+  fi
+
+  if ! command -v "${CURL_BINARY}" >/dev/null 2>&1; then
+    echo "[pingora-direct-rollback] 未找到 curl 可执行文件，无法验证 Nginx smoke URL: ${CURL_BINARY}" >&2
+    exit 1
+  fi
+
+  echo "+ ${CURL_BINARY} ${smoke_args[*]}"
+  smoke_body="$("${CURL_BINARY}" "${smoke_args[@]}")"
+  if [[ -n "${NGINX_SMOKE_EXPECT_BODY}" ]]; then
+    if [[ "${smoke_body}" != *"${NGINX_SMOKE_EXPECT_BODY}"* ]]; then
+      echo "[pingora-direct-rollback] Nginx smoke 响应缺少预期片段: ${NGINX_SMOKE_EXPECT_BODY}" >&2
+      echo "[pingora-direct-rollback] Nginx smoke 响应前 500 字符: ${smoke_body:0:500}" >&2
+      exit 1
+    fi
+    echo "[pingora-direct-rollback] nginx smoke evidence matched expected body fragment."
+  else
+    echo "[pingora-direct-rollback] nginx smoke evidence curl --fail passed without body fragment check."
+  fi
+}
+
+test_nginx_config_before_reload() {
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ ${NGINX_BINARY} -t"
+    echo "[pingora-direct-rollback] dry-run：--apply --reload-nginx 后会先执行 nginx -t，通过后再 reload。"
+    return
+  fi
+
+  if ! command -v "${NGINX_BINARY}" >/dev/null 2>&1; then
+    echo "[pingora-direct-rollback] 未找到 Nginx 可执行文件，无法执行: ${NGINX_BINARY} -t" >&2
+    exit 1
+  fi
+
+  echo "+ ${NGINX_BINARY} -t"
+  "${NGINX_BINARY}" -t
+}
+
+validate_dropin_path_for_apply() {
+  if [[ "${APPLY}" != "true" ]]; then
+    return
+  fi
+
+  DROPIN_DIR="$(dirname "${DROPIN_PATH}")"
+  if [[ -L "${DROPIN_DIR}" ]]; then
+    echo "[pingora-direct-rollback] drop-in 目录不能是符号链接: ${DROPIN_DIR}" >&2
+    exit 1
+  fi
+  if [[ -e "${DROPIN_DIR}" && ! -d "${DROPIN_DIR}" ]]; then
+    echo "[pingora-direct-rollback] drop-in 父路径必须是目录: ${DROPIN_DIR}" >&2
+    exit 1
+  fi
+  if [[ -L "${DROPIN_PATH}" ]]; then
+    echo "[pingora-direct-rollback] drop-in 目标不能是符号链接: ${DROPIN_PATH}" >&2
+    exit 1
+  fi
+  if [[ -e "${DROPIN_PATH}" && ! -f "${DROPIN_PATH}" ]]; then
+    echo "[pingora-direct-rollback] drop-in 目标已存在但不是普通文件: ${DROPIN_PATH}" >&2
+    exit 1
+  fi
+}
+
+verify_health_patrol_env_after_rollback() {
+  if [[ -z "${HEALTH_PATROL_ENV_FILE}" ]]; then
+    return
+  fi
+
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-rollback] 已跳过 health patrol env 回退后复核。"
+    return
+  fi
+
+  health_patrol_args=(
+    "${HEALTH_PATROL_ENV_CHECK_SCRIPT}"
+    --env-file
+    "${HEALTH_PATROL_ENV_FILE}"
+    --expected-gateway-mode
+    nginx
+  )
+  if [[ -n "${HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL}" ]]; then
+    health_patrol_args+=(
+      --expected-public-base-url
+      "${HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL}"
+    )
+  fi
+  if [[ -n "${HEALTH_PATROL_EXPECTED_PUBLIC_HOST}" ]]; then
+    health_patrol_args+=(
+      --expected-public-host
+      "${HEALTH_PATROL_EXPECTED_PUBLIC_HOST}"
+    )
+  elif [[ "${HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST}" != "false" ]]; then
+    health_patrol_args+=(--require-empty-public-host)
+  fi
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ node -- ${health_patrol_args[*]}"
+    echo "[pingora-direct-rollback] dry-run：--apply 后会复核 health patrol env 已切回 nginx，且 public base URL / Host 已恢复为预期值。"
+    return
+  fi
+
+  if ! command -v node >/dev/null 2>&1; then
+    echo "[pingora-direct-rollback] 未找到 node，无法复核 health patrol env。" >&2
+    exit 1
+  fi
+  if [[ ! -f "${HEALTH_PATROL_ENV_CHECK_SCRIPT}" ]]; then
+    echo "[pingora-direct-rollback] health patrol env 复核脚本不存在: ${HEALTH_PATROL_ENV_CHECK_SCRIPT}" >&2
+    exit 1
+  fi
+
+  echo "+ node -- ${health_patrol_args[*]}"
+  node -- "${health_patrol_args[@]}"
+}
+
+verify_pingora_shadow_probe_after_rollback() {
+  if [[ -z "${PINGORA_SHADOW_PROBE_URL}" ]]; then
+    return
+  fi
+
+  if [[ "${VERIFY_SYSTEMD_AFTER}" != "true" ]]; then
+    echo "[pingora-direct-rollback] 已跳过 Pingora shadow 探针回退后核验。"
+    return
+  fi
+
+  shadow_args=(
+    --fail
+    --silent
+    --show-error
+    --max-time
+    5
+    -H
+    "X-Genarrative-Pingora-Probe: ${PINGORA_SHADOW_PROBE_TOKEN}"
+    "${PINGORA_SHADOW_PROBE_URL}"
+  )
+
+  if [[ "${APPLY}" != "true" ]]; then
+    echo "+ ${CURL_BINARY} --fail --silent --show-error --max-time 5 -H X-Genarrative-Pingora-Probe: <redacted> ${PINGORA_SHADOW_PROBE_URL}"
+    echo "[pingora-direct-rollback] dry-run：--apply 后会验证 Pingora shadow 探针仍为 gateway=pingora-shadow。"
+    return
+  fi
+
+  if ! command -v "${CURL_BINARY}" >/dev/null 2>&1; then
+    echo "[pingora-direct-rollback] 未找到 curl 可执行文件，无法验证 Pingora shadow 探针: ${CURL_BINARY}" >&2
+    exit 1
+  fi
+
+  echo "+ ${CURL_BINARY} --fail --silent --show-error --max-time 5 -H X-Genarrative-Pingora-Probe: <redacted> ${PINGORA_SHADOW_PROBE_URL}"
+  shadow_body="$("${CURL_BINARY}" "${shadow_args[@]}")"
+  if [[ "${shadow_body}" != *'"ok":true'* || "${shadow_body}" != *'"gateway":"pingora-shadow"'* ]]; then
+    echo "[pingora-direct-rollback] Pingora shadow 探针响应不是预期 JSON: ${shadow_body}" >&2
+    exit 1
+  fi
+}
+
+echo "[pingora-direct-rollback] apply=${APPLY} service=${SERVICE_NAME} dropin=${DROPIN_PATH}"
+
+if [[ "${APPLY}" != "true" ]]; then
+  echo "[pingora-direct-rollback] 当前是 dry-run；确认无误后追加 --apply。"
+fi
+
+validate_dropin_path_for_apply
+test_nginx_config_before_reload
+
+if [[ -e "${DROPIN_PATH}" || -L "${DROPIN_PATH}" ]]; then
+  run_cmd rm -f "${DROPIN_PATH}"
+else
+  echo "[pingora-direct-rollback] direct-entry drop-in 不存在，视为已移除: ${DROPIN_PATH}"
+fi
+
+run_systemctl daemon-reload
+run_systemctl restart "${SERVICE_NAME}"
+verify_systemd_dropin_removed
+verify_systemd_exec_start_after_rollback
+
+run_systemctl reload "${NGINX_SERVICE}"
+verify_nginx_active_after_reload
+verify_nginx_smoke_after_reload
+verify_health_patrol_env_after_rollback
+verify_pingora_shadow_probe_after_rollback
+
+if [[ "${STATUS_AFTER}" == "true" ]]; then
+  run_systemctl status "${SERVICE_NAME}" --no-pager
+fi
+
+cat <<EOF
+[pingora-direct-rollback] 完成。后续请确认：
+- systemctl cat ${SERVICE_NAME} 不再包含 AmbientCapabilities=CAP_NET_BIND_SERVICE
+- systemctl show ${SERVICE_NAME} --property=ExecStart --value --no-pager 指向 current release 的 pingora-gateway
+- ${NGINX_BINARY} -t 已通过
+- systemctl is-active ${NGINX_SERVICE} 为 active
+- ${CURL_BINARY} --fail ${NGINX_SMOKE_URL:-<nginx-smoke-url>} 已通过
+- 如传入 --nginx-smoke-expect-body，Nginx smoke 响应体已匹配预期片段
+- 如传入 --health-patrol-env-file，health patrol env 已复核为 nginx 模式且 public base URL / Host 符合预期
+- 如传入 --pingora-shadow-probe-url，Pingora shadow 高端口探针已复核为 gateway=pingora-shadow
+- 公网入口已回到 Nginx 或其它正式前置入口
+EOF
diff --git a/scripts/deploy/pingora-gateway-env-shadow-switch.mjs b/scripts/deploy/pingora-gateway-env-shadow-switch.mjs
new file mode 100644
index 000000000..ab7ba188e
--- /dev/null
+++ b/scripts/deploy/pingora-gateway-env-shadow-switch.mjs
@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+import {
+  chownSync,
+  chmodSync,
+  lstatSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const TARGET_KEYS = [
+  'GENARRATIVE_PINGORA_GATEWAY_LISTEN',
+  'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN',
+  'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+  'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE',
+  'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE',
+];
+const SHADOW_VALUES = {
+  GENARRATIVE_PINGORA_GATEWAY_LISTEN: '127.0.0.1:18081',
+  GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: '',
+  GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: '',
+  GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: '',
+  GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: '',
+};
+const DRY_RUN_ENV_FILE_MODE = 0o600;
+
+const config = parseArgs(process.argv.slice(2));
+if (config.apply) {
+  assertEnvFileIsWritableRegularFile(config.envFile);
+}
+
+const originalText = readFileSync(config.envFile, 'utf8');
+const nextText = rewriteEnvFile(originalText, SHADOW_VALUES);
+const checkFile = writeDryRunEnv(nextText);
+
+try {
+  console.log(
+    `[pingora-gateway-env-shadow-switch] apply=${config.apply} env=${config.envFile}`,
+  );
+  for (const key of TARGET_KEYS) {
+    console.log(`~ ${key}=${SHADOW_VALUES[key]}`);
+  }
+  assertShadowEnv(checkFile);
+
+  if (!config.apply) {
+    console.log(
+      '[pingora-gateway-env-shadow-switch] 当前是 dry-run；追加 --apply 后才会写入 env 文件。',
+    );
+  } else {
+    writeEnvFileAtomically(config.envFile, nextText);
+  }
+
+  console.log('[pingora-gateway-env-shadow-switch] 完成');
+} finally {
+  rmSync(path.dirname(checkFile), { recursive: true, force: true });
+}
+
+function parseArgs(argv) {
+  const result = {
+    envFile:
+      process.env.GENARRATIVE_PINGORA_GATEWAY_ENV_FILE ||
+      '/etc/genarrative/pingora-gateway.env',
+    apply: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--env-file':
+        result.envFile = requireValue(argv, ++index, arg);
+        break;
+      case '--apply':
+        result.apply = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (!path.isAbsolute(result.envFile)) {
+    throw new Error(`--env-file 必须是绝对路径: ${result.envFile}`);
+  }
+  validateNoControlCharacters(result.envFile, '--env-file');
+  if (isFilesystemRootPath(result.envFile)) {
+    throw new Error('--env-file 不能是文件系统根目录。');
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/deploy/pingora-gateway-env-shadow-switch.mjs [options]
+
+Options:
+  --env-file <path>  Pingora gateway env 文件，默认 /etc/genarrative/pingora-gateway.env。
+  --apply            写入 env 文件；默认只 dry-run 并用临时 env 复核。
+`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function rewriteEnvFile(text, nextValuesByKey) {
+  const lines = text.replace(/\r\n/gu, '\n').split('\n');
+  if (lines.at(-1) === '') {
+    lines.pop();
+  }
+
+  const seen = new Set();
+  const output = [];
+  for (const line of lines) {
+    const assignment = parseAssignmentLine(line);
+    if (!assignment || !TARGET_KEYS.includes(assignment.key)) {
+      output.push(line);
+      continue;
+    }
+    if (seen.has(assignment.key)) {
+      throw new Error(`pingora gateway env 中存在重复配置: ${assignment.key}`);
+    }
+    seen.add(assignment.key);
+    output.push(
+      `${assignment.leading}${assignment.exportPrefix}${assignment.key}=${nextValuesByKey[assignment.key]}`,
+    );
+  }
+
+  for (const key of TARGET_KEYS) {
+    if (!seen.has(key)) {
+      output.push(`${key}=${nextValuesByKey[key]}`);
+    }
+  }
+
+  return `${output.join('\n')}\n`;
+}
+
+function parseAssignmentLine(line) {
+  const match = line.match(/^(\s*)(export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/u);
+  if (!match) {
+    return null;
+  }
+  return {
+    leading: match[1] || '',
+    exportPrefix: match[2] || '',
+    key: match[3],
+  };
+}
+
+function writeDryRunEnv(content) {
+  const dir = mkdtempSync(
+    path.join(tmpdir(), 'genarrative-pingora-gateway-env-shadow-switch-'),
+  );
+  const filePath = path.join(dir, 'pingora-gateway.env');
+  writeFileSync(filePath, content, {
+    encoding: 'utf8',
+    mode: DRY_RUN_ENV_FILE_MODE,
+  });
+  chmodSync(filePath, DRY_RUN_ENV_FILE_MODE);
+  return filePath;
+}
+
+function assertShadowEnv(filePath) {
+  const values = parseEnvFile(readFileSync(filePath, 'utf8'));
+  if (
+    values.GENARRATIVE_PINGORA_GATEWAY_LISTEN !==
+    SHADOW_VALUES.GENARRATIVE_PINGORA_GATEWAY_LISTEN
+  ) {
+    throw new Error(
+      'shadow env 复核失败：GENARRATIVE_PINGORA_GATEWAY_LISTEN 必须是 127.0.0.1:18081。',
+    );
+  }
+  for (const key of [
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN',
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE',
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE',
+  ]) {
+    if ((values[key] || '') !== '') {
+      throw new Error(`shadow env 复核失败：${key} 必须为空。`);
+    }
+  }
+}
+
+function parseEnvFile(text) {
+  const values = {};
+  for (const line of text.split(/\r?\n/u)) {
+    const assignment = parseAssignmentLine(line);
+    if (!assignment) {
+      continue;
+    }
+    values[assignment.key] = line
+      .slice(line.indexOf('=') + 1)
+      .trim()
+      .replace(/^['"]|['"]$/gu, '');
+  }
+  return values;
+}
+
+function writeEnvFileAtomically(filePath, content) {
+  const currentStat = assertEnvFileIsWritableRegularFile(filePath);
+  const currentMode = currentStat.mode & 0o777;
+  const tempFile = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  try {
+    writeFileSync(tempFile, content, { encoding: 'utf8', mode: currentMode });
+    chownSync(tempFile, currentStat.uid, currentStat.gid);
+    chmodSync(tempFile, currentMode);
+    assertEnvFileIsWritableRegularFile(filePath);
+    renameSync(tempFile, filePath);
+  } catch (error) {
+    rmSync(tempFile, { force: true });
+    throw error;
+  }
+}
+
+function assertEnvFileIsWritableRegularFile(filePath) {
+  const currentStat = lstatSync(filePath);
+  if (currentStat.isSymbolicLink()) {
+    throw new Error(
+      `--env-file 不能是符号链接；请直接传真实 Pingora gateway env 文件路径: ${filePath}`,
+    );
+  }
+  if (!currentStat.isFile()) {
+    throw new Error(`--env-file 必须指向普通文件: ${filePath}`);
+  }
+  return currentStat;
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value ?? ''))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
diff --git a/scripts/deploy/pingora-health-patrol-env-switch.mjs b/scripts/deploy/pingora-health-patrol-env-switch.mjs
new file mode 100644
index 000000000..60f5df19a
--- /dev/null
+++ b/scripts/deploy/pingora-health-patrol-env-switch.mjs
@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  chownSync,
+  chmodSync,
+  lstatSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const GATEWAY_MODES = new Set(['nginx', 'pingora-direct']);
+const TARGET_KEYS = [
+  'GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE',
+  'GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL',
+  'GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST',
+];
+const DRY_RUN_ENV_FILE_MODE = 0o600;
+
+const config = parseArgs(process.argv.slice(2));
+if (config.apply) {
+  assertEnvFileIsWritableRegularFile(config.envFile);
+}
+const originalText = readFileSync(config.envFile, 'utf8');
+const nextValues = {
+  GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE: config.gatewayMode,
+  GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL: normalizeBaseUrl(
+    config.publicBaseUrl,
+    '--public-base-url',
+  ),
+  GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST: config.clearPublicHost
+    ? ''
+    : config.publicHost,
+};
+const nextText = rewriteEnvFile(originalText, nextValues);
+const checkFile = writeDryRunEnv(nextText);
+
+try {
+  console.log(
+    `[pingora-health-patrol-env-switch] apply=${config.apply} env=${config.envFile} mode=${config.gatewayMode}`,
+  );
+  for (const key of TARGET_KEYS) {
+    console.log(`~ ${key}=${nextValues[key]}`);
+  }
+
+  runHealthPatrolEnvCheck(checkFile);
+
+  if (!config.apply) {
+    console.log(
+      '[pingora-health-patrol-env-switch] 当前是 dry-run；追加 --apply 后才会写入 env 文件。',
+    );
+  } else {
+    writeEnvFileAtomically(config.envFile, nextText);
+  }
+
+  console.log('[pingora-health-patrol-env-switch] 完成');
+} finally {
+  rmSync(path.dirname(checkFile), { recursive: true, force: true });
+}
+
+function parseArgs(argv) {
+  const result = {
+    envFile:
+      process.env.GENARRATIVE_HEALTH_PATROL_ENV_FILE ||
+      '/etc/genarrative/health-patrol.env',
+    gatewayMode: process.env.GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE || '',
+    publicBaseUrl:
+      process.env.GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL || '',
+    publicHost: process.env.GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST || null,
+    clearPublicHost: readBoolEnv(
+      'GENARRATIVE_HEALTH_PATROL_CLEAR_PUBLIC_HOST',
+    ),
+    checkScript:
+      process.env.GENARRATIVE_HEALTH_PATROL_ENV_CHECK_SCRIPT ||
+      defaultEnvCheckScript(),
+    apply: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--env-file':
+        result.envFile = requireValue(argv, ++index, arg);
+        break;
+      case '--gateway-mode':
+        result.gatewayMode = requireValue(argv, ++index, arg);
+        break;
+      case '--public-base-url':
+        result.publicBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--public-host':
+        result.publicHost = requireValue(argv, ++index, arg);
+        break;
+      case '--clear-public-host':
+        result.clearPublicHost = true;
+        break;
+      case '--check-script':
+        result.checkScript = requireValue(argv, ++index, arg);
+        break;
+      case '--apply':
+        result.apply = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (!path.isAbsolute(result.envFile)) {
+    throw new Error(`--env-file 必须是绝对路径: ${result.envFile}`);
+  }
+  validateNoControlCharacters(result.envFile, '--env-file');
+  if (isFilesystemRootPath(result.envFile)) {
+    throw new Error('--env-file 不能是文件系统根目录。');
+  }
+  if (!path.isAbsolute(result.checkScript)) {
+    throw new Error(`--check-script 必须是绝对路径: ${result.checkScript}`);
+  }
+  validateNoControlCharacters(result.checkScript, '--check-script');
+  if (isFilesystemRootPath(result.checkScript)) {
+    throw new Error('--check-script 不能是文件系统根目录。');
+  }
+  if (!GATEWAY_MODES.has(result.gatewayMode)) {
+    throw new Error(
+      `--gateway-mode 只支持 nginx 或 pingora-direct: ${result.gatewayMode}`,
+    );
+  }
+  if (!result.publicBaseUrl) {
+    throw new Error('必须提供 --public-base-url。');
+  }
+  normalizeBaseUrl(result.publicBaseUrl, '--public-base-url');
+  if (result.publicHost !== null && result.clearPublicHost) {
+    throw new Error('--public-host 和 --clear-public-host 不能同时使用。');
+  }
+  if (result.publicHost === null && !result.clearPublicHost) {
+    throw new Error(
+      '必须显式提供 --public-host 或 --clear-public-host，避免沿用旧 Host 覆盖。',
+    );
+  }
+  if (result.publicHost !== null) {
+    validateHostOption(result.publicHost, '--public-host');
+  }
+  if (
+    result.gatewayMode === 'pingora-direct' &&
+    isLoopbackUrl(result.publicBaseUrl) &&
+    result.clearPublicHost
+  ) {
+    throw new Error(
+      'Pingora direct 模式使用本机 public base URL 时必须提供 --public-host，避免巡检命中默认 vhost。',
+    );
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/deploy/pingora-health-patrol-env-switch.mjs --gateway-mode <nginx|pingora-direct> --public-base-url <url> (--public-host <host>|--clear-public-host) [options]
+
+Options:
+  --env-file <path>          health-patrol env 文件，默认 /etc/genarrative/health-patrol.env。
+  --gateway-mode <mode>      nginx 或 pingora-direct。
+  --public-base-url <url>    写入 GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL。
+  --public-host <host>       写入 GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST。
+  --clear-public-host        清空 GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST。
+  --check-script <path>      env 复核脚本，默认使用同一 release 内的 check-production-health-patrol-env.mjs。
+  --apply                    写入 env 文件；默认只 dry-run 并用临时 env 复核。
+`);
+}
+
+function readBoolEnv(name) {
+  const value = process.env[name];
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return false;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${name} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function defaultEnvCheckScript() {
+  const scriptPath = fileURLToPath(import.meta.url);
+  const releaseRoot = path.resolve(path.dirname(scriptPath), '../..');
+  return path.join(releaseRoot, 'scripts/check-production-health-patrol-env.mjs');
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function rewriteEnvFile(text, nextValuesByKey) {
+  const lines = text.replace(/\r\n/gu, '\n').split('\n');
+  if (lines.at(-1) === '') {
+    lines.pop();
+  }
+
+  const seen = new Set();
+  const output = [];
+  for (const line of lines) {
+    const assignment = parseAssignmentLine(line);
+    if (!assignment || !TARGET_KEYS.includes(assignment.key)) {
+      output.push(line);
+      continue;
+    }
+    if (seen.has(assignment.key)) {
+      throw new Error(`health patrol env 中存在重复配置: ${assignment.key}`);
+    }
+    seen.add(assignment.key);
+    output.push(
+      `${assignment.leading}${assignment.exportPrefix}${assignment.key}=${nextValuesByKey[assignment.key]}`,
+    );
+  }
+
+  for (const key of TARGET_KEYS) {
+    if (!seen.has(key)) {
+      output.push(`${key}=${nextValuesByKey[key]}`);
+    }
+  }
+
+  return `${output.join('\n')}\n`;
+}
+
+function parseAssignmentLine(line) {
+  const match = line.match(/^(\s*)(export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/u);
+  if (!match) {
+    return null;
+  }
+  return {
+    leading: match[1] || '',
+    exportPrefix: match[2] || '',
+    key: match[3],
+  };
+}
+
+function writeDryRunEnv(content) {
+  const dir = mkdtempSync(
+    path.join(tmpdir(), 'genarrative-health-patrol-env-switch-'),
+  );
+  const filePath = path.join(dir, 'health-patrol.env');
+  writeFileSync(filePath, content, {
+    encoding: 'utf8',
+    mode: DRY_RUN_ENV_FILE_MODE,
+  });
+  chmodSync(filePath, DRY_RUN_ENV_FILE_MODE);
+  return filePath;
+}
+
+function writeEnvFileAtomically(filePath, content) {
+  const currentStat = assertEnvFileIsWritableRegularFile(filePath);
+  const currentMode = currentStat.mode & 0o777;
+  const tempFile = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  try {
+    writeFileSync(tempFile, content, { encoding: 'utf8', mode: currentMode });
+    chownSync(tempFile, currentStat.uid, currentStat.gid);
+    chmodSync(tempFile, currentMode);
+    assertEnvFileIsWritableRegularFile(filePath);
+    renameSync(tempFile, filePath);
+  } catch (error) {
+    rmSync(tempFile, { force: true });
+    throw error;
+  }
+}
+
+function assertEnvFileIsWritableRegularFile(filePath) {
+  const currentStat = lstatSync(filePath);
+  if (currentStat.isSymbolicLink()) {
+    throw new Error(
+      `--env-file 不能是符号链接；请直接传真实 health patrol env 文件路径: ${filePath}`,
+    );
+  }
+  if (!currentStat.isFile()) {
+    throw new Error(`--env-file 必须指向普通文件: ${filePath}`);
+  }
+  return currentStat;
+}
+
+function runHealthPatrolEnvCheck(envFile) {
+  const checkArgs = [
+    config.checkScript,
+    '--env-file',
+    envFile,
+    '--expected-gateway-mode',
+    config.gatewayMode,
+    '--expected-public-base-url',
+    normalizeBaseUrl(config.publicBaseUrl, '--public-base-url'),
+  ];
+  if (config.clearPublicHost) {
+    checkArgs.push('--require-empty-public-host');
+  } else {
+    checkArgs.push('--expected-public-host', config.publicHost);
+  }
+
+  console.log(`+ node ${checkArgs.join(' ')}`);
+  const result = spawnSync(process.execPath, ['--', ...checkArgs], {
+    encoding: 'utf8',
+  });
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+function normalizeBaseUrl(value, label) {
+  validateNoControlCharacters(value, label);
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error('unsupported protocol');
+    }
+    return parsed.toString().replace(/\/+$/u, '');
+  } catch {
+    throw new Error(`${label} 必须是合法 http(s) URL: ${value}`);
+  }
+}
+
+function validateHostOption(value, label) {
+  const raw = String(value);
+  validateNoControlCharacters(raw, label);
+  if (raw !== raw.trim() || raw.includes('://') || /[\s/?#@]/u.test(raw)) {
+    throw new Error(
+      `${label} 只能是 host 或 host:port，不能包含 scheme、路径、查询、片段或空白字符。`,
+    );
+  }
+  try {
+    const parsed = new URL(`https://${raw}`);
+    if (
+      !parsed.hostname ||
+      parsed.pathname !== '/' ||
+      parsed.search ||
+      parsed.hash ||
+      parsed.username ||
+      parsed.password
+    ) {
+      throw new Error('invalid host');
+    }
+  } catch {
+    throw new Error(`${label} 不是合法的 host 或 host:port。`);
+  }
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value ?? ''))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function isLoopbackUrl(value) {
+  try {
+    const hostname = new URL(value).hostname.toLowerCase();
+    return (
+      hostname === 'localhost' ||
+      hostname === '::1' ||
+      hostname === '[::1]' ||
+      hostname.startsWith('127.')
+    );
+  } catch {
+    return false;
+  }
+}
diff --git a/scripts/deploy/pingora-realpath-canary-disable.sh b/scripts/deploy/pingora-realpath-canary-disable.sh
new file mode 100644
index 000000000..379048b8d
--- /dev/null
+++ b/scripts/deploy/pingora-realpath-canary-disable.sh
@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+TARGET_PATH="${GENARRATIVE_PINGORA_REALPATH_CANARY_TARGET_PATH:-/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf}"
+NGINX_BINARY="${GENARRATIVE_NGINX_BINARY:-nginx}"
+NGINX_SERVICE="${GENARRATIVE_NGINX_SERVICE:-nginx.service}"
+SYSTEMCTL_BINARY="${GENARRATIVE_SYSTEMCTL_BINARY:-systemctl}"
+APPLY="false"
+STATUS_AFTER="true"
+
+usage() {
+  cat <<'EOF'
+用法:
+  scripts/deploy/pingora-realpath-canary-disable.sh [--apply] [--target-path <path>] [--nginx-binary <path|name>] [--nginx-service <unit>] [--systemctl-binary <path|name>] [--no-status]
+
+说明:
+  关闭 Nginx -> Pingora 真实路径 canary：删除
+  /etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf，执行 nginx -t，
+  再 reload nginx。默认 dry-run，必须显式传 --apply 才会修改系统。
+  如果 nginx -t 或 reload 失败，脚本会恢复删除前的目标文件。
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --apply)
+      APPLY="true"
+      shift
+      ;;
+    --target-path)
+      TARGET_PATH="${2:-}"
+      if [[ -z "${TARGET_PATH}" ]]; then
+        echo "[pingora-realpath-canary-disable] --target-path 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-binary)
+      NGINX_BINARY="${2:-}"
+      if [[ -z "${NGINX_BINARY}" ]]; then
+        echo "[pingora-realpath-canary-disable] --nginx-binary 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-service)
+      NGINX_SERVICE="${2:-}"
+      if [[ -z "${NGINX_SERVICE}" ]]; then
+        echo "[pingora-realpath-canary-disable] --nginx-service 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --systemctl-binary)
+      SYSTEMCTL_BINARY="${2:-}"
+      if [[ -z "${SYSTEMCTL_BINARY}" ]]; then
+        echo "[pingora-realpath-canary-disable] --systemctl-binary 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --no-status)
+      STATUS_AFTER="false"
+      shift
+      ;;
+    *)
+      echo "[pingora-realpath-canary-disable] 未知参数: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+reject_control_characters() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" == *$'\n'* || "${value}" == *$'\r'* ]]; then
+    echo "[pingora-realpath-canary-disable] ${label} 不能包含换行或 NUL 字符。" >&2
+    exit 1
+  fi
+}
+
+is_filesystem_root_path() {
+  local value="$1"
+  local without_slashes="${value//\//}"
+  [[ -n "${value}" && -z "${without_slashes}" ]]
+}
+
+require_absolute_path() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" != /* ]]; then
+    echo "[pingora-realpath-canary-disable] ${label} 必须是绝对路径。" >&2
+    exit 1
+  fi
+  if is_filesystem_root_path "${value}"; then
+    echo "[pingora-realpath-canary-disable] ${label} 不能是文件系统根目录。" >&2
+    exit 1
+  fi
+}
+
+validate_command_or_absolute_path() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" == */* ]]; then
+    require_absolute_path "${label}" "${value}"
+  fi
+}
+
+print_command() {
+  printf '+'
+  for arg in "$@"; do
+    printf ' %q' "${arg}"
+  done
+  printf '\n'
+}
+
+run_or_print() {
+  if [[ "${APPLY}" == "true" ]]; then
+    "$@"
+  else
+    print_command "$@"
+  fi
+}
+
+restore_previous() {
+  local backup_path="$1"
+  cp -p -- "${backup_path}" "${TARGET_PATH}"
+}
+
+rollback_after_failure() {
+  local backup_path="$1"
+  local reason="$2"
+  echo "[pingora-realpath-canary-disable] ${reason}，恢复删除前配置。" >&2
+  restore_previous "${backup_path}"
+  "${NGINX_BINARY}" -t >/dev/null 2>&1 || true
+  "${SYSTEMCTL_BINARY}" reload "${NGINX_SERVICE}" >/dev/null 2>&1 || true
+}
+
+reject_control_characters "--target-path" "${TARGET_PATH}"
+reject_control_characters "--nginx-binary" "${NGINX_BINARY}"
+reject_control_characters "--nginx-service" "${NGINX_SERVICE}"
+reject_control_characters "--systemctl-binary" "${SYSTEMCTL_BINARY}"
+require_absolute_path "--target-path" "${TARGET_PATH}"
+validate_command_or_absolute_path "--nginx-binary" "${NGINX_BINARY}"
+validate_command_or_absolute_path "--systemctl-binary" "${SYSTEMCTL_BINARY}"
+
+TARGET_DIR="$(dirname -- "${TARGET_PATH}")"
+if [[ "${APPLY}" == "true" && ( -L "${TARGET_DIR}" || -L "${TARGET_PATH}" ) ]]; then
+  echo "[pingora-realpath-canary-disable] 目标目录或目标文件不能是符号链接。" >&2
+  exit 1
+fi
+
+if [[ "${APPLY}" != "true" ]]; then
+  echo "[pingora-realpath-canary-disable] dry-run：将删除 realpath canary ${TARGET_PATH}。"
+  print_command rm -f -- "${TARGET_PATH}"
+  run_or_print "${NGINX_BINARY}" -t
+  run_or_print "${SYSTEMCTL_BINARY}" reload "${NGINX_SERVICE}"
+  exit 0
+fi
+
+if [[ ! -e "${TARGET_PATH}" ]]; then
+  echo "[pingora-realpath-canary-disable] 目标文件不存在，视为已关闭: ${TARGET_PATH}"
+  if [[ "${STATUS_AFTER}" == "true" ]]; then
+    "${SYSTEMCTL_BINARY}" is-active "${NGINX_SERVICE}"
+  fi
+  exit 0
+fi
+if [[ ! -f "${TARGET_PATH}" ]]; then
+  echo "[pingora-realpath-canary-disable] 目标存在但不是普通文件: ${TARGET_PATH}" >&2
+  exit 1
+fi
+
+backup_path="$(mktemp "${TARGET_DIR}/.genarrative-pingora-realpath-canary.disable.backup.XXXXXX")"
+trap 'rm -f -- "${backup_path}"' EXIT
+cp -p -- "${TARGET_PATH}" "${backup_path}"
+rm -f -- "${TARGET_PATH}"
+
+if ! "${NGINX_BINARY}" -t; then
+  rollback_after_failure "${backup_path}" "nginx -t 失败"
+  exit 1
+fi
+if ! "${SYSTEMCTL_BINARY}" reload "${NGINX_SERVICE}"; then
+  rollback_after_failure "${backup_path}" "reload ${NGINX_SERVICE} 失败"
+  exit 1
+fi
+
+if [[ "${STATUS_AFTER}" == "true" ]]; then
+  "${SYSTEMCTL_BINARY}" is-active "${NGINX_SERVICE}"
+fi
+
+echo "[pingora-realpath-canary-disable] 已关闭 realpath canary: ${TARGET_PATH}"
diff --git a/scripts/deploy/pingora-realpath-canary-enable.sh b/scripts/deploy/pingora-realpath-canary-enable.sh
new file mode 100644
index 000000000..dd22528f4
--- /dev/null
+++ b/scripts/deploy/pingora-realpath-canary-enable.sh
@@ -0,0 +1,350 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+REPO_ROOT="$(cd -- "${SCRIPT_DIR}/../.." >/dev/null 2>&1 && pwd)"
+
+TEMPLATE_PATH="${GENARRATIVE_PINGORA_REALPATH_CANARY_TEMPLATE_PATH:-${REPO_ROOT}/deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf}"
+TARGET_PATH="${GENARRATIVE_PINGORA_REALPATH_CANARY_TARGET_PATH:-/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf}"
+PROBE_TOKEN="${GENARRATIVE_PINGORA_REALPATH_CANARY_PROBE_TOKEN:-${GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN:-}}"
+BASE_URL="${GENARRATIVE_PINGORA_REALPATH_CANARY_BASE_URL:-http://127.0.0.1:18083}"
+HOST_HEADER="${GENARRATIVE_PINGORA_REALPATH_CANARY_HOST:-}"
+NGINX_BINARY="${GENARRATIVE_NGINX_BINARY:-nginx}"
+NGINX_SERVICE="${GENARRATIVE_NGINX_SERVICE:-nginx.service}"
+SYSTEMCTL_BINARY="${GENARRATIVE_SYSTEMCTL_BINARY:-systemctl}"
+LIVE_SCRIPT="${GENARRATIVE_PINGORA_REALPATH_CANARY_LIVE_SCRIPT:-${REPO_ROOT}/scripts/check-pingora-canary-live.mjs}"
+APPLY="false"
+RUN_LIVE="true"
+STATUS_AFTER="true"
+
+PLACEHOLDER="__GENARRATIVE_PINGORA_PROBE_TOKEN__"
+
+usage() {
+  cat <<'EOF'
+用法:
+  scripts/deploy/pingora-realpath-canary-enable.sh [--apply] [--probe-token <token>] [--host <host>] [--base-url <url>] [--template-path <path>] [--target-path <path>] [--nginx-binary <path|name>] [--nginx-service <unit>] [--systemctl-binary <path|name>] [--live-script <path>] [--skip-live] [--no-status]
+
+说明:
+  启用 Nginx -> Pingora 真实路径 canary。脚本会把随包
+  deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf 渲染到
+  /etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf。
+
+默认是 dry-run，只打印计划；必须显式传 --apply 才会写 Nginx 配置。
+--apply 会替换 probe token、写入目标文件、执行 nginx -t、reload nginx，
+然后运行 realpath canary live smoke。任一阶段失败都会恢复写入前的目标文件状态。
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --apply)
+      APPLY="true"
+      shift
+      ;;
+    --probe-token)
+      PROBE_TOKEN="${2:-}"
+      if [[ -z "${PROBE_TOKEN}" ]]; then
+        echo "[pingora-realpath-canary-enable] --probe-token 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --host)
+      HOST_HEADER="${2:-}"
+      if [[ -z "${HOST_HEADER}" ]]; then
+        echo "[pingora-realpath-canary-enable] --host 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --base-url)
+      BASE_URL="${2:-}"
+      if [[ -z "${BASE_URL}" ]]; then
+        echo "[pingora-realpath-canary-enable] --base-url 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --template-path)
+      TEMPLATE_PATH="${2:-}"
+      if [[ -z "${TEMPLATE_PATH}" ]]; then
+        echo "[pingora-realpath-canary-enable] --template-path 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --target-path)
+      TARGET_PATH="${2:-}"
+      if [[ -z "${TARGET_PATH}" ]]; then
+        echo "[pingora-realpath-canary-enable] --target-path 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-binary)
+      NGINX_BINARY="${2:-}"
+      if [[ -z "${NGINX_BINARY}" ]]; then
+        echo "[pingora-realpath-canary-enable] --nginx-binary 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --nginx-service)
+      NGINX_SERVICE="${2:-}"
+      if [[ -z "${NGINX_SERVICE}" ]]; then
+        echo "[pingora-realpath-canary-enable] --nginx-service 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --systemctl-binary)
+      SYSTEMCTL_BINARY="${2:-}"
+      if [[ -z "${SYSTEMCTL_BINARY}" ]]; then
+        echo "[pingora-realpath-canary-enable] --systemctl-binary 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --live-script)
+      LIVE_SCRIPT="${2:-}"
+      if [[ -z "${LIVE_SCRIPT}" ]]; then
+        echo "[pingora-realpath-canary-enable] --live-script 缺少参数" >&2
+        exit 1
+      fi
+      shift 2
+      ;;
+    --skip-live)
+      RUN_LIVE="false"
+      shift
+      ;;
+    --no-status)
+      STATUS_AFTER="false"
+      shift
+      ;;
+    *)
+      echo "[pingora-realpath-canary-enable] 未知参数: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+reject_control_characters() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" == *$'\n'* || "${value}" == *$'\r'* ]]; then
+    echo "[pingora-realpath-canary-enable] ${label} 不能包含换行或 NUL 字符。" >&2
+    exit 1
+  fi
+}
+
+is_filesystem_root_path() {
+  local value="$1"
+  local without_slashes="${value//\//}"
+  [[ -n "${value}" && -z "${without_slashes}" ]]
+}
+
+require_absolute_path() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" != /* ]]; then
+    echo "[pingora-realpath-canary-enable] ${label} 必须是绝对路径。" >&2
+    exit 1
+  fi
+  if is_filesystem_root_path "${value}"; then
+    echo "[pingora-realpath-canary-enable] ${label} 不能是文件系统根目录。" >&2
+    exit 1
+  fi
+}
+
+validate_command_or_absolute_path() {
+  local label="$1"
+  local value="$2"
+  if [[ "${value}" == */* ]]; then
+    require_absolute_path "${label}" "${value}"
+  fi
+}
+
+validate_host() {
+  local label="$1"
+  local value="$2"
+  if [[ -z "${value}" ]]; then
+    echo "[pingora-realpath-canary-enable] ${label} 必须提供。" >&2
+    exit 1
+  fi
+  if [[ "${value}" == http://* || "${value}" == https://* || "${value}" == */* || "${value}" == *\?* || "${value}" =~ [[:space:]] ]]; then
+    echo "[pingora-realpath-canary-enable] ${label} 必须是 Host 或 host:port，不能是 URL、路径、查询或包含空白。" >&2
+    exit 1
+  fi
+}
+
+validate_base_url() {
+  if [[ "${BASE_URL}" != http://* && "${BASE_URL}" != https://* ]]; then
+    echo "[pingora-realpath-canary-enable] --base-url 必须以 http:// 或 https:// 开头。" >&2
+    exit 1
+  fi
+}
+
+validate_probe_token() {
+  if [[ "${APPLY}" != "true" ]]; then
+    return
+  fi
+  if [[ -z "${PROBE_TOKEN}" ]]; then
+    echo "[pingora-realpath-canary-enable] --apply 必须提供 --probe-token 或 GENARRATIVE_PINGORA_REALPATH_CANARY_PROBE_TOKEN。" >&2
+    exit 1
+  fi
+  if [[ "${PROBE_TOKEN}" == "${PLACEHOLDER}" || "${#PROBE_TOKEN}" -lt 8 ]]; then
+    echo "[pingora-realpath-canary-enable] probe token 不能是占位值或过短。" >&2
+    exit 1
+  fi
+}
+
+escape_nginx_double_quoted() {
+  local value="$1"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  printf '%s' "${value}"
+}
+
+render_template_to() {
+  local output_path="$1"
+  local content escaped_token
+  content="$(<"${TEMPLATE_PATH}")"
+  escaped_token="$(escape_nginx_double_quoted "${PROBE_TOKEN}")"
+  printf '%s' "${content//${PLACEHOLDER}/${escaped_token}}" >"${output_path}"
+}
+
+print_command() {
+  printf '+'
+  for arg in "$@"; do
+    printf ' %q' "${arg}"
+  done
+  printf '\n'
+}
+
+run_or_print() {
+  if [[ "${APPLY}" == "true" ]]; then
+    "$@"
+  else
+    print_command "$@"
+  fi
+}
+
+restore_previous() {
+  local backup_path="$1"
+  local had_target="$2"
+  if [[ "${had_target}" == "true" ]]; then
+    cp -p -- "${backup_path}" "${TARGET_PATH}"
+  else
+    rm -f -- "${TARGET_PATH}"
+  fi
+}
+
+rollback_after_failure() {
+  local backup_path="$1"
+  local had_target="$2"
+  local reason="$3"
+  echo "[pingora-realpath-canary-enable] ${reason}，恢复写入前配置。" >&2
+  restore_previous "${backup_path}" "${had_target}"
+  "${NGINX_BINARY}" -t >/dev/null 2>&1 || true
+  "${SYSTEMCTL_BINARY}" reload "${NGINX_SERVICE}" >/dev/null 2>&1 || true
+}
+
+reject_control_characters "--template-path" "${TEMPLATE_PATH}"
+reject_control_characters "--target-path" "${TARGET_PATH}"
+reject_control_characters "--probe-token" "${PROBE_TOKEN}"
+reject_control_characters "--base-url" "${BASE_URL}"
+reject_control_characters "--host" "${HOST_HEADER}"
+reject_control_characters "--nginx-binary" "${NGINX_BINARY}"
+reject_control_characters "--nginx-service" "${NGINX_SERVICE}"
+reject_control_characters "--systemctl-binary" "${SYSTEMCTL_BINARY}"
+reject_control_characters "--live-script" "${LIVE_SCRIPT}"
+
+require_absolute_path "--template-path" "${TEMPLATE_PATH}"
+require_absolute_path "--target-path" "${TARGET_PATH}"
+if [[ "${RUN_LIVE}" == "true" ]]; then
+  require_absolute_path "--live-script" "${LIVE_SCRIPT}"
+fi
+validate_command_or_absolute_path "--nginx-binary" "${NGINX_BINARY}"
+validate_command_or_absolute_path "--systemctl-binary" "${SYSTEMCTL_BINARY}"
+validate_host "--host" "${HOST_HEADER}"
+validate_base_url
+validate_probe_token
+
+if [[ ! -f "${TEMPLATE_PATH}" ]]; then
+  echo "[pingora-realpath-canary-enable] 未找到 realpath canary 模板: ${TEMPLATE_PATH}" >&2
+  exit 1
+fi
+if [[ "${RUN_LIVE}" == "true" && ! -f "${LIVE_SCRIPT}" ]]; then
+  echo "[pingora-realpath-canary-enable] 未找到 realpath canary live smoke 脚本: ${LIVE_SCRIPT}" >&2
+  exit 1
+fi
+
+TARGET_DIR="$(dirname -- "${TARGET_PATH}")"
+if [[ "${APPLY}" == "true" ]]; then
+  if [[ ! -d "${TARGET_DIR}" ]]; then
+    echo "[pingora-realpath-canary-enable] 目标目录不存在: ${TARGET_DIR}" >&2
+    exit 1
+  fi
+  if [[ -L "${TARGET_DIR}" || -L "${TARGET_PATH}" ]]; then
+    echo "[pingora-realpath-canary-enable] 目标目录或目标文件不能是符号链接。" >&2
+    exit 1
+  fi
+fi
+
+if [[ "${APPLY}" != "true" ]]; then
+  echo "[pingora-realpath-canary-enable] dry-run：将渲染 realpath canary 到 ${TARGET_PATH}，probe token 输出已隐藏。"
+  print_command install -m 0644 "<rendered-realpath-canary>" "${TARGET_PATH}"
+  run_or_print "${NGINX_BINARY}" -t
+  run_or_print "${SYSTEMCTL_BINARY}" reload "${NGINX_SERVICE}"
+  if [[ "${RUN_LIVE}" == "true" ]]; then
+    run_or_print node -- "${LIVE_SCRIPT}" --realpath --base-url "${BASE_URL}" --host "${HOST_HEADER}"
+  fi
+  exit 0
+fi
+
+tmp_path="$(mktemp "${TARGET_DIR}/.genarrative-pingora-realpath-canary.XXXXXX")"
+backup_path="$(mktemp "${TARGET_DIR}/.genarrative-pingora-realpath-canary.backup.XXXXXX")"
+had_target="false"
+cleanup_paths=("${tmp_path}" "${backup_path}")
+trap 'rm -f -- "${cleanup_paths[@]}"' EXIT
+
+render_template_to "${tmp_path}"
+chmod 0644 "${tmp_path}"
+
+if [[ -e "${TARGET_PATH}" ]]; then
+  if [[ ! -f "${TARGET_PATH}" ]]; then
+    echo "[pingora-realpath-canary-enable] 目标已存在但不是普通文件: ${TARGET_PATH}" >&2
+    exit 1
+  fi
+  cp -p -- "${TARGET_PATH}" "${backup_path}"
+  had_target="true"
+fi
+
+install -m 0644 "${tmp_path}" "${TARGET_PATH}"
+if ! "${NGINX_BINARY}" -t; then
+  rollback_after_failure "${backup_path}" "${had_target}" "nginx -t 失败"
+  exit 1
+fi
+if ! "${SYSTEMCTL_BINARY}" reload "${NGINX_SERVICE}"; then
+  rollback_after_failure "${backup_path}" "${had_target}" "reload ${NGINX_SERVICE} 失败"
+  exit 1
+fi
+
+if [[ "${RUN_LIVE}" == "true" ]]; then
+  if ! node -- "${LIVE_SCRIPT}" --realpath --base-url "${BASE_URL}" --host "${HOST_HEADER}"; then
+    rollback_after_failure "${backup_path}" "${had_target}" "realpath canary live smoke 失败"
+    exit 1
+  fi
+fi
+
+if [[ "${STATUS_AFTER}" == "true" ]]; then
+  "${SYSTEMCTL_BINARY}" is-active "${NGINX_SERVICE}"
+fi
+
+echo "[pingora-realpath-canary-enable] 已启用 realpath canary: ${TARGET_PATH}"
diff --git a/scripts/deploy/pingora-tls-cert-sync.mjs b/scripts/deploy/pingora-tls-cert-sync.mjs
new file mode 100644
index 000000000..63533eea7
--- /dev/null
+++ b/scripts/deploy/pingora-tls-cert-sync.mjs
@@ -0,0 +1,480 @@
+#!/usr/bin/env node
+
+import { randomBytes } from 'node:crypto';
+import {
+  accessSync,
+  chmodSync,
+  chownSync,
+  constants,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { userInfo } from 'node:os';
+
+const DEFAULT_SERVICE_USER = 'genarrative';
+const DEFAULT_SERVICE_GROUP = 'genarrative';
+const DEFAULT_TARGET_USER = 'root';
+const DEFAULT_DIRECTORY_MODE = '0750';
+const DEFAULT_FILE_MODE = '0640';
+
+const config = parseArgs(process.argv.slice(2));
+const result = run();
+
+if (config.json) {
+  console.log(`${JSON.stringify(result, null, 2)}\n`);
+} else {
+  const mode = config.apply ? 'apply' : 'dry-run';
+  console.log(`[pingora-tls-cert-sync] ${mode} OK`);
+  console.log(`[pingora-tls-cert-sync] target=${result.target.directory}`);
+  for (const item of result.files) {
+    console.log(
+      `[pingora-tls-cert-sync] ${item.kind}: ${item.source.path} -> ${item.target.path}`,
+    );
+  }
+}
+
+function usage() {
+  console.log(`Usage:
+  node scripts/deploy/pingora-tls-cert-sync.mjs --source-cert-file <path> --source-key-file <path> --target-dir <path> [options]
+
+Options:
+  --source-cert-file <path>  已存在的证书链文件，通常是 Let's Encrypt live/fullchain.pem。
+  --source-key-file <path>   已存在的私钥文件，通常是 Let's Encrypt live/privkey.pem。
+  --target-dir <path>        Pingora 私有 TLS 目录，例如 /etc/genarrative/pingora-tls/<host>。
+  --service-user <user|uid>  目标服务用户，默认 genarrative。
+  --service-group <group|gid>
+                             目标文件组，默认 genarrative。
+  --target-user <user|uid>   目标文件 owner，默认 root。
+  --directory-mode <mode>    目标目录权限，默认 0750。
+  --file-mode <mode>         证书和私钥权限，默认 0640。
+  --apply                    执行复制；默认只做 dry-run 校验。
+  --json                     输出 JSON。
+
+该脚本只把现有证书复制到 Pingora 私有目录，不修改 Let's Encrypt / Certbot / Nginx 原始文件。
+源路径可以是 Certbot live symlink，但解析后的目标必须是普通文件；目标目录和目标文件不允许是 symlink。
+`);
+}
+
+function parseArgs(argv) {
+  const result = {
+    sourceCertFile:
+      process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_SOURCE_CERT_FILE || '',
+    sourceKeyFile:
+      process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_SOURCE_KEY_FILE || '',
+    targetDir: process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_TARGET_DIR || '',
+    serviceUser:
+      process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_SERVICE_USER ||
+      DEFAULT_SERVICE_USER,
+    serviceGroup:
+      process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_SERVICE_GROUP ||
+      DEFAULT_SERVICE_GROUP,
+    targetUser:
+      process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_TARGET_USER ||
+      DEFAULT_TARGET_USER,
+    directoryMode:
+      process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_DIRECTORY_MODE ||
+      DEFAULT_DIRECTORY_MODE,
+    fileMode:
+      process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_FILE_MODE ||
+      DEFAULT_FILE_MODE,
+    apply: readBoolEnv(
+      process.env.GENARRATIVE_PINGORA_TLS_CERT_SYNC_APPLY,
+      false,
+      'GENARRATIVE_PINGORA_TLS_CERT_SYNC_APPLY',
+    ),
+    json: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        usage();
+        process.exit(0);
+        break;
+      case '--source-cert-file':
+        result.sourceCertFile = requireValue(argv, ++index, arg);
+        break;
+      case '--source-key-file':
+        result.sourceKeyFile = requireValue(argv, ++index, arg);
+        break;
+      case '--target-dir':
+        result.targetDir = requireValue(argv, ++index, arg);
+        break;
+      case '--service-user':
+        result.serviceUser = requireValue(argv, ++index, arg);
+        break;
+      case '--service-group':
+        result.serviceGroup = requireValue(argv, ++index, arg);
+        break;
+      case '--target-user':
+        result.targetUser = requireValue(argv, ++index, arg);
+        break;
+      case '--directory-mode':
+        result.directoryMode = requireValue(argv, ++index, arg);
+        break;
+      case '--file-mode':
+        result.fileMode = requireValue(argv, ++index, arg);
+        break;
+      case '--apply':
+        result.apply = true;
+        break;
+      case '--json':
+        result.json = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  validateSafeAbsoluteFilePath(
+    result.sourceCertFile,
+    '--source-cert-file',
+  );
+  validateSafeAbsoluteFilePath(result.sourceKeyFile, '--source-key-file');
+  validateSafeAbsoluteDirectoryPath(result.targetDir, '--target-dir');
+  validateIdentity(result.serviceUser, '--service-user');
+  validateIdentity(result.serviceGroup, '--service-group');
+  validateIdentity(result.targetUser, '--target-user');
+  result.directoryModeNumber = parseMode(
+    result.directoryMode,
+    '--directory-mode',
+  );
+  result.fileModeNumber = parseMode(result.fileMode, '--file-mode');
+  if ((result.fileModeNumber & 0o007) !== 0) {
+    throw new Error('--file-mode 不能允许 other 读取证书或私钥。');
+  }
+  if ((result.directoryModeNumber & 0o007) !== 0) {
+    throw new Error('--directory-mode 不能允许 other 进入 TLS 私有目录。');
+  }
+  return result;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function readBoolEnv(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  validateNoControlCharacters(raw, label);
+  const normalized = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${label} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function validateSafeAbsoluteFilePath(value, label) {
+  validateNoControlCharacters(value, label);
+  if (!path.isAbsolute(value)) {
+    throw new Error(`${label} 必须是绝对路径。`);
+  }
+  if (isFilesystemRootPath(value)) {
+    throw new Error(`${label} 不能是文件系统根目录。`);
+  }
+}
+
+function validateSafeAbsoluteDirectoryPath(value, label) {
+  validateSafeAbsoluteFilePath(value, label);
+  if (path.basename(path.resolve(value)) === '..') {
+    throw new Error(`${label} 不能以 .. 结尾。`);
+  }
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function validateIdentity(value, label) {
+  validateNoControlCharacters(value, label);
+  if (!/^[A-Za-z0-9_.#-]+$/u.test(String(value))) {
+    throw new Error(`${label} 只能包含字母、数字、点、下划线、短横线或 #。`);
+  }
+}
+
+function parseMode(value, label) {
+  validateNoControlCharacters(value, label);
+  const text = String(value).trim();
+  if (!/^0?[0-7]{3}$/u.test(text)) {
+    throw new Error(`${label} 必须是三位八进制权限，例如 0640。`);
+  }
+  return Number.parseInt(text, 8);
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function run() {
+  const certSource = inspectSourceFile(
+    config.sourceCertFile,
+    '--source-cert-file',
+  );
+  const keySource = inspectSourceFile(config.sourceKeyFile, '--source-key-file');
+  const certTarget = path.join(config.targetDir, 'fullchain.pem');
+  const keyTarget = path.join(config.targetDir, 'privkey.pem');
+  const owner = config.apply
+    ? resolveOwner(config.targetUser, config.serviceGroup)
+    : { uid: null, gid: null };
+
+  assertNoSymlinkAncestors(config.targetDir, '--target-dir');
+  assertTargetPath(certTarget, '目标 fullchain.pem');
+  assertTargetPath(keyTarget, '目标 privkey.pem');
+  if (existsSync(config.targetDir)) {
+    assertTargetDirectory(config.targetDir);
+  }
+
+  const planned = {
+    mode: config.apply ? 'apply' : 'dry-run',
+    target: {
+      directory: config.targetDir,
+      user: config.targetUser,
+      group: config.serviceGroup,
+      uid: owner.uid,
+      gid: owner.gid,
+      serviceUser: config.serviceUser,
+      directoryMode: formatMode(config.directoryModeNumber),
+      fileMode: formatMode(config.fileModeNumber),
+    },
+    files: [
+      {
+        kind: 'cert',
+        source: certSource,
+        target: { path: certTarget },
+      },
+      {
+        kind: 'key',
+        source: keySource,
+        target: { path: keyTarget },
+      },
+    ],
+    serviceUserReadable: false,
+  };
+
+  if (!config.apply) {
+    return planned;
+  }
+
+  mkdirSync(config.targetDir, { recursive: true });
+  assertTargetDirectory(config.targetDir);
+  chmodSync(config.targetDir, config.directoryModeNumber);
+  applyOwner(config.targetDir, owner);
+
+  copyAtomic(certSource.resolvedPath, certTarget, owner);
+  copyAtomic(keySource.resolvedPath, keyTarget, owner);
+
+  planned.serviceUserReadable = assertServiceUserReadable(
+    config.serviceUser,
+    [certTarget, keyTarget],
+  );
+  return planned;
+}
+
+function inspectSourceFile(filePath, label) {
+  const linkStat = lstatSync(filePath);
+  const sourceIsSymlink = linkStat.isSymbolicLink();
+  const resolvedPath = realpathSync(filePath);
+  const fileStat = statSync(resolvedPath);
+  if (!fileStat.isFile()) {
+    throw new Error(`${label} 解析后必须是普通文件: ${resolvedPath}`);
+  }
+  return {
+    path: filePath,
+    resolvedPath,
+    sourceIsSymlink,
+    sizeBytes: fileStat.size,
+  };
+}
+
+function assertTargetDirectory(directory) {
+  const linkStat = lstatSync(directory);
+  if (linkStat.isSymbolicLink()) {
+    throw new Error(`--target-dir 不能是符号链接: ${directory}`);
+  }
+  if (!linkStat.isDirectory()) {
+    throw new Error(`--target-dir 已存在但不是目录: ${directory}`);
+  }
+}
+
+function assertNoSymlinkAncestors(targetDir, label) {
+  const resolved = path.resolve(targetDir);
+  const parsed = path.parse(resolved);
+  let current = parsed.root;
+  for (const part of resolved.slice(parsed.root.length).split(path.sep)) {
+    if (!part) {
+      continue;
+    }
+    current = path.join(current, part);
+    if (!existsSync(current)) {
+      break;
+    }
+    const linkStat = lstatSync(current);
+    if (linkStat.isSymbolicLink()) {
+      throw new Error(`${label} 已存在路径不能包含符号链接: ${current}`);
+    }
+    if (!linkStat.isDirectory()) {
+      throw new Error(`${label} 已存在父路径不是目录: ${current}`);
+    }
+  }
+}
+
+function assertTargetPath(filePath, label) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  const linkStat = lstatSync(filePath);
+  if (linkStat.isSymbolicLink()) {
+    throw new Error(`${label} 不能是符号链接: ${filePath}`);
+  }
+  if (!linkStat.isFile()) {
+    throw new Error(`${label} 已存在但不是普通文件: ${filePath}`);
+  }
+}
+
+function resolveOwner(user, group) {
+  const current = currentIdentity();
+  const uid = resolveUserId(user, current);
+  const gid = resolveGroupId(group, current, user);
+  if (!isCurrentUserRoot()) {
+    if (uid !== current.uid || gid !== current.gid) {
+      throw new Error(
+        `当前用户不是 root，不能把证书授权给 ${user}:${group}；请用 sudo -n 执行 --apply。`,
+      );
+    }
+  }
+  return { uid, gid };
+}
+
+function resolveUserId(user, current) {
+  if (/^#?\d+$/u.test(user)) {
+    return Number.parseInt(user.replace(/^#/u, ''), 10);
+  }
+  if (user === current.username) {
+    return current.uid;
+  }
+  return Number.parseInt(
+    execFileSync('id', ['-u', user], { encoding: 'utf8' }).trim(),
+    10,
+  );
+}
+
+function resolveGroupId(group, current, user) {
+  if (/^#?\d+$/u.test(group)) {
+    return Number.parseInt(group.replace(/^#/u, ''), 10);
+  }
+  if (group === current.groupname || group === String(current.gid)) {
+    return current.gid;
+  }
+  const getent = spawnSync('getent', ['group', group], { encoding: 'utf8' });
+  if (getent.status === 0 && getent.stdout.trim()) {
+    const parts = getent.stdout.trim().split(':');
+    return Number.parseInt(parts[2], 10);
+  }
+  if (group === user) {
+    return Number.parseInt(
+      execFileSync('id', ['-g', user], { encoding: 'utf8' }).trim(),
+      10,
+    );
+  }
+  throw new Error(`无法解析服务组: ${group}`);
+}
+
+function currentIdentity() {
+  const uid = typeof process.getuid === 'function' ? process.getuid() : -1;
+  const gid = typeof process.getgid === 'function' ? process.getgid() : -1;
+  let username = '';
+  try {
+    username = userInfo().username;
+  } catch {
+    username = process.env.USER || process.env.LOGNAME || '';
+  }
+  return {
+    uid,
+    gid,
+    username,
+    groupname: '',
+  };
+}
+
+function isCurrentUserRoot() {
+  return typeof process.getuid === 'function' && process.getuid() === 0;
+}
+
+function applyOwner(filePath, owner) {
+  const current = currentIdentity();
+  if (!isCurrentUserRoot() && owner.uid === current.uid && owner.gid === current.gid) {
+    return;
+  }
+  chownSync(filePath, owner.uid, owner.gid);
+}
+
+function copyAtomic(sourcePath, targetPath, owner) {
+  const tempPath = path.join(
+    path.dirname(targetPath),
+    `.${path.basename(targetPath)}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`,
+  );
+  try {
+    copyFileSync(sourcePath, tempPath, constants.COPYFILE_EXCL);
+    chmodSync(tempPath, config.fileModeNumber);
+    applyOwner(tempPath, owner);
+    renameSync(tempPath, targetPath);
+    chmodSync(targetPath, config.fileModeNumber);
+    applyOwner(targetPath, owner);
+  } catch (error) {
+    rmSync(tempPath, { force: true });
+    throw error;
+  }
+}
+
+function assertServiceUserReadable(serviceUser, files) {
+  if (/^#?\d+$/u.test(serviceUser)) {
+    for (const file of files) {
+      accessSync(file, constants.R_OK);
+    }
+    return true;
+  }
+  const current = currentIdentity();
+  if (serviceUser === current.username && !isCurrentUserRoot()) {
+    for (const file of files) {
+      accessSync(file, constants.R_OK);
+    }
+    return true;
+  }
+  for (const file of files) {
+    const check = spawnSync('sudo', ['-n', '-u', serviceUser, 'test', '-r', file], {
+      encoding: 'utf8',
+    });
+    if (check.status !== 0) {
+      const detail = (check.stderr || check.stdout || '').trim();
+      throw new Error(
+        `服务用户 ${serviceUser} 不可读: ${file}${detail ? ` (${detail})` : ''}`,
+      );
+    }
+  }
+  return true;
+}
+
+function formatMode(mode) {
+  return `0${mode.toString(8).padStart(3, '0')}`;
+}
diff --git a/scripts/deploy/production-api-deploy.sh b/scripts/deploy/production-api-deploy.sh
index e215b3e90..851d897a2 100644
--- a/scripts/deploy/production-api-deploy.sh
+++ b/scripts/deploy/production-api-deploy.sh
@@ -5,12 +5,13 @@ set -euo pipefail
 usage() {
   cat <<'EOF'
 用法:
-  ./scripts/deploy/production-api-deploy.sh --source-dir build/<version> [--version <version>] [--release-root /opt/genarrative/releases] [--current-link /opt/genarrative/current] [--service genarrative-api.service] [--worker-service-pattern 'genarrative-external-generation-worker@*.service'] [--no-worker-services] [--worker-controller-service genarrative-external-generation-controller.service] [--no-worker-controller] [--health-url http://127.0.0.1:8082/readyz] [--api-env-file /etc/genarrative/api-server.env] [--database genarrative-prod] [--spacetime-server-url http://127.0.0.1:3101]
+  ./scripts/deploy/production-api-deploy.sh --source-dir build/<version> [--version <version>] [--release-root /opt/genarrative/releases] [--current-link /opt/genarrative/current] [--service genarrative-api.service] [--pingora-service genarrative-pingora-gateway.service] [--worker-service-pattern 'genarrative-external-generation-worker@*.service'] [--no-worker-services] [--worker-controller-service genarrative-external-generation-controller.service] [--no-worker-controller] [--health-url http://127.0.0.1:8082/readyz] [--api-env-file /etc/genarrative/api-server.env] [--database genarrative-prod] [--spacetime-server-url http://127.0.0.1:3101]
 
 说明:
   进入维护模式，校验并发布 api-server 单文件，更新 current 链接，重启 systemd 服务并执行 readiness 检查。
   默认同时重启外部生成 worker controller 和已加载的 worker 实例；未启用 worker 单元时会自动跳过。
   若传入 --database，会在重启前把 GENARRATIVE_SPACETIME_DATABASE 写入 api-server 环境文件，避免服务继续读取旧库。
+  若发布包包含 pingora-gateway，部署脚本会在 current 链接切换后先复核 systemd/env 仍是本机高端口 shadow 配置，再启动或重启 Pingora 影子服务并复核 active。
   失败时保留维护模式。
 EOF
 }
@@ -25,6 +26,16 @@ require_argument() {
   fi
 }
 
+require_absolute_path() {
+  local value="$1"
+  local label="$2"
+
+  if [[ ! "${value}" = /* ]]; then
+    echo "[production-api-deploy] ${label} 必须使用绝对路径: ${value}" >&2
+    exit 1
+  fi
+}
+
 validate_spacetime_database_name() {
   local database="$1"
 
@@ -224,6 +235,144 @@ ensure_runtime_env_and_dirs() {
   fi
 }
 
+extract_pingora_env_files_from_unit() {
+  local service_name="$1"
+  local unit_content
+
+  if ! unit_content="$(systemctl cat "${service_name}")"; then
+    echo "[production-api-deploy] 无法读取 Pingora systemd 最终配置: ${service_name}" >&2
+    exit 1
+  fi
+
+  if printf "%s\n" "${unit_content}" | grep -Eq '^[[:space:]]*(AmbientCapabilities|CapabilityBoundingSet)=.*CAP_NET_BIND_SERVICE'; then
+    echo "[production-api-deploy] Pingora systemd 已包含 CAP_NET_BIND_SERVICE，疑似直连入口配置；API deploy 不会自动启动或重启直连服务: ${service_name}" >&2
+    exit 1
+  fi
+
+  printf "%s\n" "${unit_content}" | while IFS= read -r raw_line; do
+    local line value token env_file
+    line="${raw_line#"${raw_line%%[![:space:]]*}"}"
+    [[ "${line}" == EnvironmentFile=* ]] || continue
+    value="${line#EnvironmentFile=}"
+    for token in ${value}; do
+      env_file="${token#-}"
+      env_file="${env_file%\"}"
+      env_file="${env_file#\"}"
+      env_file="${env_file%\'}"
+      env_file="${env_file#\'}"
+      [[ -n "${env_file}" ]] && printf "%s\n" "${env_file}"
+    done
+  done
+}
+
+find_pingora_gateway_env_file() {
+  local service_name="$1"
+  local env_file listen
+
+  while IFS= read -r env_file; do
+    if [[ "${env_file}" != /* ]]; then
+      echo "[production-api-deploy] Pingora EnvironmentFile 必须使用绝对路径: ${env_file}" >&2
+      exit 1
+    fi
+    listen="$(read_env_value "${env_file}" "GENARRATIVE_PINGORA_GATEWAY_LISTEN")"
+    if [[ -n "${listen}" ]]; then
+      printf "%s\n" "${env_file}"
+      return
+    fi
+  done < <(extract_pingora_env_files_from_unit "${service_name}")
+
+  echo "[production-api-deploy] Pingora systemd 配置缺少包含 GENARRATIVE_PINGORA_GATEWAY_LISTEN 的 EnvironmentFile: ${service_name}" >&2
+  exit 1
+}
+
+require_pingora_shadow_env() {
+  local env_file="$1"
+  local listen tls_listen redirect_listen
+
+  listen="$(read_env_value "${env_file}" "GENARRATIVE_PINGORA_GATEWAY_LISTEN")"
+  tls_listen="$(read_env_value "${env_file}" "GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN")"
+  redirect_listen="$(read_env_value "${env_file}" "GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN")"
+
+  if [[ "${listen}" != "127.0.0.1:18081" ]]; then
+    echo "[production-api-deploy] Pingora 自动启动只允许 shadow 监听 127.0.0.1:18081，当前 GENARRATIVE_PINGORA_GATEWAY_LISTEN=${listen:-<empty>}" >&2
+    exit 1
+  fi
+  if [[ -n "${tls_listen}" ]]; then
+    echo "[production-api-deploy] Pingora 自动启动不允许启用 TLS_LISTEN，当前 GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${tls_listen}" >&2
+    exit 1
+  fi
+  if [[ -n "${redirect_listen}" ]]; then
+    echo "[production-api-deploy] Pingora 自动启动不允许启用 HTTP_REDIRECT_LISTEN，当前 GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${redirect_listen}" >&2
+    exit 1
+  fi
+}
+
+check_pingora_shadow_service_config() {
+  local service_name="$1"
+  local env_file
+
+  env_file="$(find_pingora_gateway_env_file "${service_name}")"
+  require_pingora_shadow_env "${env_file}"
+  printf "%s\n" "${env_file}"
+}
+
+ensure_pingora_shadow_service() {
+  local service_name="$1"
+  local env_file="${2:-}"
+
+  if [[ -z "${env_file}" ]]; then
+    env_file="$(check_pingora_shadow_service_config "${service_name}")"
+  else
+    require_pingora_shadow_env "${env_file}"
+  fi
+
+  echo "[production-api-deploy] 发布包包含 Pingora，启动或重启 shadow 影子服务: ${service_name} (${env_file})"
+  systemctl restart "${service_name}"
+  if ! systemctl is-active --quiet "${service_name}"; then
+    echo "[production-api-deploy] Pingora shadow 影子服务启动或重启后不是 active: ${service_name}" >&2
+    exit 1
+  fi
+}
+
+validate_release_manifest() {
+  local manifest_path="$1"
+  local require_pingora="$2"
+
+  if [[ ! -f "${manifest_path}" ]]; then
+    echo "[production-api-deploy] 发布产物缺少 release-manifest.json: ${manifest_path}" >&2
+    exit 1
+  fi
+
+  node - "${manifest_path}" "${require_pingora}" <<'NODE'
+const fs = require('fs');
+
+const manifestPath = process.argv[2];
+const requirePingora = process.argv[3] === '1';
+let manifest;
+try {
+  manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+} catch (error) {
+  console.error(`[production-api-deploy] release-manifest.json 不是合法 JSON: ${error.message}`);
+  process.exit(1);
+}
+
+const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+const hasApiServer = artifacts.some((artifact) => artifact?.path === 'api-server');
+if (!hasApiServer) {
+  console.error('[production-api-deploy] release-manifest.json 缺少 api-server artifact。');
+  process.exit(1);
+}
+
+if (requirePingora) {
+  const hasPingora = artifacts.some((artifact) => artifact?.path === 'pingora-gateway');
+  if (!hasPingora) {
+    console.error('[production-api-deploy] release-manifest.json 缺少 pingora-gateway artifact。');
+    process.exit(1);
+  }
+}
+NODE
+}
+
 list_worker_services() {
   local pattern="$1"
 
@@ -360,6 +509,7 @@ VERSION=""
 RELEASE_ROOT="/opt/genarrative/releases"
 CURRENT_LINK="/opt/genarrative/current"
 SERVICE_NAME="genarrative-api.service"
+PINGORA_SERVICE_NAME="genarrative-pingora-gateway.service"
 WORKER_SERVICE_PATTERN="genarrative-external-generation-worker@*.service"
 WORKER_CONTROLLER_SERVICE="genarrative-external-generation-controller.service"
 HEALTH_URL="http://127.0.0.1:8082/readyz"
@@ -367,6 +517,9 @@ API_ENV_FILE="/etc/genarrative/api-server.env"
 DATABASE=""
 SPACETIME_SERVER_URL=""
 DEPLOY_COMPLETED=0
+PINGORA_INCLUDED=0
+RELEASE_DIR=""
+STAGING_RELEASE_DIR=""
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -394,6 +547,10 @@ while [[ $# -gt 0 ]]; do
       SERVICE_NAME="${2:?缺少 --service 的值}"
       shift 2
       ;;
+    --pingora-service)
+      PINGORA_SERVICE_NAME="${2:?缺少 --pingora-service 的值}"
+      shift 2
+      ;;
     --worker-service-pattern)
       WORKER_SERVICE_PATTERN="${2:?缺少 --worker-service-pattern 的值}"
       shift 2
@@ -435,6 +592,9 @@ while [[ $# -gt 0 ]]; do
 done
 
 require_argument "${SOURCE_DIR}" "--source-dir"
+require_absolute_path "${RELEASE_ROOT}" "--release-root"
+require_absolute_path "${CURRENT_LINK}" "--current-link"
+require_absolute_path "${API_ENV_FILE}" "--api-env-file"
 
 if [[ -n "${DATABASE}" ]]; then
   validate_spacetime_database_name "${DATABASE}"
@@ -448,8 +608,13 @@ fi
 SOURCE_DIR="$(cd "${SOURCE_DIR}" && pwd)"
 VERSION="${VERSION:-$(basename "${SOURCE_DIR}")}"
 
-if [[ ! "${VERSION}" =~ ^[0-9A-Za-z._-]+$ ]]; then
-  echo "[production-api-deploy] --version 只能包含数字、字母、点、下划线和短横线: ${VERSION}" >&2
+if [[ ! "${VERSION}" =~ ^[0-9A-Za-z][0-9A-Za-z._-]*$ ]]; then
+  echo "[production-api-deploy] --version 必须以数字或字母开头，且只能包含数字、字母、点、下划线和短横线: ${VERSION}" >&2
+  exit 1
+fi
+
+if [[ "${VERSION}" == "." || "${VERSION}" == ".." ]]; then
+  echo "[production-api-deploy] --version 不能是点目录: ${VERSION}" >&2
   exit 1
 fi
 
@@ -458,9 +623,34 @@ if [[ ! -f "${SOURCE_DIR}/api-server" || ! -f "${SOURCE_DIR}/api-server.sha256"
   exit 1
 fi
 
+RELEASE_DIR="${RELEASE_ROOT}/${VERSION}"
+STAGING_RELEASE_DIR="${RELEASE_ROOT}/.${VERSION}.staging.$$"
+
+if [[ -e "${RELEASE_DIR}" ]]; then
+  echo "[production-api-deploy] 目标 release 已存在，拒绝覆盖或合并旧文件: ${RELEASE_DIR}" >&2
+  exit 1
+fi
+
+if [[ -e "${STAGING_RELEASE_DIR}" ]]; then
+  echo "[production-api-deploy] 临时 staging release 已存在: ${STAGING_RELEASE_DIR}" >&2
+  exit 1
+fi
+
+if [[ -e "${CURRENT_LINK}" && ! -L "${CURRENT_LINK}" ]]; then
+  echo "[production-api-deploy] current 链接路径已存在但不是符号链接，拒绝覆盖: ${CURRENT_LINK}" >&2
+  exit 1
+fi
+
+cleanup_staging_release() {
+  if [[ -n "${STAGING_RELEASE_DIR:-}" && -d "${STAGING_RELEASE_DIR}" ]]; then
+    rm -rf "${STAGING_RELEASE_DIR}"
+  fi
+}
+
 on_exit() {
   local exit_code=$?
   if [[ "${exit_code}" -ne 0 && "${DEPLOY_COMPLETED}" -ne 1 ]]; then
+    cleanup_staging_release
     echo "[production-api-deploy] 部署失败，保持维护模式。" >&2
   fi
   exit "${exit_code}"
@@ -468,52 +658,225 @@ on_exit() {
 
 trap on_exit EXIT
 
-"${SCRIPT_DIR}/maintenance-on.sh" "api deploy ${VERSION}"
+bash "${SCRIPT_DIR}/maintenance-on.sh" "api deploy ${VERSION}"
 
 echo "[production-api-deploy] 校验 api-server"
 (
   cd "${SOURCE_DIR}"
   sha256sum -c api-server.sha256
+  if [[ -f pingora-gateway || -f pingora-gateway.sha256 ]]; then
+    if [[ ! -f pingora-gateway || ! -f pingora-gateway.sha256 ]]; then
+      echo "[production-api-deploy] pingora-gateway 与 pingora-gateway.sha256 必须同时存在。" >&2
+      exit 1
+    fi
+    sha256sum -c pingora-gateway.sha256
+  fi
 )
+if [[ -f "${SOURCE_DIR}/pingora-gateway" ]]; then
+  PINGORA_INCLUDED=1
+fi
+validate_release_manifest "${SOURCE_DIR}/release-manifest.json" "${PINGORA_INCLUDED}"
 
-RELEASE_DIR="${RELEASE_ROOT}/${VERSION}"
-mkdir -p "${RELEASE_DIR}"
-cp "${SOURCE_DIR}/api-server" "${RELEASE_DIR}/api-server"
-chmod +x "${RELEASE_DIR}/api-server"
+mkdir -p "${RELEASE_ROOT}"
+mkdir "${STAGING_RELEASE_DIR}"
+RELEASE_CONTENT_DIR="${STAGING_RELEASE_DIR}"
+cp "${SOURCE_DIR}/api-server" "${RELEASE_CONTENT_DIR}/api-server"
+cp "${SOURCE_DIR}/api-server.sha256" "${RELEASE_CONTENT_DIR}/api-server.sha256"
+chmod +x "${RELEASE_CONTENT_DIR}/api-server"
+if [[ -f "${SOURCE_DIR}/pingora-gateway" ]]; then
+  cp "${SOURCE_DIR}/pingora-gateway" "${RELEASE_CONTENT_DIR}/pingora-gateway"
+  cp "${SOURCE_DIR}/pingora-gateway.sha256" "${RELEASE_CONTENT_DIR}/pingora-gateway.sha256"
+  chmod +x "${RELEASE_CONTENT_DIR}/pingora-gateway"
+  echo "[production-api-deploy] 已复制 Pingora 影子网关；current 链接切换后将复核 shadow 配置并启动或重启 ${PINGORA_SERVICE_NAME}"
+fi
 
 BACKUP_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"
-WORKSPACE_BACKUP_SCRIPT_SOURCE="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts/database-backup-to-oss.mjs"
 HEALTH_PATROL_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/production-health-patrol.mjs"
-WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts/ops/production-health-patrol.mjs"
-mkdir -p "${RELEASE_DIR}/scripts" "${RELEASE_DIR}/scripts/ops"
+PINGORA_CURRENT_RELEASE_AUDIT_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/pingora-current-release-audit.mjs"
+PINGORA_DIRECT_REHEARSAL_STATUS_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/pingora-direct-rehearsal-status.mjs"
+PINGORA_CUTOVER_STATUS_SNAPSHOT_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/pingora-cutover-status-snapshot.mjs"
+PINGORA_CUTOVER_EVIDENCE_BUNDLE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/pingora-cutover-evidence-bundle.mjs"
+PINGORA_CUTOVER_COMMAND_EVIDENCE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/pingora-cutover-command-evidence.mjs"
+PINGORA_CUTOVER_EVIDENCE_VERIFY_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/pingora-cutover-evidence-verify.mjs"
+PINGORA_CUTOVER_EVIDENCE_AUDIT_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/pingora-cutover-evidence-audit.mjs"
+HEALTH_PATROL_ENV_CHECK_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/check-production-health-patrol-env.mjs"
+PINGORA_RELEASE_READINESS_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/check-pingora-release-readiness.mjs"
+PINGORA_ENABLE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-direct-enable.sh"
+PINGORA_ROLLBACK_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-direct-rollback.sh"
+PINGORA_REALPATH_CANARY_ENABLE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh"
+PINGORA_REALPATH_CANARY_DISABLE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh"
+PINGORA_HEALTH_PATROL_ENV_SWITCH_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
+PINGORA_GATEWAY_ENV_SHADOW_SWITCH_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
+PINGORA_TLS_CERT_SYNC_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs"
+PINGORA_PREFLIGHT_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/check-pingora-direct-preflight.mjs"
+PINGORA_LIVE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/check-pingora-direct-live.mjs"
+PINGORA_CANARY_LIVE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/check-pingora-canary-live.mjs"
+PINGORA_CANARY_ACCESS_LOG_PARITY_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/check-pingora-canary-access-log-parity.mjs"
+PINGORA_DEPLOY_DIR_SOURCE="${SOURCE_DIR}/deploy/pingora"
+SYSTEMD_DEPLOY_DIR_SOURCE="${SOURCE_DIR}/deploy/systemd"
+NGINX_DEPLOY_DIR_SOURCE="${SOURCE_DIR}/deploy/nginx"
+ENV_DEPLOY_DIR_SOURCE="${SOURCE_DIR}/deploy/env"
+mkdir -p "${RELEASE_CONTENT_DIR}/scripts" "${RELEASE_CONTENT_DIR}/scripts/deploy" "${RELEASE_CONTENT_DIR}/scripts/ops" "${RELEASE_CONTENT_DIR}/deploy"
 if [[ ! -f "${BACKUP_SCRIPT_SOURCE}" ]]; then
-  if [[ -f "${WORKSPACE_BACKUP_SCRIPT_SOURCE}" ]]; then
-    echo "[production-api-deploy] 发布产物缺少 scripts/database-backup-to-oss.mjs，回退使用部署工作区脚本；请重新触发包含该脚本的 API 构建。" >&2
-    BACKUP_SCRIPT_SOURCE="${WORKSPACE_BACKUP_SCRIPT_SOURCE}"
-  else
-    echo "[production-api-deploy] 缺少数据库备份脚本: ${SOURCE_DIR}/scripts/database-backup-to-oss.mjs" >&2
-    exit 1
-  fi
+  echo "[production-api-deploy] 发布产物缺少数据库备份脚本: ${SOURCE_DIR}/scripts/database-backup-to-oss.mjs" >&2
+  exit 1
 fi
-cp "${BACKUP_SCRIPT_SOURCE}" "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
-chmod 0644 "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
+cp "${BACKUP_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/database-backup-to-oss.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/database-backup-to-oss.mjs"
 if [[ ! -f "${HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
-  if [[ -f "${WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
-    echo "[production-api-deploy] 发布产物缺少 scripts/ops/production-health-patrol.mjs，回退使用部署工作区脚本；请重新触发包含该脚本的 API 构建。" >&2
-    HEALTH_PATROL_SCRIPT_SOURCE="${WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE}"
-  else
-    echo "[production-api-deploy] 未找到生产健康巡检脚本，跳过复制；genarrative-health-patrol.service 会因脚本缺失而跳过执行。" >&2
-    HEALTH_PATROL_SCRIPT_SOURCE=""
-  fi
+  echo "[production-api-deploy] 发布产物缺少生产健康巡检脚本: ${SOURCE_DIR}/scripts/ops/production-health-patrol.mjs" >&2
+  exit 1
 fi
-if [[ -n "${HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
-  cp "${HEALTH_PATROL_SCRIPT_SOURCE}" "${RELEASE_DIR}/scripts/ops/production-health-patrol.mjs"
-  chmod 0644 "${RELEASE_DIR}/scripts/ops/production-health-patrol.mjs"
+cp "${HEALTH_PATROL_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/ops/production-health-patrol.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/ops/production-health-patrol.mjs"
+if [[ ! -f "${PINGORA_CURRENT_RELEASE_AUDIT_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora current release 自审脚本: ${SOURCE_DIR}/scripts/ops/pingora-current-release-audit.mjs" >&2
+  exit 1
 fi
+cp "${PINGORA_CURRENT_RELEASE_AUDIT_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-current-release-audit.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-current-release-audit.mjs"
+if [[ ! -f "${PINGORA_DIRECT_REHEARSAL_STATUS_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连彩排状态脚本: ${SOURCE_DIR}/scripts/ops/pingora-direct-rehearsal-status.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_DIRECT_REHEARSAL_STATUS_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-direct-rehearsal-status.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-direct-rehearsal-status.mjs"
+if [[ ! -f "${PINGORA_CUTOVER_STATUS_SNAPSHOT_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连切换状态快照脚本: ${SOURCE_DIR}/scripts/ops/pingora-cutover-status-snapshot.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_CUTOVER_STATUS_SNAPSHOT_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-status-snapshot.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-status-snapshot.mjs"
+if [[ ! -f "${PINGORA_CUTOVER_EVIDENCE_BUNDLE_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连切换证据包脚本: ${SOURCE_DIR}/scripts/ops/pingora-cutover-evidence-bundle.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_CUTOVER_EVIDENCE_BUNDLE_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-evidence-bundle.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-evidence-bundle.mjs"
+if [[ ! -f "${PINGORA_CUTOVER_COMMAND_EVIDENCE_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连切换命令证据脚本: ${SOURCE_DIR}/scripts/ops/pingora-cutover-command-evidence.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_CUTOVER_COMMAND_EVIDENCE_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-command-evidence.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-command-evidence.mjs"
+if [[ ! -f "${PINGORA_CUTOVER_EVIDENCE_VERIFY_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连切换证据验真脚本: ${SOURCE_DIR}/scripts/ops/pingora-cutover-evidence-verify.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_CUTOVER_EVIDENCE_VERIFY_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-evidence-verify.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-evidence-verify.mjs"
+if [[ ! -f "${PINGORA_CUTOVER_EVIDENCE_AUDIT_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连切换证据根目录审计脚本: ${SOURCE_DIR}/scripts/ops/pingora-cutover-evidence-audit.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_CUTOVER_EVIDENCE_AUDIT_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-evidence-audit.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/ops/pingora-cutover-evidence-audit.mjs"
+if [[ ! -f "${HEALTH_PATROL_ENV_CHECK_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少生产健康巡检 env 复核脚本: ${SOURCE_DIR}/scripts/check-production-health-patrol-env.mjs" >&2
+  exit 1
+fi
+cp "${HEALTH_PATROL_ENV_CHECK_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/check-production-health-patrol-env.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/check-production-health-patrol-env.mjs"
+if [[ ! -f "${PINGORA_RELEASE_READINESS_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora release readiness 聚合门禁脚本: ${SOURCE_DIR}/scripts/check-pingora-release-readiness.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_RELEASE_READINESS_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/check-pingora-release-readiness.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/check-pingora-release-readiness.mjs"
+if [[ ! -f "${PINGORA_ENABLE_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连启用脚本: ${SOURCE_DIR}/scripts/deploy/pingora-direct-enable.sh" >&2
+  exit 1
+fi
+cp "${PINGORA_ENABLE_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-direct-enable.sh"
+chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-direct-enable.sh"
+if [[ ! -f "${PINGORA_ROLLBACK_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连回退脚本: ${SOURCE_DIR}/scripts/deploy/pingora-direct-rollback.sh" >&2
+  exit 1
+fi
+cp "${PINGORA_ROLLBACK_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-direct-rollback.sh"
+chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-direct-rollback.sh"
+if [[ ! -f "${PINGORA_REALPATH_CANARY_ENABLE_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora realpath canary 启用脚本: ${SOURCE_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh" >&2
+  exit 1
+fi
+cp "${PINGORA_REALPATH_CANARY_ENABLE_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh"
+chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh"
+if [[ ! -f "${PINGORA_REALPATH_CANARY_DISABLE_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora realpath canary 关闭脚本: ${SOURCE_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh" >&2
+  exit 1
+fi
+cp "${PINGORA_REALPATH_CANARY_DISABLE_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh"
+chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh"
+if [[ ! -f "${PINGORA_HEALTH_PATROL_ENV_SWITCH_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora health patrol env 切换脚本: ${SOURCE_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_HEALTH_PATROL_ENV_SWITCH_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
+chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
+if [[ ! -f "${PINGORA_GATEWAY_ENV_SHADOW_SWITCH_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora gateway env shadow 切换脚本: ${SOURCE_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_GATEWAY_ENV_SHADOW_SWITCH_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
+chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
+if [[ ! -f "${PINGORA_TLS_CERT_SYNC_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora TLS 证书同步脚本: ${SOURCE_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_TLS_CERT_SYNC_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs"
+chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs"
+if [[ ! -f "${PINGORA_PREFLIGHT_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连预检脚本: ${SOURCE_DIR}/scripts/check-pingora-direct-preflight.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_PREFLIGHT_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/check-pingora-direct-preflight.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/check-pingora-direct-preflight.mjs"
+if [[ ! -f "${PINGORA_LIVE_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 直连 live smoke 脚本: ${SOURCE_DIR}/scripts/check-pingora-direct-live.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_LIVE_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/check-pingora-direct-live.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/check-pingora-direct-live.mjs"
+if [[ ! -f "${PINGORA_CANARY_LIVE_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora canary live smoke 脚本: ${SOURCE_DIR}/scripts/check-pingora-canary-live.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_CANARY_LIVE_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/check-pingora-canary-live.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/check-pingora-canary-live.mjs"
+if [[ ! -f "${PINGORA_CANARY_ACCESS_LOG_PARITY_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora canary access log 对账脚本: ${SOURCE_DIR}/scripts/check-pingora-canary-access-log-parity.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_CANARY_ACCESS_LOG_PARITY_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/check-pingora-canary-access-log-parity.mjs"
+chmod 0644 "${RELEASE_CONTENT_DIR}/scripts/check-pingora-canary-access-log-parity.mjs"
+if [[ ! -d "${PINGORA_DEPLOY_DIR_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora 配置目录: ${SOURCE_DIR}/deploy/pingora" >&2
+  exit 1
+fi
+rm -rf "${RELEASE_CONTENT_DIR}/deploy/pingora"
+cp -R "${PINGORA_DEPLOY_DIR_SOURCE}" "${RELEASE_CONTENT_DIR}/deploy/pingora"
+if [[ ! -d "${SYSTEMD_DEPLOY_DIR_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 systemd 配置目录: ${SOURCE_DIR}/deploy/systemd" >&2
+  exit 1
+fi
+rm -rf "${RELEASE_CONTENT_DIR}/deploy/systemd"
+cp -R "${SYSTEMD_DEPLOY_DIR_SOURCE}" "${RELEASE_CONTENT_DIR}/deploy/systemd"
+if [[ ! -d "${NGINX_DEPLOY_DIR_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Nginx 配置目录: ${SOURCE_DIR}/deploy/nginx" >&2
+  exit 1
+fi
+rm -rf "${RELEASE_CONTENT_DIR}/deploy/nginx"
+cp -R "${NGINX_DEPLOY_DIR_SOURCE}" "${RELEASE_CONTENT_DIR}/deploy/nginx"
+if [[ ! -d "${ENV_DEPLOY_DIR_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少环境变量示例目录: ${SOURCE_DIR}/deploy/env" >&2
+  exit 1
+fi
+rm -rf "${RELEASE_CONTENT_DIR}/deploy/env"
+cp -R "${ENV_DEPLOY_DIR_SOURCE}" "${RELEASE_CONTENT_DIR}/deploy/env"
 
-if [[ -f "${SOURCE_DIR}/release-manifest.json" ]]; then
-  cp "${SOURCE_DIR}/release-manifest.json" "${RELEASE_DIR}/release-manifest.api-server.json"
-fi
+cp "${SOURCE_DIR}/release-manifest.json" "${RELEASE_CONTENT_DIR}/release-manifest.api-server.json"
+
+PINGORA_SHADOW_ENV_FILE=""
 
 if [[ -n "${DATABASE}" ]]; then
   echo "[production-api-deploy] 写入 api-server SpacetimeDB database: ${DATABASE} -> ${API_ENV_FILE}"
@@ -527,8 +890,22 @@ fi
 
 ensure_runtime_env_and_dirs "${API_ENV_FILE}"
 
+if [[ "${PINGORA_INCLUDED}" -eq 1 ]]; then
+  PINGORA_SHADOW_ENV_FILE="$(check_pingora_shadow_service_config "${PINGORA_SERVICE_NAME}")"
+fi
+
 mkdir -p "$(dirname "${CURRENT_LINK}")"
-ln -sfn "${RELEASE_DIR}" "${CURRENT_LINK}"
+if [[ -e "${RELEASE_DIR}" ]]; then
+  echo "[production-api-deploy] 目标 release 在发布过程中出现，拒绝合并 staging: ${RELEASE_DIR}" >&2
+  exit 1
+fi
+mv -T "${STAGING_RELEASE_DIR}" "${RELEASE_DIR}"
+STAGING_RELEASE_DIR=""
+ln -sfnT "${RELEASE_DIR}" "${CURRENT_LINK}"
+
+if [[ "${PINGORA_INCLUDED}" -eq 1 ]]; then
+  ensure_pingora_shadow_service "${PINGORA_SERVICE_NAME}" "${PINGORA_SHADOW_ENV_FILE}"
+fi
 
 echo "[production-api-deploy] 重启服务: ${SERVICE_NAME}"
 systemctl restart "${SERVICE_NAME}"
@@ -540,7 +917,7 @@ wait_for_worker_controller_service "${WORKER_CONTROLLER_SERVICE}"
 echo "[production-api-deploy] 等待 readiness: ${HEALTH_URL}"
 for _ in {1..30}; do
   if curl -fsS "${HEALTH_URL}" >/dev/null; then
-    "${SCRIPT_DIR}/maintenance-off.sh"
+    bash "${SCRIPT_DIR}/maintenance-off.sh"
     DEPLOY_COMPLETED=1
     echo "[production-api-deploy] 完成: ${RELEASE_DIR}/api-server"
     exit 0
diff --git a/scripts/deploy/production-stdb-publish.sh b/scripts/deploy/production-stdb-publish.sh
index cdd60d41b..0f894adc7 100644
--- a/scripts/deploy/production-stdb-publish.sh
+++ b/scripts/deploy/production-stdb-publish.sh
@@ -174,7 +174,7 @@ prepare_async_backup() {
 
   ASYNC_BACKUP_STATUS_FILE="$(mktemp /tmp/genarrative-stdb-backup-status.XXXXXX.json)"
   echo "[production-stdb-publish] publish 前生成本地冷备份，随后会异步上传 OSS"
-  node "${ASYNC_BACKUP_SCRIPT}" \
+  node -- "${ASYNC_BACKUP_SCRIPT}" \
     --env-file /etc/genarrative/api-server.env \
     --data-dir "${SPACETIME_ROOT_DIR}" \
     --database "${DATABASE}" \
@@ -200,7 +200,7 @@ start_async_backup_upload() {
   mkdir -p "$(dirname "${ASYNC_BACKUP_ARCHIVE}")"
   ASYNC_BACKUP_LOG="$(dirname "${ASYNC_BACKUP_ARCHIVE}")/${DATABASE}-upload.log"
   echo "[production-stdb-publish] 后台上传本地备份到 OSS: ${ASYNC_BACKUP_ARCHIVE}"
-  nohup node "${ASYNC_BACKUP_SCRIPT}" \
+  nohup node -- "${ASYNC_BACKUP_SCRIPT}" \
     --env-file /etc/genarrative/api-server.env \
     --upload-archive "${ASYNC_BACKUP_ARCHIVE}" \
     --manifest-file "${ASYNC_BACKUP_MANIFEST}" \
@@ -254,7 +254,7 @@ case "${BACKUP_MODE}" in
     fi
 
     echo "[production-stdb-publish] publish 前同步执行 OSS 冷备份，失败会阻断发布"
-    node "${BACKUP_SCRIPT}" \
+    node -- "${BACKUP_SCRIPT}" \
       --env-file /etc/genarrative/api-server.env \
       --data-dir "${SPACETIME_ROOT_DIR}" \
       --database "${DATABASE}" \
diff --git a/scripts/jenkins-server-provision.sh b/scripts/jenkins-server-provision.sh
index 279a4dac3..454611aa6 100755
--- a/scripts/jenkins-server-provision.sh
+++ b/scripts/jenkins-server-provision.sh
@@ -652,10 +652,15 @@ restore_nginx_default_sites_enabled() {
 install_nginx_config_with_rollback() {
   local config_target="/etc/nginx/conf.d/genarrative.conf"
   local snippet_target="/etc/nginx/snippets/genarrative-maintenance.conf"
+  local pingora_canary_snippet_target="/etc/nginx/snippets/genarrative-pingora-canary.conf"
+  local pingora_realpath_canary_snippet_target="/etc/nginx/snippets/genarrative-pingora-realpath-canary.conf"
   local config_source
-  local rendered_config rendered_snippet config_backup snippet_backup disabled_sites
+  local rendered_config rendered_snippet rendered_pingora_canary_snippet rendered_pingora_realpath_canary_snippet
+  local config_backup snippet_backup pingora_canary_snippet_backup pingora_realpath_canary_snippet_backup disabled_sites
   local had_config="false"
   local had_snippet="false"
+  local had_pingora_canary_snippet="false"
+  local had_pingora_realpath_canary_snippet="false"
 
   run_cmd mkdir -p /etc/nginx/snippets /etc/nginx/conf.d
   if [[ "${NGINX_CONFIG_MODE}" == "production-https" ]]; then
@@ -669,6 +674,8 @@ install_nginx_config_with_rollback() {
 
   echo "+ render ${config_source} -> ${config_target}"
   echo "+ install -m 0644 deploy/nginx/snippets/genarrative-maintenance.conf ${snippet_target}"
+  echo "+ install -m 0644 deploy/nginx/snippets/genarrative-pingora-canary.conf ${pingora_canary_snippet_target}"
+  echo "+ install -m 0644 deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf ${pingora_realpath_canary_snippet_target}"
 
   if [[ "${DRY_RUN}" == "true" ]]; then
     echo "+ disable /etc/nginx/sites-enabled/default* if present"
@@ -679,8 +686,12 @@ install_nginx_config_with_rollback() {
 
   rendered_config="$(mktemp)"
   rendered_snippet="$(mktemp)"
+  rendered_pingora_canary_snippet="$(mktemp)"
+  rendered_pingora_realpath_canary_snippet="$(mktemp)"
   config_backup="$(mktemp)"
   snippet_backup="$(mktemp)"
+  pingora_canary_snippet_backup="$(mktemp)"
+  pingora_realpath_canary_snippet_backup="$(mktemp)"
   disabled_sites="$(mktemp)"
   if [[ "${NGINX_CONFIG_MODE}" == "production-https" ]]; then
     validate_nginx_tls
@@ -689,6 +700,8 @@ install_nginx_config_with_rollback() {
     render_nginx_development_http_config >"${rendered_config}"
   fi
   cp deploy/nginx/snippets/genarrative-maintenance.conf "${rendered_snippet}"
+  cp deploy/nginx/snippets/genarrative-pingora-canary.conf "${rendered_pingora_canary_snippet}"
+  cp deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf "${rendered_pingora_realpath_canary_snippet}"
 
   if [[ -f "${config_target}" ]]; then
     cp -p "${config_target}" "${config_backup}"
@@ -698,9 +711,19 @@ install_nginx_config_with_rollback() {
     cp -p "${snippet_target}" "${snippet_backup}"
     had_snippet="true"
   fi
+  if [[ -f "${pingora_canary_snippet_target}" ]]; then
+    cp -p "${pingora_canary_snippet_target}" "${pingora_canary_snippet_backup}"
+    had_pingora_canary_snippet="true"
+  fi
+  if [[ -f "${pingora_realpath_canary_snippet_target}" ]]; then
+    cp -p "${pingora_realpath_canary_snippet_target}" "${pingora_realpath_canary_snippet_backup}"
+    had_pingora_realpath_canary_snippet="true"
+  fi
 
   install -m 0644 "${rendered_config}" "${config_target}"
   install -m 0644 "${rendered_snippet}" "${snippet_target}"
+  install -m 0644 "${rendered_pingora_canary_snippet}" "${pingora_canary_snippet_target}"
+  install -m 0644 "${rendered_pingora_realpath_canary_snippet}" "${pingora_realpath_canary_snippet_target}"
   disable_nginx_default_sites_enabled "${disabled_sites}"
 
   if ! nginx -t; then
@@ -715,14 +738,24 @@ install_nginx_config_with_rollback() {
     else
       rm -f "${snippet_target}"
     fi
+    if [[ "${had_pingora_canary_snippet}" == "true" ]]; then
+      cp -p "${pingora_canary_snippet_backup}" "${pingora_canary_snippet_target}"
+    else
+      rm -f "${pingora_canary_snippet_target}"
+    fi
+    if [[ "${had_pingora_realpath_canary_snippet}" == "true" ]]; then
+      cp -p "${pingora_realpath_canary_snippet_backup}" "${pingora_realpath_canary_snippet_target}"
+    else
+      rm -f "${pingora_realpath_canary_snippet_target}"
+    fi
     restore_nginx_default_sites_enabled "${disabled_sites}"
-    rm -f "${rendered_config}" "${rendered_snippet}" "${config_backup}" "${snippet_backup}" "${disabled_sites}"
+    rm -f "${rendered_config}" "${rendered_snippet}" "${rendered_pingora_canary_snippet}" "${rendered_pingora_realpath_canary_snippet}" "${config_backup}" "${snippet_backup}" "${pingora_canary_snippet_backup}" "${pingora_realpath_canary_snippet_backup}" "${disabled_sites}"
     exit 1
   fi
   echo "+ nginx -s reload"
   nginx -s reload
 
-  rm -f "${rendered_config}" "${rendered_snippet}" "${config_backup}" "${snippet_backup}" "${disabled_sites}"
+  rm -f "${rendered_config}" "${rendered_snippet}" "${rendered_pingora_canary_snippet}" "${rendered_pingora_realpath_canary_snippet}" "${config_backup}" "${snippet_backup}" "${pingora_canary_snippet_backup}" "${pingora_realpath_canary_snippet_backup}" "${disabled_sites}"
 }
 
 cleanup_placeholder_nginx_config() {
@@ -824,11 +857,16 @@ require_path deploy/systemd/genarrative-database-backup.service
 require_path deploy/systemd/genarrative-database-backup.timer
 require_path deploy/systemd/genarrative-health-patrol.service
 require_path deploy/systemd/genarrative-health-patrol.timer
+require_path deploy/systemd/genarrative-pingora-gateway.service
+require_path deploy/systemd/genarrative-pingora-gateway-direct-entry.conf
 require_path deploy/systemd/otelcol-contrib.service
 require_path deploy/otelcol/genarrative-debug.yaml
 require_path deploy/nginx/genarrative.conf
 require_path deploy/nginx/genarrative-dev-http.conf
 require_path deploy/nginx/snippets/genarrative-maintenance.conf
+require_path deploy/nginx/snippets/genarrative-pingora-canary.conf
+require_path deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf
+require_path deploy/logrotate/genarrative-pingora-gateway
 require_path deploy/env/api-server.env.example
 require_path deploy/env/external-generation-worker.env.example
 require_path deploy/env/external-generation-controller.env.example
@@ -844,7 +882,7 @@ echo "[server-provision] target=${DEPLOY_TARGET}, dry_run=${DRY_RUN}, nginx_conf
 run_cmd id
 require_root_for_real_provision
 install_nginx_brotli_modules
-run_cmd mkdir -p "${SPACETIME_ROOT}" "${RELEASE_ROOT}" "$(dirname "${CURRENT_LINK}")" "$(dirname "${WEB_LINK}")" /etc/genarrative /var/lib/genarrative/maintenance /var/lib/genarrative/auth /var/lib/genarrative/tracking-outbox /var/lib/genarrative/database-backups /var/lib/genarrative/health-patrol
+run_cmd mkdir -p "${SPACETIME_ROOT}" "${RELEASE_ROOT}" "$(dirname "${CURRENT_LINK}")" "$(dirname "${WEB_LINK}")" /etc/genarrative /etc/genarrative/pingora /var/lib/genarrative/maintenance /var/lib/genarrative/auth /var/lib/genarrative/tracking-outbox /var/lib/genarrative/database-backups /var/lib/genarrative/health-patrol /var/log/genarrative
 
 if ! id spacetimedb >/dev/null 2>&1; then
   run_cmd useradd --system --home-dir "${SPACETIME_ROOT}" --shell /usr/sbin/nologin spacetimedb
@@ -860,6 +898,7 @@ fi
 
 run_cmd chown -R spacetimedb:spacetimedb "${SPACETIME_ROOT}"
 run_cmd chown -R genarrative:genarrative /opt/genarrative /var/lib/genarrative /srv/genarrative
+run_cmd chown -R genarrative:genarrative /var/log/genarrative
 install_genarrative_openssl_runtime
 
 if [[ ! -x "${SPACETIME_BIN_SOURCE}" ]]; then
@@ -893,6 +932,9 @@ install_file "${database_backup_service}" /etc/systemd/system/genarrative-databa
 install_file deploy/systemd/genarrative-database-backup.timer /etc/systemd/system/genarrative-database-backup.timer 0644
 install_file "${health_patrol_service}" /etc/systemd/system/genarrative-health-patrol.service 0644
 install_file deploy/systemd/genarrative-health-patrol.timer /etc/systemd/system/genarrative-health-patrol.timer 0644
+install_file deploy/systemd/genarrative-pingora-gateway.service /etc/systemd/system/genarrative-pingora-gateway.service 0644
+install_file deploy/systemd/genarrative-pingora-gateway-direct-entry.conf /etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf 0644
+install_file deploy/logrotate/genarrative-pingora-gateway /etc/logrotate.d/genarrative-pingora-gateway 0644
 rm -f "${spacetimedb_service}" "${api_service}" "${external_generation_worker_service}" "${external_generation_controller_service}" "${database_backup_service}" "${health_patrol_service}"
 
 if [[ ! -f "${API_ENV_FILE}" ]]; then
diff --git a/scripts/ops/pingora-current-release-audit.mjs b/scripts/ops/pingora-current-release-audit.mjs
new file mode 100644
index 000000000..cc49901f2
--- /dev/null
+++ b/scripts/ops/pingora-current-release-audit.mjs
@@ -0,0 +1,705 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { access, readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const REQUIRED_ARTIFACTS = [
+  { path: 'api-server', executable: true },
+  { path: 'scripts/database-backup-to-oss.mjs' },
+  { path: 'scripts/ops/production-health-patrol.mjs' },
+  { path: 'scripts/ops/pingora-current-release-audit.mjs' },
+  { path: 'scripts/ops/pingora-direct-rehearsal-status.mjs' },
+  { path: 'scripts/ops/pingora-cutover-status-snapshot.mjs' },
+  { path: 'scripts/ops/pingora-cutover-evidence-bundle.mjs' },
+  { path: 'scripts/check-production-health-patrol-env.mjs' },
+  { path: 'scripts/check-pingora-release-readiness.mjs' },
+  { path: 'scripts/check-pingora-direct-preflight.mjs' },
+  { path: 'scripts/check-pingora-direct-live.mjs' },
+  { path: 'scripts/check-pingora-canary-live.mjs' },
+  { path: 'scripts/check-pingora-canary-access-log-parity.mjs' },
+  { path: 'scripts/deploy/pingora-direct-enable.sh', executable: true },
+  { path: 'scripts/deploy/pingora-direct-rollback.sh', executable: true },
+  { path: 'scripts/deploy/pingora-realpath-canary-enable.sh', executable: true },
+  { path: 'scripts/deploy/pingora-realpath-canary-disable.sh', executable: true },
+  { path: 'scripts/deploy/pingora-health-patrol-env-switch.mjs', executable: true },
+  { path: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs', executable: true },
+  { path: 'scripts/deploy/pingora-tls-cert-sync.mjs', executable: true },
+  { path: 'deploy/systemd/genarrative-pingora-gateway.service' },
+  { path: 'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf' },
+  { path: 'deploy/nginx/snippets/genarrative-pingora-canary.conf' },
+  { path: 'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf' },
+  { path: 'deploy/env/health-patrol.env.example' },
+  { path: 'deploy/env/pingora-direct-live.env.example' },
+  { path: 'deploy/env/pingora-canary-live.env.example' },
+  { path: 'deploy/pingora/pingora-gateway.env.example' },
+  { path: 'deploy/pingora/nginx-route-parity.matrix.json' },
+];
+const REQUIRED_DIRS = [
+  'deploy/systemd',
+  'deploy/nginx',
+  'deploy/env',
+  'deploy/pingora',
+];
+
+const config = parseArgs(process.argv.slice(2));
+const audit = await buildAudit(config);
+
+console.log(`${JSON.stringify(audit, null, 2)}\n`);
+
+if (audit.summary.status === 'CRITICAL' && !config.warnOnly) {
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const result = {
+    releaseRoot:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_RELEASE_ROOT ||
+      '/opt/genarrative/current',
+    requirePingoraGateway: readBoolEnv(
+      'GENARRATIVE_PINGORA_CURRENT_RELEASE_REQUIRE_GATEWAY',
+    ),
+    systemdShow: readBoolEnv(
+      'GENARRATIVE_PINGORA_CURRENT_RELEASE_SYSTEMD_SHOW',
+    ),
+    systemdService:
+      process.env.GENARRATIVE_PINGORA_CURRENT_RELEASE_SYSTEMD_SERVICE ||
+      'genarrative-pingora-gateway.service',
+    timeoutMs: parseOptionalPositiveInt(
+      process.env.GENARRATIVE_PINGORA_CURRENT_RELEASE_TIMEOUT_MS,
+      5000,
+      'GENARRATIVE_PINGORA_CURRENT_RELEASE_TIMEOUT_MS',
+    ),
+    warnOnly: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--release-root':
+        result.releaseRoot = requireValue(argv, ++index, arg);
+        break;
+      case '--require-pingora-gateway':
+        result.requirePingoraGateway = true;
+        break;
+      case '--systemd-show':
+        result.systemdShow = true;
+        break;
+      case '--systemd-service':
+        result.systemdService = requireValue(argv, ++index, arg);
+        break;
+      case '--timeout-ms':
+        result.timeoutMs = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          arg,
+        );
+        break;
+      case '--warn-only':
+        result.warnOnly = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (!path.isAbsolute(result.releaseRoot)) {
+    throw new Error('--release-root 必须是绝对路径。');
+  }
+  validateNoControlCharacters(result.releaseRoot, '--release-root');
+  if (isFilesystemRootPath(result.releaseRoot)) {
+    throw new Error('--release-root 不能是文件系统根目录。');
+  }
+  validateNoControlCharacters(result.systemdService, '--systemd-service');
+  if (!result.systemdService || /[\s/]/u.test(result.systemdService)) {
+    throw new Error('--systemd-service 必须是 systemd unit 名称。');
+  }
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/ops/pingora-current-release-audit.mjs [options]
+
+Options:
+  --release-root <path>          current release 根目录，默认 /opt/genarrative/current。
+  --require-pingora-gateway     要求 current release 已包含 pingora-gateway 且可执行。
+  --systemd-show                读取 systemctl show，确认 service ExecStart 指向 current release 的 pingora-gateway。
+  --systemd-service <name>      systemd service 名，默认 genarrative-pingora-gateway.service。
+  --timeout-ms <ms>             systemctl 超时，默认 5000。
+  --warn-only                   即使出现 CRITICAL 也以退出码 0 结束，只用于人工盘点。
+
+该脚本只读检查 current release 自包含能力，不写 /etc、不 reload systemd、不修改 Nginx 或 Pingora。
+CRITICAL 默认会让进程以退出码 1 结束，适合作为切换窗口前置门禁。
+`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function readBoolEnv(name) {
+  const value = process.env[name];
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return false;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${name} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function parseOptionalPositiveInt(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parseRequiredPositiveInt(raw, label);
+}
+
+function parseRequiredPositiveInt(raw, label) {
+  const text = String(raw ?? '').trim();
+  if (!/^[1-9][0-9]*$/u.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  return Number.parseInt(text, 10);
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+async function buildAudit(input) {
+  const artifacts = await inspectArtifacts(input);
+  const directories = await inspectDirectories(input);
+  const pingoraGateway = await inspectPingoraGateway(input);
+  const checksums = await inspectChecksums(input, pingoraGateway);
+  const releaseManifest = await inspectReleaseManifest(input, pingoraGateway);
+  const systemd = input.systemdShow
+    ? await inspectSystemd(input)
+    : {
+        checked: false,
+        status: 'OK',
+        diagnostics: [],
+      };
+  const summary = summarize([
+    ...artifacts.map((artifact) => artifact.status),
+    ...directories.map((directory) => directory.status),
+    pingoraGateway.status,
+    ...checksums.map((checksum) => checksum.status),
+    releaseManifest.status,
+    systemd.status,
+  ]);
+
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    releaseRoot: input.releaseRoot,
+    summary,
+    artifacts,
+    directories,
+    pingoraGateway,
+    checksums,
+    releaseManifest,
+    systemd,
+  };
+}
+
+async function inspectArtifacts(input) {
+  const artifacts = [];
+  for (const artifact of REQUIRED_ARTIFACTS) {
+    artifacts.push(await inspectArtifact(input.releaseRoot, artifact));
+  }
+  return artifacts;
+}
+
+async function inspectDirectories(input) {
+  const directories = [];
+  for (const relativePath of REQUIRED_DIRS) {
+    const fullPath = path.join(input.releaseRoot, relativePath);
+    const diagnostics = [];
+    let exists = false;
+    let status = 'OK';
+    try {
+      const fileStat = await stat(fullPath);
+      exists = fileStat.isDirectory();
+      if (!exists) {
+        diagnostics.push('路径存在但不是目录。');
+        status = 'CRITICAL';
+      }
+    } catch (error) {
+      diagnostics.push(`目录不存在或不可读: ${error.message}`);
+      status = 'CRITICAL';
+    }
+    directories.push({
+      path: relativePath,
+      exists,
+      status,
+      diagnostics,
+    });
+  }
+  return directories;
+}
+
+async function inspectArtifact(releaseRoot, artifact) {
+  const fullPath = path.join(releaseRoot, artifact.path);
+  const diagnostics = [];
+  let exists = false;
+  let type = 'missing';
+  let executable = false;
+  let status = 'OK';
+
+  try {
+    const fileStat = await stat(fullPath);
+    exists = true;
+    type = fileStat.isFile()
+      ? 'file'
+      : fileStat.isDirectory()
+        ? 'directory'
+        : 'other';
+    if (type !== 'file') {
+      diagnostics.push('路径存在但不是文件。');
+      status = 'CRITICAL';
+    }
+  } catch (error) {
+    diagnostics.push(`文件不存在或不可读: ${error.message}`);
+    status = 'CRITICAL';
+  }
+
+  if (exists && artifact.executable) {
+    try {
+      await access(fullPath, fsConstants.X_OK);
+      executable = true;
+    } catch (error) {
+      diagnostics.push(`文件不可执行: ${error.message}`);
+      status = 'CRITICAL';
+    }
+  }
+
+  return {
+    path: artifact.path,
+    expectedExecutable: Boolean(artifact.executable),
+    exists,
+    type,
+    executable,
+    status,
+    diagnostics,
+  };
+}
+
+async function inspectPingoraGateway(input) {
+  const binaryPath = path.join(input.releaseRoot, 'pingora-gateway');
+  const diagnostics = [];
+  let included = false;
+  let executable = false;
+  let status = 'OK';
+
+  try {
+    const fileStat = await stat(binaryPath);
+    included = fileStat.isFile();
+    if (!included) {
+      diagnostics.push('pingora-gateway 路径存在但不是文件。');
+      status = 'CRITICAL';
+    }
+  } catch (error) {
+    if (input.requirePingoraGateway) {
+      diagnostics.push(`缺少 pingora-gateway: ${error.message}`);
+      status = 'CRITICAL';
+    }
+  }
+
+  if (included) {
+    try {
+      await access(binaryPath, fsConstants.X_OK);
+      executable = true;
+    } catch (error) {
+      diagnostics.push(`pingora-gateway 不可执行: ${error.message}`);
+      status = 'CRITICAL';
+    }
+  }
+
+  return {
+    required: input.requirePingoraGateway,
+    included,
+    path: 'pingora-gateway',
+    absolutePath: binaryPath,
+    executable,
+    status,
+    diagnostics,
+  };
+}
+
+async function inspectChecksums(input, pingoraGateway) {
+  const checksumTargets = [
+    {
+      path: 'api-server',
+      checksumPath: 'api-server.sha256',
+      required: true,
+    },
+    {
+      path: 'pingora-gateway',
+      checksumPath: 'pingora-gateway.sha256',
+      required: input.requirePingoraGateway || pingoraGateway.included,
+    },
+  ];
+
+  const checksums = [];
+  for (const target of checksumTargets) {
+    checksums.push(await inspectChecksum(input.releaseRoot, target));
+  }
+  return checksums;
+}
+
+async function inspectChecksum(releaseRoot, target) {
+  const diagnostics = [];
+  const artifactPath = path.join(releaseRoot, target.path);
+  const checksumPath = path.join(releaseRoot, target.checksumPath);
+  let status = 'OK';
+  let checked = false;
+  let exists = false;
+  let expectedSha256 = '';
+  let computedSha256 = '';
+  let checksumFileTarget = '';
+
+  if (!target.required) {
+    return {
+      path: target.path,
+      checksumPath: target.checksumPath,
+      required: false,
+      checked,
+      exists,
+      checksumFileTarget,
+      expectedSha256,
+      computedSha256,
+      matches: null,
+      status,
+      diagnostics,
+    };
+  }
+
+  try {
+    const checksumText = await readFile(checksumPath, 'utf8');
+    exists = true;
+    const parsed = parseSha256File(checksumText);
+    expectedSha256 = parsed.sha256;
+    checksumFileTarget = parsed.fileName;
+    if (path.basename(checksumFileTarget) !== path.basename(target.path)) {
+      diagnostics.push(
+        `${target.checksumPath} 指向了非预期文件: ${checksumFileTarget}`,
+      );
+      status = 'CRITICAL';
+    }
+  } catch (error) {
+    diagnostics.push(`checksum 文件不存在、不可读或格式错误: ${error.message}`);
+    status = 'CRITICAL';
+  }
+
+  try {
+    computedSha256 = await sha256File(artifactPath);
+    checked = true;
+  } catch (error) {
+    diagnostics.push(`无法读取待校验文件: ${error.message}`);
+    status = 'CRITICAL';
+  }
+
+  const matches =
+    checked && Boolean(expectedSha256) && computedSha256 === expectedSha256;
+  if (checked && expectedSha256 && !matches) {
+    diagnostics.push(
+      `${target.path} sha256 不匹配: expected ${expectedSha256}, actual ${computedSha256}`,
+    );
+    status = 'CRITICAL';
+  }
+
+  return {
+    path: target.path,
+    checksumPath: target.checksumPath,
+    required: target.required,
+    checked,
+    exists,
+    checksumFileTarget,
+    expectedSha256,
+    computedSha256,
+    matches,
+    status,
+    diagnostics,
+  };
+}
+
+function parseSha256File(content) {
+  const firstLine = content.split(/\r?\n/u).find((line) => line.trim());
+  if (!firstLine) {
+    throw new Error('checksum 文件为空');
+  }
+  const match = firstLine.match(/^([0-9a-fA-F]{64})\s+(.+)$/u);
+  if (!match) {
+    throw new Error('checksum 行必须是 sha256sum 输出格式');
+  }
+  return {
+    sha256: match[1].toLowerCase(),
+    fileName: match[2].replace(/^\*/u, '').trim(),
+  };
+}
+
+async function sha256File(filePath) {
+  const content = await readFile(filePath);
+  return createHash('sha256').update(content).digest('hex');
+}
+
+async function inspectReleaseManifest(input, pingoraGateway) {
+  const candidates = [
+    'release-manifest.api-server.json',
+    'release-manifest.json',
+  ];
+  const diagnostics = [];
+  let status = 'OK';
+  let pathUsed = '';
+  let manifest = null;
+
+  for (const candidate of candidates) {
+    try {
+      const content = await readFile(path.join(input.releaseRoot, candidate), 'utf8');
+      manifest = JSON.parse(content);
+      pathUsed = candidate;
+      break;
+    } catch (error) {
+      diagnostics.push(`${candidate} 不可用: ${error.message}`);
+    }
+  }
+
+  if (!manifest) {
+    return {
+      checked: true,
+      path: '',
+      candidates,
+      componentType: '',
+      artifacts: [],
+      status: 'CRITICAL',
+      diagnostics,
+    };
+  }
+
+  diagnostics.length = 0;
+  const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+  const apiArtifact = artifacts.find((artifact) => artifact?.path === 'api-server');
+  const pingoraArtifact = artifacts.find(
+    (artifact) => artifact?.path === 'pingora-gateway',
+  );
+
+  if (manifest.component_type !== 'api-server') {
+    diagnostics.push(
+      `release manifest component_type 应为 api-server，实际 ${manifest.component_type || '(空)'}`,
+    );
+    status = 'CRITICAL';
+  }
+  if (!apiArtifact) {
+    diagnostics.push('release manifest 缺少 api-server artifact。');
+    status = 'CRITICAL';
+  } else if (apiArtifact.checksum_path !== 'api-server.sha256') {
+    diagnostics.push(
+      `api-server artifact checksum_path 应为 api-server.sha256，实际 ${apiArtifact.checksum_path || '(空)'}`,
+    );
+    status = 'CRITICAL';
+  }
+
+  if (input.requirePingoraGateway || pingoraGateway.included) {
+    if (!pingoraArtifact) {
+      diagnostics.push('release manifest 缺少 pingora-gateway artifact。');
+      status = 'CRITICAL';
+    } else if (pingoraArtifact.checksum_path !== 'pingora-gateway.sha256') {
+      diagnostics.push(
+        `pingora-gateway artifact checksum_path 应为 pingora-gateway.sha256，实际 ${pingoraArtifact.checksum_path || '(空)'}`,
+      );
+      status = 'CRITICAL';
+    }
+  } else if (pingoraArtifact) {
+    diagnostics.push(
+      'release manifest 登记了 pingora-gateway，但 current release 未包含该二进制。',
+    );
+    status = 'CRITICAL';
+  }
+
+  return {
+    checked: true,
+    path: pathUsed,
+    candidates,
+    componentType: manifest.component_type || '',
+    artifacts: artifacts.map((artifact) => ({
+      component: artifact?.component || '',
+      path: artifact?.path || '',
+      checksumPath: artifact?.checksum_path || '',
+    })),
+    status,
+    diagnostics,
+  };
+}
+
+async function inspectSystemd(input) {
+  const expectedBinary = path.join(input.releaseRoot, 'pingora-gateway');
+  const expectedRealpath = await resolveOptionalRealpath(expectedBinary);
+  const result = await runCommand(
+    'systemctl',
+    [
+      'show',
+      input.systemdService,
+      '--property=FragmentPath',
+      '--property=DropInPaths',
+      '--property=User',
+      '--property=ExecStart',
+      '--no-pager',
+    ],
+    input,
+  );
+  const show = parseSystemctlShow(result.stdout);
+  const diagnostics = [];
+  let status = 'OK';
+
+  if (result.code !== 0) {
+    diagnostics.push(`systemctl show 失败: ${result.stderr || result.error}`);
+    status = 'CRITICAL';
+  }
+
+  const execStart = show.ExecStart || '';
+  const execStartBinary = parseExecStartBinary(execStart);
+  const execStartRealpath = execStartBinary
+    ? await resolveOptionalRealpath(execStartBinary)
+    : null;
+  const execStartMatches =
+    execStartBinary === expectedBinary ||
+    (expectedRealpath &&
+      execStartRealpath &&
+      expectedRealpath === execStartRealpath);
+
+  if (result.code === 0 && !execStartMatches) {
+    diagnostics.push(
+      `ExecStart 未指向 current release 网关二进制: expected ${expectedBinary}, actual ${execStart || '(空)'}`,
+    );
+    status = 'CRITICAL';
+  }
+
+  return {
+    checked: true,
+    service: input.systemdService,
+    status,
+    expectedBinary,
+    expectedRealpath,
+    execStartBinary,
+    execStartRealpath,
+    fragmentPath: show.FragmentPath || '',
+    dropInPaths: show.DropInPaths || '',
+    user: show.User || '',
+    execStart,
+    command: result.command,
+    diagnostics,
+  };
+}
+
+async function resolveOptionalRealpath(filePath) {
+  try {
+    return await realpath(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function parseExecStartBinary(execStart) {
+  const pathMatch = execStart.match(/\bpath=([^ ;]+)(?:\s|;|$)/u);
+  if (pathMatch) {
+    return pathMatch[1];
+  }
+  const argvMatch = execStart.match(/\bargv\[\]=([^ ;]+)(?:\s|;|$)/u);
+  if (argvMatch) {
+    return argvMatch[1];
+  }
+  return '';
+}
+
+function parseSystemctlShow(text) {
+  const result = {};
+  for (const line of text.split(/\r?\n/u)) {
+    const equalsIndex = line.indexOf('=');
+    if (equalsIndex <= 0) {
+      continue;
+    }
+    result[line.slice(0, equalsIndex)] = line.slice(equalsIndex + 1);
+  }
+  return result;
+}
+
+function runCommand(command, args, input) {
+  validateNoControlCharacters(command, '子命令可执行文件');
+  for (const arg of args) {
+    validateNoControlCharacters(arg, '子命令参数');
+  }
+
+  return new Promise((resolve) => {
+    const startedAt = new Date();
+    const child = execFile(
+      command,
+      args,
+      {
+        encoding: 'utf8',
+        timeout: input.timeoutMs,
+        maxBuffer: 1024 * 1024,
+      },
+      (error, stdout, stderr) => {
+        const finishedAt = new Date();
+        resolve({
+          command: [command, ...args],
+          code: error?.code ?? 0,
+          signal: error?.signal ?? null,
+          error: error ? error.message : '',
+          stdout: stdout || '',
+          stderr: stderr || '',
+          startedAt: startedAt.toISOString(),
+          finishedAt: finishedAt.toISOString(),
+          durationMs: finishedAt.getTime() - startedAt.getTime(),
+        });
+      },
+    );
+    child.on('error', (error) => {
+      const finishedAt = new Date();
+      resolve({
+        command: [command, ...args],
+        code: 1,
+        signal: null,
+        error: error.message,
+        stdout: '',
+        stderr: '',
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+      });
+    });
+  });
+}
+
+function summarize(statuses) {
+  const criticalCount = statuses.filter((status) => status === 'CRITICAL').length;
+  const warningCount = statuses.filter((status) => status === 'WARNING').length;
+  return {
+    status: criticalCount > 0 ? 'CRITICAL' : warningCount > 0 ? 'WARNING' : 'OK',
+    criticalCount,
+    warningCount,
+  };
+}
diff --git a/scripts/ops/pingora-cutover-command-evidence.mjs b/scripts/ops/pingora-cutover-command-evidence.mjs
new file mode 100644
index 000000000..9fdce149b
--- /dev/null
+++ b/scripts/ops/pingora-cutover-command-evidence.mjs
@@ -0,0 +1,518 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import {
+  access,
+  chmod,
+  lstat,
+  mkdir,
+  readFile,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import path from 'node:path';
+
+const BUNDLE_DIR_MODE = 0o750;
+const EVIDENCE_FILE_MODE = 0o640;
+const SECRET_VALUE_FLAGS = new Set([
+  '--direct-probe-token',
+  '--probe-token',
+  '--pingora-shadow-probe-token',
+  '--rollback-pingora-shadow-probe-token',
+]);
+const SECRET_ENV_KEYS = [
+  'GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN',
+  'GENARRATIVE_PINGORA_ROLLBACK_SHADOW_PROBE_TOKEN',
+  'GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN',
+  'GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN',
+];
+
+const config = parseArgs(process.argv.slice(2));
+const secretValues = collectSecretValues(config.commandArgs, process.env);
+const startedAt = new Date();
+const bundleDir = await createBundleDir(
+  config.outputRoot,
+  config.phase,
+  config.commandName,
+  startedAt,
+);
+const run = await runCommand(config.command, config.commandArgs, secretValues);
+const finishedAt = new Date();
+
+const stdoutPath = path.join(bundleDir, 'command.stdout.txt');
+const stderrPath = path.join(bundleDir, 'command.stderr.txt');
+const recordPath = path.join(bundleDir, 'command-record.json');
+const manifestPath = path.join(bundleDir, 'manifest.json');
+const exitCode =
+  run.signal
+    ? run.exitCode ?? 1
+    : run.exitCode === null || run.exitCode === undefined
+    ? run.error
+      ? 1
+      : 0
+    : run.exitCode;
+const status = exitCode === 0 && !run.signal && !run.error ? 'OK' : 'FAILED';
+
+await writeEvidenceFile(stdoutPath, redactSecrets(run.stdout, secretValues));
+await writeEvidenceFile(stderrPath, redactSecrets(run.stderr, secretValues));
+
+const commandRecord = {
+  schemaVersion: 1,
+  name: config.commandName,
+  phase: config.phase,
+  ...(config.cutoverRunId ? { cutoverRunId: config.cutoverRunId } : {}),
+  ...(config.expectedExecutable
+    ? { expectedExecutable: config.expectedExecutable }
+    : {}),
+  executable: redactSecrets(config.command, secretValues),
+  args: redactSecretArgs(config.commandArgs, secretValues),
+  command: formatCommand(config.command, config.commandArgs, secretValues),
+  cwd: process.cwd(),
+  exitCode,
+  signal: run.signal,
+  error: run.error || null,
+  startedAt: startedAt.toISOString(),
+  finishedAt: finishedAt.toISOString(),
+  durationMs: finishedAt.getTime() - startedAt.getTime(),
+  stdoutPath: path.basename(stdoutPath),
+  stderrPath: path.basename(stderrPath),
+};
+await writeEvidenceFile(
+  recordPath,
+  `${JSON.stringify(commandRecord, null, 2)}\n`,
+);
+const artifactFiles = {
+  stdout: await buildEvidenceFileMetadata(stdoutPath),
+  stderr: await buildEvidenceFileMetadata(stderrPath),
+  commandRecord: await buildEvidenceFileMetadata(recordPath),
+};
+
+const manifest = {
+  schemaVersion: 1,
+  generatedAt: new Date().toISOString(),
+  phase: config.phase,
+  commandName: config.commandName,
+  ...(config.cutoverRunId ? { cutoverRunId: config.cutoverRunId } : {}),
+  ...(config.expectedExecutable
+    ? { expectedExecutable: config.expectedExecutable }
+    : {}),
+  outputRoot: config.outputRoot,
+  bundleDir,
+  summary: {
+    status,
+    exitCode,
+    signal: run.signal,
+  },
+  files: {
+    manifest: path.basename(manifestPath),
+    ...artifactFiles,
+  },
+  command: commandRecord,
+};
+await writeEvidenceFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+console.log(
+  `${JSON.stringify(
+    {
+      ok: status === 'OK',
+      phase: config.phase,
+      commandName: config.commandName,
+      cutoverRunId: config.cutoverRunId || null,
+      expectedExecutable: config.expectedExecutable || null,
+      status,
+      exitCode,
+      bundleDir,
+      manifestPath,
+      stdoutPath,
+      stderrPath,
+      commandRecordPath: recordPath,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (exitCode !== 0) {
+  process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+  const separatorIndex = argv.indexOf('--');
+  const optionArgs =
+    separatorIndex < 0 ? argv : argv.slice(0, separatorIndex);
+  if (optionArgs.includes('-h') || optionArgs.includes('--help')) {
+    printUsage();
+    process.exit(0);
+  }
+  if (separatorIndex < 0) {
+    throw new Error('必须使用 -- 分隔证据参数和真实命令。');
+  }
+
+  const command = argv[separatorIndex + 1] || '';
+  const commandArgs = argv.slice(separatorIndex + 2);
+  const result = {
+    phase:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_COMMAND_PHASE || 'manual',
+    commandName:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_COMMAND_NAME || 'command',
+    cutoverRunId: process.env.GENARRATIVE_PINGORA_CUTOVER_RUN_ID || '',
+    expectedExecutable:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_EXPECTED_EXECUTABLE || '',
+    requiredArgs: parseRequiredArgsEnv(
+      process.env.GENARRATIVE_PINGORA_CUTOVER_REQUIRED_ARGS || '',
+    ),
+    outputRoot:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_ROOT ||
+      '/var/log/genarrative/pingora-cutover-evidence',
+    command,
+    commandArgs,
+  };
+
+  for (let index = 0; index < optionArgs.length; index += 1) {
+    const arg = optionArgs[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--phase':
+        result.phase = requireValue(optionArgs, ++index, arg);
+        break;
+      case '--command-name':
+        result.commandName = requireValue(optionArgs, ++index, arg);
+        break;
+      case '--cutover-run-id':
+        result.cutoverRunId = requireValue(optionArgs, ++index, arg);
+        break;
+      case '--expected-executable':
+        result.expectedExecutable = requireValue(optionArgs, ++index, arg);
+        break;
+      case '--require-arg':
+        result.requiredArgs.push(requireAnyValue(optionArgs, ++index, arg));
+        break;
+      case '--output-root':
+        result.outputRoot = requireValue(optionArgs, ++index, arg);
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  validateConfig(result);
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/ops/pingora-cutover-command-evidence.mjs [options] -- <command> [args...]
+
+Options:
+  --phase <name>         写入 manifest 的阶段标签，例如 enable-apply / rollback-apply。
+  --command-name <name>  写入 manifest 的命令名，例如 pingora-direct-rollback-apply。
+  --cutover-run-id <id>  可选，写入 manifest 的本次切换批次 ID；正式 runbook 会用同一 ID 串联所有阶段和命令证据。
+  --expected-executable <path>
+                        可选，要求 -- 后面的真实命令精确等于该绝对路径；正式 runbook 用于绑定 apply 证据和 current release 随包脚本。
+  --require-arg <arg>    可选，要求 -- 后面的真实命令参数包含该值；正式 runbook 用于在执行前确认 apply 证据包含 --apply。
+  --output-root <path>   证据输出根目录，默认 /var/log/genarrative/pingora-cutover-evidence。
+
+该脚本会执行 -- 后面的真实命令，并把 stdout、stderr、退出码、脱敏后的命令记录和 manifest 写入 --output-root 下的新证据目录；失败时仍保留证据并返回真实命令的退出码。
+`);
+}
+
+function validateConfig(config) {
+  validateSafeName(config.phase, '--phase');
+  validateSafeName(config.commandName, '--command-name');
+  if (config.cutoverRunId) {
+    validateSafeName(config.cutoverRunId, '--cutover-run-id');
+  }
+  if (config.expectedExecutable) {
+    validateSafeExecutablePath(config.expectedExecutable, '--expected-executable');
+  }
+  if (!path.isAbsolute(config.outputRoot)) {
+    throw new Error('--output-root 必须是绝对路径。');
+  }
+  if (path.resolve(config.outputRoot) === path.parse(path.resolve(config.outputRoot)).root) {
+    throw new Error('--output-root 不能是文件系统根目录。');
+  }
+  validateNoControlCharacters(config.outputRoot, '--output-root');
+  if (!config.command) {
+    throw new Error('-- 后必须提供真实命令。');
+  }
+  validateCommandPath(config.command);
+  for (const commandArg of config.commandArgs) {
+    validateCommandArg(commandArg);
+  }
+  if (
+    config.expectedExecutable &&
+    config.command !== config.expectedExecutable
+  ) {
+    throw new Error(
+      `真实命令与 --expected-executable 不一致: expected ${config.expectedExecutable}, got ${config.command}`,
+    );
+  }
+  for (const requiredArg of config.requiredArgs) {
+    validateRequiredArg(requiredArg, '--require-arg');
+    if (!config.commandArgs.includes(requiredArg)) {
+      throw new Error(`真实命令参数缺少 --require-arg 要求的 ${requiredArg}`);
+    }
+  }
+}
+
+function validateCommandPath(command) {
+  validateSafeExecutablePath(command, '真实命令');
+}
+
+function validateCommandArg(value) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error('真实命令参数不能包含换行或 NUL 字符。');
+  }
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function validateSafeExecutablePath(command, label) {
+  const prefix = label.startsWith('--') ? `${label} ` : label;
+  if (!path.isAbsolute(command)) {
+    throw new Error(`${prefix}必须是绝对路径。`);
+  }
+  if (path.resolve(command) === path.parse(path.resolve(command)).root) {
+    throw new Error(`${prefix}不能是文件系统根目录。`);
+  }
+  if (/[\0\r\n]/u.test(command)) {
+    throw new Error(`${prefix}不能包含换行或 NUL 字符。`);
+  }
+}
+
+function parseRequiredArgsEnv(value) {
+  return String(value || '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function validateRequiredArg(value, label) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    /[\0\r\n]/u.test(value)
+  ) {
+    throw new Error(`${label} 必须是非空且不包含换行的字符串。`);
+  }
+}
+
+function validateSafeName(value, label) {
+  const text = String(value || '');
+  if (!/^[0-9A-Za-z._-]+$/u.test(text)) {
+    throw new Error(
+      `${label} 只能包含 ASCII 字母、数字、点、下划线或短横线。`,
+    );
+  }
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function requireAnyValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+async function createBundleDir(outputRoot, phase, commandName, date) {
+  await validateOutputRootForWriting(outputRoot);
+  await mkdir(outputRoot, { recursive: true });
+  await validateOutputRootForWriting(outputRoot);
+  await access(outputRoot, fsConstants.W_OK);
+  const baseName = `${formatTimestampForPath(date)}-${phase}-${commandName}`;
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const suffix = attempt === 0 ? '' : `-${attempt}`;
+    const bundleDir = path.join(outputRoot, `${baseName}${suffix}`);
+    try {
+      await mkdir(bundleDir, { recursive: false, mode: BUNDLE_DIR_MODE });
+      await chmod(bundleDir, BUNDLE_DIR_MODE);
+      return bundleDir;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw error;
+      }
+    }
+  }
+  throw new Error(`无法创建唯一证据目录: ${path.join(outputRoot, baseName)}`);
+}
+
+async function validateOutputRootForWriting(outputRoot) {
+  const target = path.resolve(outputRoot);
+  const root = path.parse(target).root;
+  let current = root;
+  const segments = path
+    .relative(root, target)
+    .split(path.sep)
+    .filter(Boolean);
+
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    let stats;
+    try {
+      stats = await lstat(current);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        return;
+      }
+      throw error;
+    }
+
+    if (stats.isSymbolicLink()) {
+      if (current === target) {
+        throw new Error(`--output-root 不能是符号链接: ${current}`);
+      }
+      throw new Error(`--output-root 上级目录不能是符号链接: ${current}`);
+    }
+
+    if (!stats.isDirectory()) {
+      if (current === target) {
+        throw new Error(`--output-root 已存在但不是目录: ${current}`);
+      }
+      throw new Error(`--output-root 上级路径已存在但不是目录: ${current}`);
+    }
+  }
+}
+
+async function writeEvidenceFile(filePath, content) {
+  await writeFile(filePath, content, {
+    encoding: 'utf8',
+    flag: 'wx',
+    mode: EVIDENCE_FILE_MODE,
+  });
+  await chmod(filePath, EVIDENCE_FILE_MODE);
+}
+
+async function buildEvidenceFileMetadata(filePath) {
+  const [stats, content] = await Promise.all([stat(filePath), readFile(filePath)]);
+  return {
+    path: path.basename(filePath),
+    sizeBytes: stats.size,
+    sha256: createHash('sha256').update(content).digest('hex'),
+  };
+}
+
+function runCommand(command, args, secrets) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: process.cwd(),
+      env: process.env,
+      shell: false,
+      windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    let spawnError = '';
+
+    child.stdout?.on('data', (chunk) => {
+      const text = String(chunk);
+      stdout += text;
+      process.stdout.write(redactSecrets(text, secrets));
+    });
+    child.stderr?.on('data', (chunk) => {
+      const text = String(chunk);
+      stderr += text;
+      process.stderr.write(redactSecrets(text, secrets));
+    });
+    child.on('error', (error) => {
+      spawnError = error.message;
+    });
+    child.on('close', (exitCode, signal) => {
+      resolve({
+        exitCode,
+        signal: signal || null,
+        error: spawnError,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+function collectSecretValues(args, env) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const inlineValue = getInlineSecretFlagValue(args[index]);
+    if (inlineValue) {
+      values.push(inlineValue);
+      continue;
+    }
+    if (index > 0 && SECRET_VALUE_FLAGS.has(args[index - 1]) && args[index]) {
+      values.push(args[index]);
+    }
+  }
+  for (const key of SECRET_ENV_KEYS) {
+    const value = String(env[key] || '');
+    if (value) {
+      values.push(value);
+    }
+  }
+  return [...new Set(values)].filter((value) => value.length >= 4);
+}
+
+function redactSecrets(text, secrets) {
+  let redacted = String(text || '');
+  for (const secret of secrets) {
+    redacted = redacted.split(secret).join('<redacted>');
+  }
+  return redacted;
+}
+
+function formatCommand(command, args, secrets) {
+  return [redactSecrets(command, secrets), ...redactSecretArgs(args, secrets)].join(' ');
+}
+
+function redactSecretArgs(args, secrets = []) {
+  return args.map((arg, index) => {
+    const redacted =
+      index > 0 && SECRET_VALUE_FLAGS.has(args[index - 1])
+      ? '<redacted>'
+      : redactInlineSecretArg(arg);
+    return redactSecrets(redacted, secrets);
+  });
+}
+
+function getInlineSecretFlagValue(arg) {
+  const text = String(arg || '');
+  for (const flag of SECRET_VALUE_FLAGS) {
+    const prefix = `${flag}=`;
+    if (text.startsWith(prefix)) {
+      return text.slice(prefix.length);
+    }
+  }
+  return '';
+}
+
+function redactInlineSecretArg(arg) {
+  const text = String(arg || '');
+  for (const flag of SECRET_VALUE_FLAGS) {
+    if (text.startsWith(`${flag}=`)) {
+      return `${flag}=<redacted>`;
+    }
+  }
+  return arg;
+}
+
+function formatTimestampForPath(date) {
+  return date
+    .toISOString()
+    .replace(/[-:]/gu, '')
+    .replace(/\.\d{3}Z$/u, 'Z');
+}
diff --git a/scripts/ops/pingora-cutover-evidence-audit.mjs b/scripts/ops/pingora-cutover-evidence-audit.mjs
new file mode 100644
index 000000000..43b73eba2
--- /dev/null
+++ b/scripts/ops/pingora-cutover-evidence-audit.mjs
@@ -0,0 +1,2035 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access, lstat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_EVIDENCE_ROOT = '/var/log/genarrative/pingora-cutover-evidence';
+const DEFAULT_CUTOVER_TIMELINE_MAX_SPAN_MS = 24 * 60 * 60 * 1000;
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const CUTOVER_TIMELINE_ORDER = [
+  { type: 'phase', phase: 'pre-cutover' },
+  {
+    type: 'command',
+    phase: 'enable-apply',
+    commandName: 'pingora-direct-enable-apply',
+  },
+  {
+    type: 'command',
+    phase: 'post-enable',
+    commandName: 'pingora-health-patrol-direct-env-switch',
+  },
+  { type: 'phase', phase: 'post-enable' },
+  {
+    type: 'command',
+    phase: 'rollback-prep',
+    commandName: 'pingora-gateway-shadow-env-switch',
+  },
+  {
+    type: 'command',
+    phase: 'rollback-prep',
+    commandName: 'pingora-health-patrol-nginx-env-switch',
+  },
+  {
+    type: 'command',
+    phase: 'rollback-apply',
+    commandName: 'pingora-direct-rollback-apply',
+  },
+  { type: 'phase', phase: 'post-rollback' },
+];
+
+const config = parseArgs(process.argv.slice(2));
+await validateReadOnlyDirectory(config.evidenceRoot, '--evidence-root');
+await validateVerifierScript(config.verifyScript);
+
+const discovery = await discoverEvidence(config.evidenceRoot, {
+  allowExtraRootEntries: config.allowExtraRootEntries,
+});
+const audit = await buildAudit(config, discovery);
+
+console.log(`${JSON.stringify(audit, null, 2)}\n`);
+
+if (!audit.ok) {
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const result = {
+    evidenceRoot:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_ROOT ||
+      DEFAULT_EVIDENCE_ROOT,
+    verifyScript:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_VERIFY_SCRIPT ||
+      path.join(SCRIPT_DIR, 'pingora-cutover-evidence-verify.mjs'),
+    timelineMaxSpanMs: parsePositiveInteger(
+      process.env.GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS ||
+        DEFAULT_CUTOVER_TIMELINE_MAX_SPAN_MS,
+      'GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS',
+    ),
+    requiredCutoverRunId:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_RUN_ID || '',
+    allowExtraRootEntries: false,
+    requiredPhases: [],
+    requiredPhaseDirectLiveAccessLog: [],
+    requiredPhaseDirectLiveStaticHeaders: [],
+    requiredPhasePingoraEnvShadow: [],
+    requiredCommands: [],
+    requiredCommandExecutables: [],
+    requiredCommandArgs: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--evidence-root':
+        result.evidenceRoot = requireValue(argv, ++index, arg);
+        break;
+      case '--verify-script':
+        result.verifyScript = requireValue(argv, ++index, arg);
+        break;
+      case '--phase':
+      case '--require-phase':
+        result.requiredPhases.push(requireValue(argv, ++index, arg));
+        break;
+      case '--require-command':
+        result.requiredCommands.push(requireValue(argv, ++index, arg));
+        break;
+      case '--require-phase-direct-live-access-log':
+        result.requiredPhaseDirectLiveAccessLog.push(
+          requireValue(argv, ++index, arg),
+        );
+        break;
+      case '--require-phase-direct-live-static-headers':
+        result.requiredPhaseDirectLiveStaticHeaders.push(
+          requireValue(argv, ++index, arg),
+        );
+        break;
+      case '--require-phase-pingora-env-shadow':
+        result.requiredPhasePingoraEnvShadow.push(
+          requireValue(argv, ++index, arg),
+        );
+        break;
+      case '--require-command-executable':
+        result.requiredCommandExecutables.push(requireValue(argv, ++index, arg));
+        break;
+      case '--require-command-arg':
+        result.requiredCommandArgs.push(requireValue(argv, ++index, arg));
+        break;
+      case '--timeline-max-span-ms':
+        result.timelineMaxSpanMs = parsePositiveInteger(
+          requireValue(argv, ++index, arg),
+          '--timeline-max-span-ms',
+        );
+        break;
+      case '--require-cutover-run-id':
+        result.requiredCutoverRunId = requireValue(argv, ++index, arg);
+        break;
+      case '--allow-extra-root-entries':
+        result.allowExtraRootEntries = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  for (const [label, value] of [
+    ['--evidence-root', result.evidenceRoot],
+    ['--verify-script', result.verifyScript],
+  ]) {
+    if (!path.isAbsolute(value)) {
+      throw new Error(`${label} 必须是绝对路径。`);
+    }
+    if (isFilesystemRootPath(value)) {
+      throw new Error(`${label} 不能是文件系统根目录。`);
+    }
+    validateNoControlCharacters(value, label);
+  }
+  result.requiredPhases = normalizeRequiredPhases(result.requiredPhases);
+  result.requiredPhaseDirectLiveAccessLog = normalizeRequiredPhases(
+    result.requiredPhaseDirectLiveAccessLog,
+  );
+  result.requiredPhaseDirectLiveStaticHeaders = normalizeRequiredPhases(
+    result.requiredPhaseDirectLiveStaticHeaders,
+  );
+  result.requiredPhasePingoraEnvShadow = normalizeRequiredPhases(
+    result.requiredPhasePingoraEnvShadow,
+  );
+  const requiredCommands = normalizeRequiredCommands(result.requiredCommands);
+  result.requiredCommandExecutables = normalizeRequiredCommandExecutables(
+    result.requiredCommandExecutables,
+  );
+  result.requiredCommandArgs = normalizeRequiredCommandArgs(
+    result.requiredCommandArgs,
+  );
+  result.requiredCommands = mergeRequiredCommands(
+    requiredCommands,
+    result.requiredCommandExecutables,
+    result.requiredCommandArgs,
+  );
+  if (result.requiredCutoverRunId) {
+    validateSafeCutoverRunId(
+      result.requiredCutoverRunId,
+      '--require-cutover-run-id',
+    );
+  }
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/ops/pingora-cutover-evidence-audit.mjs [options]
+
+Options:
+  --evidence-root <path>  证据根目录，默认 ${DEFAULT_EVIDENCE_ROOT}。
+  --verify-script <path>  证据验真脚本，默认同目录 pingora-cutover-evidence-verify.mjs。
+  --require-phase <name>  要求并验真某个阶段的最新证据；可重复。--phase 是别名。
+  --require-command <phase>:<commandName>
+                         要求并验真某个切换命令证据；可重复。
+  --require-phase-direct-live-access-log <phase>
+                         要求某个阶段 manifest.summary.directLiveAccessLog 已存在且 direct live request_id access log 对账成功；正式切换默认用于 post-enable。
+  --require-phase-direct-live-static-headers <phase>
+                         要求某个阶段 manifest.summary.directLiveStaticHeaders 已存在且包含可判定的 direct live 静态响应头摘要；正式切换默认用于 post-enable。
+  --require-phase-pingora-env-shadow <phase>
+                         要求某个阶段 manifest.summary.pingoraEnvShadow 已存在且证明 Pingora env 已恢复 shadow 高端口；正式切换默认用于 post-rollback。
+  --require-command-executable <phase>:<commandName>:<absolutePath>
+                         要求某个命令证据的 manifest.expectedExecutable、manifest.command.executable 和 command-record.json executable 与该绝对路径一致；可重复。
+  --require-command-arg <phase>:<commandName>:<arg>
+                         要求某个命令证据的 manifest.command.args 和 command-record.json args 都包含该参数；可重复。
+  --timeline-max-span-ms <ms>
+                         标准五段切换时间线允许的最大跨度，默认 ${DEFAULT_CUTOVER_TIMELINE_MAX_SPAN_MS}ms，可用 GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS 覆盖。
+  --require-cutover-run-id <id>
+                         只接受 manifest.cutoverRunId 与该 ID 一致的阶段和命令证据，避免混入其它切换批次。
+  --allow-extra-root-entries
+                         允许证据根目录中存在非证据目录条目；默认拒绝，正式切换归档不应使用。
+
+该脚本只读扫描 Pingora 直连切换证据根目录，按 manifest.phase 找到每个阶段的最新证据目录，也可按 manifest.phase + manifest.commandName 找到真实切换命令证据，并调用随包证据验真脚本的 --require-summary-ok 严格模式校验 schemaVersion=1 manifest.files 的 sizeBytes / sha256 与 manifest.summary.status=OK；所有候选证据都必须带合法 manifest.generatedAt，最新证据选择和标准时间线证明只使用该字段，不用目录 mtime 兜底；若同一阶段或同一命令的最新 manifest.generatedAt 重复，则拒绝按目录名打平并要求重新归档或清理证据根目录；命令证据的 manifest.command 与 command-record.json 也必须是 schemaVersion=1；可用 --require-phase-direct-live-access-log 要求指定阶段必须带 direct live access log 对账摘要，防止旧 post-enable 证据包缺少 request_id 反查复盘入口；可用 --require-phase-direct-live-static-headers 要求指定阶段必须带 direct live 静态响应头摘要，防止旧 post-enable 证据包缺少 Cache-Control、ETag、Last-Modified、Range 和 304 复盘入口；可用 --require-phase-pingora-env-shadow 要求指定阶段必须带 Pingora env shadow 摘要，防止旧 post-rollback 证据包无法证明 active env 已从低端口 direct 恢复到 127.0.0.1:18081；证据根目录默认只能包含带 manifest.json 的证据目录，不允许夹带普通文件、无 manifest 目录或符号链接；不会修改证据目录、不会 reload systemd、不会访问 Nginx 或 Pingora。
+`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function normalizeRequiredPhases(phases) {
+  const seen = new Set();
+  const normalized = [];
+  for (const phase of phases) {
+    const text = String(phase || '').trim();
+    validateSafePhase(text, '--require-phase');
+    if (!seen.has(text)) {
+      seen.add(text);
+      normalized.push(text);
+    }
+  }
+  return normalized;
+}
+
+function normalizeRequiredCommands(commands) {
+  const seen = new Set();
+  const normalized = [];
+  for (const command of commands) {
+    const text = String(command || '').trim();
+    const parts = text.split(':');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      throw new Error(
+        '--require-command 必须使用 <phase>:<commandName> 格式。',
+      );
+    }
+    const [phase, commandName] = parts;
+    validateSafePhase(phase, '--require-command phase');
+    validateSafeCommandName(commandName, '--require-command commandName');
+    const key = `${phase}:${commandName}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      normalized.push({ phase, commandName });
+    }
+  }
+  return normalized;
+}
+
+function normalizeRequiredCommandExecutables(commandExecutables) {
+  const seen = new Map();
+  const normalized = [];
+  for (const item of commandExecutables) {
+    const text = String(item || '').trim();
+    const parts = text.split(':');
+    if (parts.length < 3 || !parts[0] || !parts[1]) {
+      throw new Error(
+        '--require-command-executable 必须使用 <phase>:<commandName>:<absolutePath> 格式。',
+      );
+    }
+    const [phase, commandName, ...pathParts] = parts;
+    const executable = pathParts.join(':');
+    validateSafePhase(phase, '--require-command-executable phase');
+    validateSafeCommandName(
+      commandName,
+      '--require-command-executable commandName',
+    );
+    if (!path.isAbsolute(executable)) {
+      throw new Error('--require-command-executable executable 必须是绝对路径。');
+    }
+    if (isFilesystemRootPath(executable)) {
+      throw new Error(
+        '--require-command-executable executable 不能是文件系统根目录。',
+      );
+    }
+    if (/[\0\r\n]/u.test(executable)) {
+      throw new Error(
+        '--require-command-executable executable 不能包含换行或 NUL 字符。',
+      );
+    }
+    const key = `${phase}:${commandName}`;
+    const previousExecutable = seen.get(key);
+    if (previousExecutable && previousExecutable !== executable) {
+      throw new Error(
+        '--require-command-executable 不能为同一个 <phase>:<commandName> 指定多个不同路径。',
+      );
+    }
+    if (!previousExecutable) {
+      seen.set(key, executable);
+      normalized.push({ phase, commandName, executable });
+    }
+  }
+  return normalized;
+}
+
+function normalizeRequiredCommandArgs(commandArgs) {
+  const seen = new Set();
+  const normalized = [];
+  for (const item of commandArgs) {
+    const text = String(item || '').trim();
+    const parts = text.split(':');
+    if (parts.length < 3 || !parts[0] || !parts[1]) {
+      throw new Error(
+        '--require-command-arg 必须使用 <phase>:<commandName>:<arg> 格式。',
+      );
+    }
+    const [phase, commandName, ...argParts] = parts;
+    const requiredArg = argParts.join(':');
+    validateSafePhase(phase, '--require-command-arg phase');
+    validateSafeCommandName(commandName, '--require-command-arg commandName');
+    validateRequiredCommandArg(requiredArg, '--require-command-arg arg');
+    const key = `${phase}:${commandName}:${requiredArg}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      normalized.push({ phase, commandName, arg: requiredArg });
+    }
+  }
+  return normalized;
+}
+
+function mergeRequiredCommands(
+  requiredCommands,
+  requiredCommandExecutables,
+  requiredCommandArgs,
+) {
+  const seen = new Set();
+  const merged = [];
+  for (const command of [
+    ...requiredCommands,
+    ...requiredCommandExecutables,
+    ...requiredCommandArgs,
+  ]) {
+    const key = `${command.phase}:${command.commandName}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      merged.push({
+        phase: command.phase,
+        commandName: command.commandName,
+      });
+    }
+  }
+  return merged;
+}
+
+function findRequiredCommandExecutable(requiredCommandExecutables, command) {
+  return (
+    requiredCommandExecutables.find(
+      (item) =>
+        item.phase === command.phase && item.commandName === command.commandName,
+    )?.executable || null
+  );
+}
+
+function findRequiredCommandArgs(requiredCommandArgs, command) {
+  return requiredCommandArgs
+    .filter(
+      (item) =>
+        item.phase === command.phase && item.commandName === command.commandName,
+    )
+    .map((item) => item.arg);
+}
+
+function validateSafePhase(value, label) {
+  if (!isSafePhase(value)) {
+    throw new Error(
+      `${label} 只能包含 ASCII 字母、数字、点、下划线或短横线。`,
+    );
+  }
+}
+
+function validateSafeCommandName(value, label) {
+  if (!isSafePhase(value)) {
+    throw new Error(
+      `${label} 只能包含 ASCII 字母、数字、点、下划线或短横线。`,
+    );
+  }
+}
+
+function validateSafeCutoverRunId(value, label) {
+  if (!isSafePhase(value)) {
+    throw new Error(
+      `${label} 只能包含 ASCII 字母、数字、点、下划线或短横线。`,
+    );
+  }
+}
+
+function validateRequiredCommandArg(value, label) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    /[\0\r\n]/u.test(value)
+  ) {
+    throw new Error(`${label} 必须是非空且不包含换行的字符串。`);
+  }
+}
+
+function isSafePhase(value) {
+  return /^[0-9A-Za-z._-]+$/u.test(String(value || ''));
+}
+
+function parsePositiveInteger(value, label) {
+  const text = String(value || '').trim();
+  if (!/^[1-9]\d*$/u.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`${label} 超出 JavaScript 安全整数范围。`);
+  }
+  return parsed;
+}
+
+async function validateReadOnlyDirectory(dirPath, label) {
+  const stats = await lstat(dirPath);
+  if (stats.isSymbolicLink()) {
+    throw new Error(`${label} 不能是符号链接: ${dirPath}`);
+  }
+  if (!stats.isDirectory()) {
+    throw new Error(`${label} 必须是目录: ${dirPath}`);
+  }
+  await access(dirPath, fsConstants.R_OK | fsConstants.X_OK);
+}
+
+async function validateVerifierScript(scriptPath) {
+  const stats = await lstat(scriptPath);
+  if (stats.isSymbolicLink()) {
+    throw new Error(`--verify-script 不能是符号链接: ${scriptPath}`);
+  }
+  if (!stats.isFile()) {
+    throw new Error(`--verify-script 必须是文件: ${scriptPath}`);
+  }
+  await access(scriptPath, fsConstants.R_OK);
+}
+
+async function discoverEvidence(evidenceRoot, options = {}) {
+  const allowExtraRootEntries = Boolean(options.allowExtraRootEntries);
+  const entries = await readdir(evidenceRoot, { withFileTypes: true });
+  const candidates = [];
+  const diagnostics = [];
+
+  for (const entry of entries) {
+    const entryPath = path.join(evidenceRoot, entry.name);
+    const linkStats = await lstat(entryPath);
+    if (linkStats.isSymbolicLink()) {
+      if (!allowExtraRootEntries) {
+        diagnostics.push({
+          path: entry.name,
+          status: 'CRITICAL',
+          reason: '证据根目录下不能包含符号链接条目。',
+        });
+      }
+      continue;
+    }
+    if (!linkStats.isDirectory()) {
+      if (!allowExtraRootEntries) {
+        diagnostics.push({
+          path: entry.name,
+          status: 'CRITICAL',
+          reason: linkStats.isFile()
+            ? '证据根目录只能包含证据目录，发现普通文件。'
+            : '证据根目录只能包含证据目录，发现非目录条目。',
+        });
+      }
+      continue;
+    }
+
+    const manifestPath = path.join(entryPath, 'manifest.json');
+    let manifestStats;
+    try {
+      manifestStats = await lstat(manifestPath);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        if (!allowExtraRootEntries) {
+          diagnostics.push({
+            path: entry.name,
+            status: 'CRITICAL',
+            reason: '证据根目录只能包含带 manifest.json 的证据目录。',
+          });
+        }
+      } else {
+        diagnostics.push({
+          path: entry.name,
+          status: 'CRITICAL',
+          reason: `读取 manifest 状态失败: ${error.message}`,
+        });
+      }
+      continue;
+    }
+    if (manifestStats.isSymbolicLink()) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason: 'manifest 不能是符号链接。',
+      });
+      continue;
+    }
+    if (!manifestStats.isFile()) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason: 'manifest 必须是普通文件。',
+      });
+      continue;
+    }
+
+    const manifest = await readJsonManifest(manifestPath, entry.name, diagnostics);
+    if (!manifest) {
+      continue;
+    }
+    if (manifest.schemaVersion !== 1) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason: 'manifest.schemaVersion 必须是 1。',
+      });
+      continue;
+    }
+    if (!manifest.phase || typeof manifest.phase !== 'string') {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason: 'manifest 缺少 phase 字符串。',
+      });
+      continue;
+    }
+    if (!isSafePhase(manifest.phase)) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason:
+          'manifest.phase 只能包含 ASCII 字母、数字、点、下划线或短横线。',
+      });
+      continue;
+    }
+    const topLevelCommandName =
+      manifest.commandName === undefined ? null : manifest.commandName;
+    const embeddedCommandName =
+      manifest.command?.name === undefined ? null : manifest.command.name;
+    if (
+      topLevelCommandName !== null &&
+      (typeof topLevelCommandName !== 'string' ||
+        !isSafePhase(topLevelCommandName))
+    ) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason:
+          'manifest.commandName 只能包含 ASCII 字母、数字、点、下划线或短横线。',
+      });
+      continue;
+    }
+    if (
+      embeddedCommandName !== null &&
+      (typeof embeddedCommandName !== 'string' ||
+        !isSafePhase(embeddedCommandName))
+    ) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason:
+          'manifest.command.name 只能包含 ASCII 字母、数字、点、下划线或短横线。',
+      });
+      continue;
+    }
+    if (
+      topLevelCommandName !== null &&
+      embeddedCommandName !== null &&
+      topLevelCommandName !== embeddedCommandName
+    ) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason: `manifest.commandName 与 manifest.command.name 必须一致，manifest.commandName=${formatNullable(topLevelCommandName)}，manifest.command.name=${formatNullable(embeddedCommandName)}。`,
+      });
+      continue;
+    }
+    const commandName = topLevelCommandName || embeddedCommandName;
+    const cutoverRunId =
+      manifest.cutoverRunId === undefined ? null : manifest.cutoverRunId;
+    if (
+      cutoverRunId !== null &&
+      (typeof cutoverRunId !== 'string' || !isSafePhase(cutoverRunId))
+    ) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason:
+          'manifest.cutoverRunId 只能包含 ASCII 字母、数字、点、下划线或短横线。',
+      });
+      continue;
+    }
+    const topLevelExpectedExecutable =
+      manifest.expectedExecutable === undefined
+        ? null
+        : manifest.expectedExecutable;
+    const embeddedExpectedExecutable =
+      manifest.command?.expectedExecutable === undefined
+        ? null
+        : manifest.command.expectedExecutable;
+    const expectedExecutableDiagnostics = [
+      ...validateOptionalAbsolutePath(
+        topLevelExpectedExecutable,
+        'manifest.expectedExecutable',
+      ),
+      ...validateOptionalAbsolutePath(
+        embeddedExpectedExecutable,
+        'manifest.command.expectedExecutable',
+      ),
+    ];
+    if (expectedExecutableDiagnostics.length > 0) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason: expectedExecutableDiagnostics.join(' '),
+      });
+      continue;
+    }
+    const generatedAt = normalizeIsoTime(manifest.generatedAt);
+    if (!generatedAt) {
+      diagnostics.push({
+        path: entry.name,
+        manifestPath,
+        status: 'CRITICAL',
+        reason:
+          'manifest.generatedAt 必须是合法 ISO 时间；证据最新选择和时间线证明不能依赖目录 mtime。',
+      });
+      continue;
+    }
+    candidates.push({
+      phase: manifest.phase,
+      cutoverRunId,
+      bundleDir: entryPath,
+      manifestPath,
+      directoryName: entry.name,
+      generatedAt,
+      summaryStatus: manifest.summary?.status || null,
+      summaryExitCode: manifest.summary?.exitCode ?? null,
+      summarySignal: manifest.summary?.signal ?? null,
+      summaryDirectLiveAccessLog: manifest.summary?.directLiveAccessLog ?? null,
+      summaryDirectLiveStaticHeaders:
+        manifest.summary?.directLiveStaticHeaders ?? null,
+      summaryPingoraEnvShadow: manifest.summary?.pingoraEnvShadow ?? null,
+      commandName,
+      manifestCommand: manifest.command || null,
+      commandRecordFileName: manifest.files?.commandRecord?.path || null,
+      stdoutFileName: manifest.files?.stdout?.path || null,
+      stderrFileName: manifest.files?.stderr?.path || null,
+      commandStartedAt: normalizeIsoTime(manifest.command?.startedAt),
+      commandFinishedAt: normalizeIsoTime(manifest.command?.finishedAt),
+      commandDurationMs: manifest.command?.durationMs ?? null,
+      expectedExecutable:
+        topLevelExpectedExecutable ?? embeddedExpectedExecutable ?? null,
+      executable: manifest.command?.executable || null,
+    });
+  }
+
+  return { candidates, diagnostics };
+}
+
+function validateOptionalAbsolutePath(value, label) {
+  if (value === null) {
+    return [];
+  }
+  return validateRequiredAbsolutePath(value, label);
+}
+
+function validateRequiredAbsolutePath(value, label) {
+  if (typeof value !== 'string' || value.length === 0) {
+    return [`${label} 必须是绝对路径字符串。`];
+  }
+  if (!path.isAbsolute(value)) {
+    return [`${label} 必须是绝对路径。`];
+  }
+  if (isFilesystemRootPath(value)) {
+    return [`${label} 不能是文件系统根目录。`];
+  }
+  if (/[\0\r\n]/u.test(value)) {
+    return [`${label} 不能包含换行或 NUL 字符。`];
+  }
+  return [];
+}
+
+async function readJsonManifest(manifestPath, directoryName, diagnostics) {
+  let content;
+  try {
+    content = await readFile(manifestPath, 'utf8');
+  } catch (error) {
+    diagnostics.push({
+      path: directoryName,
+      manifestPath,
+      status: 'CRITICAL',
+      reason: `读取 manifest 失败: ${error.message}`,
+    });
+    return null;
+  }
+  try {
+    const manifest = JSON.parse(content);
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+      diagnostics.push({
+        path: directoryName,
+        manifestPath,
+        status: 'CRITICAL',
+        reason: 'manifest 顶层必须是 JSON object。',
+      });
+      return null;
+    }
+    return manifest;
+  } catch (error) {
+    diagnostics.push({
+      path: directoryName,
+      manifestPath,
+      status: 'CRITICAL',
+      reason: `manifest 不是合法 JSON: ${error.message}`,
+    });
+    return null;
+  }
+}
+
+async function buildAudit(config, discovery) {
+  const phasesToCheck =
+    config.requiredPhases.length > 0
+      ? config.requiredPhases
+      : config.requiredCommands.length > 0
+      ? []
+      : sortedUnique(
+          discovery.candidates
+            .filter((candidate) => candidate.commandName === null)
+            .map((candidate) => candidate.phase),
+        );
+  const phases = [];
+
+  for (const phase of phasesToCheck) {
+    const requiredAccessLog = config.requiredPhaseDirectLiveAccessLog.includes(
+      phase,
+    );
+    const requiredStaticHeaders = config.requiredPhaseDirectLiveStaticHeaders.includes(
+      phase,
+    );
+    const requiredPingoraEnvShadow = config.requiredPhasePingoraEnvShadow.includes(
+      phase,
+    );
+    const allPhaseCandidates = discovery.candidates.filter(
+      (candidate) => candidate.phase === phase && candidate.commandName === null,
+    );
+    const candidates = filterCandidatesByCutoverRunId(
+      allPhaseCandidates,
+      config.requiredCutoverRunId,
+    )
+      .sort(compareEvidenceCandidates);
+    if (candidates.length === 0) {
+      phases.push({
+        phase,
+        status: 'MISSING',
+        candidateCount: 0,
+        allCandidateCount: allPhaseCandidates.length,
+        requiredCutoverRunId: config.requiredCutoverRunId || null,
+        requiredDirectLiveAccessLog: requiredAccessLog,
+        requiredDirectLiveStaticHeaders: requiredStaticHeaders,
+        requiredPingoraEnvShadow,
+        directLiveAccessLog: null,
+        directLiveStaticHeaders: null,
+        pingoraEnvShadow: null,
+        diagnostics: [
+          missingEvidenceDiagnostic(
+            '该阶段',
+            config.requiredCutoverRunId,
+            allPhaseCandidates.length,
+          ),
+        ],
+      });
+      continue;
+    }
+
+    const latestSelection = selectUniqueLatestEvidence(candidates);
+    if (!latestSelection.ok) {
+      phases.push({
+        phase,
+        status: 'AMBIGUOUS_LATEST',
+        candidateCount: candidates.length,
+        allCandidateCount: allPhaseCandidates.length,
+        requiredCutoverRunId: config.requiredCutoverRunId || null,
+        generatedAt: latestSelection.generatedAt,
+        requiredDirectLiveAccessLog: requiredAccessLog,
+        requiredDirectLiveStaticHeaders: requiredStaticHeaders,
+        requiredPingoraEnvShadow,
+        directLiveAccessLog: null,
+        directLiveStaticHeaders: null,
+        pingoraEnvShadow: null,
+        ambiguousBundleDirs: latestSelection.ambiguousBundleDirs,
+        diagnostics: latestSelection.diagnostics,
+      });
+      continue;
+    }
+
+    const latest = latestSelection.latest;
+    const verify = await runVerifier(config.verifyScript, latest.bundleDir);
+    const manifestCheck = checkPhaseManifest(latest, {
+      requiredAccessLog,
+      requiredStaticHeaders,
+      requiredPingoraEnvShadow,
+    });
+    phases.push({
+      phase,
+      status: phaseStatus(verify, manifestCheck),
+      candidateCount: candidates.length,
+      latestBundleDir: latest.bundleDir,
+      manifestPath: latest.manifestPath,
+      cutoverRunId: latest.cutoverRunId,
+      requiredCutoverRunId: config.requiredCutoverRunId || null,
+      generatedAt: latest.generatedAt,
+      summaryStatus: latest.summaryStatus,
+      requiredDirectLiveAccessLog: requiredAccessLog,
+      requiredDirectLiveStaticHeaders: requiredStaticHeaders,
+      requiredPingoraEnvShadow,
+      directLiveAccessLog: latest.summaryDirectLiveAccessLog,
+      directLiveStaticHeaders: latest.summaryDirectLiveStaticHeaders,
+      pingoraEnvShadow: latest.summaryPingoraEnvShadow,
+      commandName: latest.commandName,
+      verify,
+      manifestCheck,
+      diagnostics: [
+        ...(verify.ok ? [] : ['最新证据目录 manifest 验真失败。']),
+        ...manifestCheck.diagnostics,
+      ],
+    });
+  }
+
+  const commands = [];
+  for (const requiredCommand of config.requiredCommands) {
+    const allCommandCandidates = discovery.candidates.filter(
+      (candidate) =>
+        candidate.phase === requiredCommand.phase &&
+        candidate.commandName === requiredCommand.commandName,
+    );
+    const candidates = filterCandidatesByCutoverRunId(
+      allCommandCandidates,
+      config.requiredCutoverRunId,
+    )
+      .sort(compareEvidenceCandidates);
+    if (candidates.length === 0) {
+      commands.push({
+        phase: requiredCommand.phase,
+        commandName: requiredCommand.commandName,
+        status: 'MISSING',
+        candidateCount: 0,
+        allCandidateCount: allCommandCandidates.length,
+        requiredCutoverRunId: config.requiredCutoverRunId || null,
+        diagnostics: [
+          missingEvidenceDiagnostic(
+            '该切换命令',
+            config.requiredCutoverRunId,
+            allCommandCandidates.length,
+          ),
+        ],
+      });
+      continue;
+    }
+
+    const latestSelection = selectUniqueLatestEvidence(candidates);
+    if (!latestSelection.ok) {
+      commands.push({
+        phase: requiredCommand.phase,
+        commandName: requiredCommand.commandName,
+        status: 'AMBIGUOUS_LATEST',
+        candidateCount: candidates.length,
+        allCandidateCount: allCommandCandidates.length,
+        requiredCutoverRunId: config.requiredCutoverRunId || null,
+        generatedAt: latestSelection.generatedAt,
+        ambiguousBundleDirs: latestSelection.ambiguousBundleDirs,
+        diagnostics: latestSelection.diagnostics,
+      });
+      continue;
+    }
+
+    const latest = latestSelection.latest;
+    const verify = await runVerifier(config.verifyScript, latest.bundleDir);
+    const expectedExecutable = findRequiredCommandExecutable(
+      config.requiredCommandExecutables,
+      requiredCommand,
+    );
+    const requiredArgs = findRequiredCommandArgs(
+      config.requiredCommandArgs,
+      requiredCommand,
+    );
+    const manifestCheck = await checkCommandManifest(
+      latest,
+      expectedExecutable,
+      requiredArgs,
+    );
+    commands.push({
+      phase: requiredCommand.phase,
+      commandName: requiredCommand.commandName,
+      status: commandStatus(verify, manifestCheck),
+      candidateCount: candidates.length,
+      latestBundleDir: latest.bundleDir,
+      manifestPath: latest.manifestPath,
+      cutoverRunId: latest.cutoverRunId,
+      requiredCutoverRunId: config.requiredCutoverRunId || null,
+      generatedAt: latest.generatedAt,
+      summaryStatus: latest.summaryStatus,
+      summaryExitCode: latest.summaryExitCode,
+      summarySignal: latest.summarySignal,
+      expectedExecutable: latest.expectedExecutable,
+      executable: latest.executable,
+      commandRecordPath: manifestCheck.commandRecordPath,
+      stdoutPath: manifestCheck.stdoutPath,
+      stderrPath: manifestCheck.stderrPath,
+      commandStartedAt: manifestCheck.commandRecordStartedAt,
+      commandFinishedAt: manifestCheck.commandRecordFinishedAt,
+      commandDurationMs: manifestCheck.commandRecordDurationMs,
+      requiredExecutable: expectedExecutable,
+      requiredArgs,
+      verify,
+      manifestCheck,
+      diagnostics: [
+        ...(verify.ok ? [] : ['最新命令证据目录 manifest 验真失败。']),
+        ...manifestCheck.diagnostics,
+      ],
+    });
+  }
+
+  const criticalDiagnostics = discovery.diagnostics.filter(
+    (item) => item.status === 'CRITICAL',
+  );
+  const timeline = buildTimelineAudit(
+    phases,
+    commands,
+    config.timelineMaxSpanMs,
+  );
+  const failedPhases = phases.filter((phase) => phase.status !== 'OK');
+  const failedCommands = commands.filter((command) => command.status !== 'OK');
+  const ok =
+    phases.length + commands.length > 0 &&
+    failedPhases.length === 0 &&
+    failedCommands.length === 0 &&
+    criticalDiagnostics.length === 0 &&
+    timeline.ok;
+
+  return {
+    ok,
+    generatedAt: new Date().toISOString(),
+    evidenceRoot: config.evidenceRoot,
+    verifyScript: config.verifyScript,
+    requiredCutoverRunId: config.requiredCutoverRunId || null,
+    allowExtraRootEntries: config.allowExtraRootEntries,
+    timelineMaxSpanMs: config.timelineMaxSpanMs,
+    requiredPhases: config.requiredPhases,
+    requiredCommands: config.requiredCommands,
+    requiredCommandExecutables: config.requiredCommandExecutables,
+    requiredCommandArgs: config.requiredCommandArgs,
+    discoveredCount: discovery.candidates.length,
+    checkedCount: phases.length + commands.length,
+    failedCount:
+      failedPhases.length +
+      failedCommands.length +
+      criticalDiagnostics.length +
+      timeline.failedCount,
+    diagnostics: discovery.diagnostics,
+    summary: buildOperatorSummary({
+      ok,
+      phases,
+      commands,
+      criticalDiagnostics,
+      timeline,
+      checkedCount: phases.length + commands.length,
+      failedCount:
+        failedPhases.length +
+        failedCommands.length +
+        criticalDiagnostics.length +
+        timeline.failedCount,
+    }),
+    timeline,
+    phases,
+    commands,
+  };
+}
+
+function buildOperatorSummary(input) {
+  const pingoraEnvShadowEvidence = input.phases
+    .filter((phase) => phase.requiredPingoraEnvShadow)
+    .map((phase) => {
+      const summary = phase.pingoraEnvShadow ?? null;
+      const firstDiagnostic = phase.diagnostics?.[0] ?? null;
+      return {
+        phase: phase.phase,
+        status: phase.status,
+        latestBundleDir: phase.latestBundleDir ?? null,
+        manifestPath: phase.manifestPath ?? null,
+        cutoverRunId: phase.cutoverRunId ?? null,
+        generatedAt: phase.generatedAt ?? null,
+        shadow: {
+          required: true,
+          ok: phase.manifestCheck?.pingoraEnvShadowCheck?.ok === true,
+          reason:
+            phase.manifestCheck?.pingoraEnvShadowCheck?.reason ??
+            firstDiagnostic,
+          summary,
+        },
+      };
+    });
+  const directLiveEvidence = input.phases
+    .filter(
+      (phase) =>
+        phase.requiredDirectLiveAccessLog ||
+        phase.requiredDirectLiveStaticHeaders,
+    )
+    .map((phase) => {
+      const accessLogRequired = phase.requiredDirectLiveAccessLog === true;
+      const staticHeadersRequired =
+        phase.requiredDirectLiveStaticHeaders === true;
+      const accessLogSummary = phase.directLiveAccessLog ?? null;
+      const staticHeadersSummary = phase.directLiveStaticHeaders ?? null;
+      const accessLogChecked = accessLogRequired || accessLogSummary !== null;
+      const staticHeadersChecked =
+        staticHeadersRequired || staticHeadersSummary !== null;
+      const firstDiagnostic = phase.diagnostics?.[0] ?? null;
+      return {
+        phase: phase.phase,
+        status: phase.status,
+        latestBundleDir: phase.latestBundleDir ?? null,
+        manifestPath: phase.manifestPath ?? null,
+        cutoverRunId: phase.cutoverRunId ?? null,
+        generatedAt: phase.generatedAt ?? null,
+        accessLog: {
+          required: accessLogRequired,
+          ok: accessLogChecked
+            ? phase.manifestCheck?.directLiveAccessLogCheck?.ok === true
+            : null,
+          reason: accessLogChecked
+            ? phase.manifestCheck?.directLiveAccessLogCheck?.reason ??
+              firstDiagnostic
+            : null,
+          summary: accessLogSummary,
+        },
+        staticHeaders: {
+          required: staticHeadersRequired,
+          ok: staticHeadersChecked
+            ? phase.manifestCheck?.directLiveStaticHeadersCheck?.ok === true
+            : null,
+          reason: staticHeadersChecked
+            ? phase.manifestCheck?.directLiveStaticHeadersCheck?.reason ??
+              firstDiagnostic
+            : null,
+          summary: staticHeadersSummary,
+        },
+      };
+    });
+
+  return {
+    status: input.ok ? 'OK' : 'CRITICAL',
+    checkedCount: input.checkedCount,
+    failedCount: input.failedCount,
+    failedItems: [
+      ...input.criticalDiagnostics.map((diagnostic) => ({
+        type: 'evidence-root',
+        status: diagnostic.status,
+        path: diagnostic.path ?? null,
+        manifestPath: diagnostic.manifestPath ?? null,
+        reason: diagnostic.reason ?? null,
+      })),
+      ...input.phases
+        .filter((phase) => phase.status !== 'OK')
+        .map((phase) => ({
+          type: 'phase',
+          phase: phase.phase,
+          status: phase.status,
+          latestBundleDir: phase.latestBundleDir ?? null,
+          manifestPath: phase.manifestPath ?? null,
+          cutoverRunId: phase.cutoverRunId ?? null,
+          generatedAt: phase.generatedAt ?? null,
+          diagnostics: phase.diagnostics ?? [],
+        })),
+      ...input.commands
+        .filter((command) => command.status !== 'OK')
+        .map((command) => ({
+          type: 'command',
+          phase: command.phase,
+          commandName: command.commandName,
+          status: command.status,
+          latestBundleDir: command.latestBundleDir ?? null,
+          manifestPath: command.manifestPath ?? null,
+          cutoverRunId: command.cutoverRunId ?? null,
+          generatedAt: command.generatedAt ?? null,
+          diagnostics: command.diagnostics ?? [],
+        })),
+      ...(input.timeline.ok
+        ? []
+        : [
+            {
+              type: 'timeline',
+              status: 'FAILED',
+              diagnostics: input.timeline.diagnostics ?? [],
+              failureBreakdown: input.timeline.failureBreakdown ?? null,
+              spanMs: input.timeline.spanMs ?? null,
+              maxSpanMs: input.timeline.maxSpanMs ?? null,
+            },
+          ]),
+    ],
+    pingoraEnvShadowEvidence,
+    directLiveEvidence,
+    timeline: {
+      checked: input.timeline.checked,
+      ok: input.timeline.ok,
+      failedCount: input.timeline.failedCount,
+      spanMs: input.timeline.spanMs,
+      maxSpanMs: input.timeline.maxSpanMs,
+      firstGeneratedAt: input.timeline.firstGeneratedAt,
+      lastGeneratedAt: input.timeline.lastGeneratedAt,
+    },
+  };
+}
+
+function filterCandidatesByCutoverRunId(candidates, requiredCutoverRunId) {
+  if (!requiredCutoverRunId) {
+    return candidates;
+  }
+  return candidates.filter(
+    (candidate) => candidate.cutoverRunId === requiredCutoverRunId,
+  );
+}
+
+function missingEvidenceDiagnostic(label, requiredCutoverRunId, allCandidateCount) {
+  if (!requiredCutoverRunId) {
+    return `没有找到${label}的证据 manifest。`;
+  }
+  if (allCandidateCount > 0) {
+    return `没有找到${label}且 cutoverRunId=${requiredCutoverRunId} 的证据 manifest；已有同名证据属于其它切换批次或缺少 cutoverRunId。`;
+  }
+  return `没有找到${label}的证据 manifest，无法满足 cutoverRunId=${requiredCutoverRunId}。`;
+}
+
+function selectUniqueLatestEvidence(candidates) {
+  const latest = candidates.at(-1);
+  const latestGeneratedAt = latest?.generatedAt || null;
+  const ambiguousCandidates = candidates.filter(
+    (candidate) => candidate.generatedAt === latestGeneratedAt,
+  );
+  if (ambiguousCandidates.length > 1) {
+    const ambiguousBundleDirs = ambiguousCandidates.map(
+      (candidate) => candidate.bundleDir,
+    );
+    return {
+      ok: false,
+      latest: null,
+      generatedAt: latestGeneratedAt,
+      ambiguousBundleDirs,
+      diagnostics: [
+        `最新证据 manifest.generatedAt=${latestGeneratedAt} 出现重复，不能按目录名打平选择；请重新归档或清理证据根目录。`,
+        `重复 generatedAt 的证据目录: ${ambiguousBundleDirs.join(', ')}`,
+      ],
+    };
+  }
+  return {
+    ok: true,
+    latest,
+    generatedAt: latestGeneratedAt,
+    ambiguousBundleDirs: [],
+    diagnostics: [],
+  };
+}
+
+function checkPhaseManifest(candidate, options = {}) {
+  const {
+    requiredAccessLog = false,
+    requiredStaticHeaders = false,
+    requiredPingoraEnvShadow = false,
+  } = options;
+  const diagnostics = [];
+  if (candidate.commandName !== null) {
+    diagnostics.push(
+      `最新阶段证据不能带 manifest.commandName，实际为 ${formatNullable(candidate.commandName)}。`,
+    );
+  }
+  if (candidate.summaryStatus !== 'OK') {
+    diagnostics.push(
+      `最新阶段证据 manifest.summary.status 必须是 OK，实际为 ${formatNullable(candidate.summaryStatus)}。`,
+    );
+  }
+  const accessLogCheck = checkDirectLiveAccessLogSummary(
+    candidate.summaryDirectLiveAccessLog,
+  );
+  if (requiredAccessLog && !accessLogCheck.ok) {
+    diagnostics.push(
+      `最新阶段证据 manifest.summary.directLiveAccessLog 必须包含 direct live access log 对账摘要：${accessLogCheck.reason}`,
+    );
+  }
+  const staticHeadersCheck = checkDirectLiveStaticHeadersSummary(
+    candidate.summaryDirectLiveStaticHeaders,
+  );
+  if (requiredStaticHeaders && !staticHeadersCheck.ok) {
+    diagnostics.push(
+      `最新阶段证据 manifest.summary.directLiveStaticHeaders 必须包含 direct live 静态响应头摘要：${staticHeadersCheck.reason}`,
+    );
+  }
+  const pingoraEnvShadowCheck = checkPingoraEnvShadowSummary(
+    candidate.summaryPingoraEnvShadow,
+  );
+  if (requiredPingoraEnvShadow && !pingoraEnvShadowCheck.ok) {
+    diagnostics.push(
+      `最新阶段证据 manifest.summary.pingoraEnvShadow 必须证明 Pingora env 已恢复 shadow：${pingoraEnvShadowCheck.reason}`,
+    );
+  }
+  return {
+    ok: diagnostics.length === 0,
+    expectedSummaryStatus: 'OK',
+    actualSummaryStatus: candidate.summaryStatus,
+    requiredDirectLiveAccessLog: requiredAccessLog,
+    requiredDirectLiveStaticHeaders: requiredStaticHeaders,
+    requiredPingoraEnvShadow,
+    directLiveAccessLogCheck: accessLogCheck,
+    directLiveStaticHeadersCheck: staticHeadersCheck,
+    pingoraEnvShadowCheck,
+    diagnostics,
+  };
+}
+
+function checkPingoraEnvShadowSummary(summary) {
+  if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
+    return { ok: false, reason: '字段缺失或不是对象。' };
+  }
+  const failures = [];
+  if (summary.present !== true) {
+    failures.push('present 必须为 true');
+  }
+  if (summary.ok !== true) {
+    failures.push('ok 必须为 true');
+  }
+  if (summary.listen !== '127.0.0.1:18081') {
+    failures.push(
+      `listen 必须是 127.0.0.1:18081，实际为 ${formatNullable(summary.listen)}`,
+    );
+  }
+  if (summary.tlsListen !== '') {
+    failures.push(`tlsListen 必须为空，实际为 ${formatNullable(summary.tlsListen)}`);
+  }
+  if (summary.httpRedirectListen !== '') {
+    failures.push(
+      `httpRedirectListen 必须为空，实际为 ${formatNullable(summary.httpRedirectListen)}`,
+    );
+  }
+  if (summary.tlsCertFile !== '') {
+    failures.push(
+      `tlsCertFile 必须为空，实际为 ${formatNullable(summary.tlsCertFile)}`,
+    );
+  }
+  if (summary.tlsKeyFile !== '') {
+    failures.push(
+      `tlsKeyFile 必须为空，实际为 ${formatNullable(summary.tlsKeyFile)}`,
+    );
+  }
+  if (summary.mode && summary.mode !== 'shadow') {
+    failures.push(`mode 必须是 shadow，实际为 ${formatNullable(summary.mode)}`);
+  }
+  if (summary.shadowReady === false) {
+    failures.push('shadowReady 必须为 true');
+  }
+  return failures.length === 0
+    ? { ok: true, reason: null }
+    : { ok: false, reason: failures.join('；') };
+}
+
+function checkDirectLiveAccessLogSummary(summary) {
+  if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
+    return { ok: false, reason: '字段缺失或不是对象。' };
+  }
+  if (summary.present !== true) {
+    return { ok: false, reason: 'present 必须为 true。' };
+  }
+  const checked = Number(summary.checked);
+  const matchedCount = Number(summary.matchedCount);
+  const missingCount = Number(summary.missingCount);
+  const mismatchCount = Number(summary.mismatchCount);
+  const failures = [];
+  if (!Number.isInteger(checked) || checked <= 0) {
+    failures.push('checked 必须是正整数');
+  }
+  if (!Number.isInteger(matchedCount) || matchedCount !== checked) {
+    failures.push('matchedCount 必须等于 checked');
+  }
+  if (!Number.isInteger(missingCount) || missingCount !== 0) {
+    failures.push('missingCount 必须为 0');
+  }
+  if (!Number.isInteger(mismatchCount) || mismatchCount !== 0) {
+    failures.push('mismatchCount 必须为 0');
+  }
+  return failures.length === 0
+    ? { ok: true, reason: null }
+    : { ok: false, reason: failures.join('；') };
+}
+
+function checkDirectLiveStaticHeadersSummary(summary) {
+  if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
+    return { ok: false, reason: '字段缺失或不是对象。' };
+  }
+  if (summary.present !== true) {
+    return { ok: false, reason: 'present 必须为 true。' };
+  }
+  if (summary.skipped) {
+    return {
+      ok: false,
+      reason: `静态检查被跳过：${formatNullable(summary.skipReason)}`,
+    };
+  }
+  const targets = [summary.normal, summary.fingerprinted].filter(
+    (target) => target && target.present,
+  );
+  if (targets.length === 0) {
+    return { ok: false, reason: '缺少 normal 或 fingerprinted 静态资产摘要。' };
+  }
+  const failures = [];
+  for (const [label, target] of [
+    ['normal', summary.normal],
+    ['fingerprinted', summary.fingerprinted],
+  ]) {
+    if (!target || !target.present) {
+      continue;
+    }
+    if (target.ok !== true) {
+      failures.push(`${label}.ok 不是 true`);
+    }
+    for (const key of [
+      'cacheControl',
+      'etag',
+      'lastModified',
+      'acceptRanges',
+      'rangeContentRange',
+    ]) {
+      if (typeof target[key] !== 'string' || target[key].length === 0) {
+        failures.push(`${label}.${key} 缺失`);
+      }
+    }
+    if (target.rangeStatusCode !== 206) {
+      failures.push(`${label}.rangeStatusCode 不是 206`);
+    }
+    if (target.etag304StatusCode !== 304) {
+      failures.push(`${label}.etag304StatusCode 不是 304`);
+    }
+    if (target.lastModified304StatusCode !== 304) {
+      failures.push(`${label}.lastModified304StatusCode 不是 304`);
+    }
+  }
+  return failures.length === 0
+    ? { ok: true, reason: null }
+    : { ok: false, reason: failures.join('；') };
+}
+
+async function checkCommandManifest(
+  candidate,
+  expectedExecutable = null,
+  requiredArgs = [],
+) {
+  const diagnostics = [];
+  if (candidate.summaryStatus !== 'OK') {
+    diagnostics.push(
+      `最新命令证据 manifest.summary.status 必须是 OK，实际为 ${formatNullable(candidate.summaryStatus)}。`,
+    );
+  }
+  if (candidate.summaryExitCode !== 0) {
+    diagnostics.push(
+      `最新命令证据 manifest.summary.exitCode 必须是 0，实际为 ${formatNullable(candidate.summaryExitCode)}。`,
+    );
+  }
+  if (candidate.summarySignal !== null) {
+    diagnostics.push(
+      `最新命令证据 manifest.summary.signal 必须为空，实际为 ${formatNullable(candidate.summarySignal)}。`,
+    );
+  }
+  if (expectedExecutable) {
+    if (candidate.expectedExecutable !== expectedExecutable) {
+      diagnostics.push(
+        `最新命令证据 manifest.expectedExecutable 必须是 ${expectedExecutable}，实际为 ${formatNullable(candidate.expectedExecutable)}。`,
+      );
+    }
+    if (candidate.executable !== expectedExecutable) {
+      diagnostics.push(
+        `最新命令证据 command.executable 必须是 ${expectedExecutable}，实际为 ${formatNullable(candidate.executable)}。`,
+      );
+    }
+  }
+  diagnostics.push(...checkCommandOutputEvidenceFileNames(candidate));
+  const embeddedCommandCheck = checkCommandRecordObject(
+    candidate.manifestCommand,
+    'manifest.command',
+    candidate,
+    expectedExecutable,
+    requiredArgs,
+  );
+  diagnostics.push(...embeddedCommandCheck.diagnostics);
+
+  const commandRecordCheck = await readCommandRecord(candidate);
+  diagnostics.push(...commandRecordCheck.diagnostics);
+  if (commandRecordCheck.record) {
+    const fileCommandCheck = checkCommandRecordObject(
+      commandRecordCheck.record,
+      'command-record.json',
+      candidate,
+      expectedExecutable,
+      requiredArgs,
+    );
+    diagnostics.push(...fileCommandCheck.diagnostics);
+    if (embeddedCommandCheck.record) {
+      diagnostics.push(
+        ...compareCommandRecords(
+          embeddedCommandCheck.record,
+          commandRecordCheck.record,
+        ),
+      );
+    }
+  }
+  return {
+    ok: diagnostics.length === 0,
+    expectedSummaryStatus: 'OK',
+    actualSummaryStatus: candidate.summaryStatus,
+    expectedExitCode: 0,
+    actualExitCode: candidate.summaryExitCode,
+    expectedSignal: null,
+    actualSignal: candidate.summarySignal,
+    expectedExecutable,
+    actualExpectedExecutable: candidate.expectedExecutable,
+    actualExecutable: candidate.executable,
+    stdoutPath: candidate.stdoutFileName,
+    stderrPath: candidate.stderrFileName,
+    commandRecordStdoutPath: commandRecordCheck.record?.stdoutPath ?? null,
+    commandRecordStderrPath: commandRecordCheck.record?.stderrPath ?? null,
+    commandRecordPath: commandRecordCheck.path,
+    commandRecordReadOk: commandRecordCheck.ok,
+    commandRecordExpectedExecutable:
+      commandRecordCheck.record?.expectedExecutable ?? null,
+    commandRecordExecutable: commandRecordCheck.record?.executable ?? null,
+    commandRecordStartedAt: normalizeIsoTime(commandRecordCheck.record?.startedAt),
+    commandRecordFinishedAt: normalizeIsoTime(commandRecordCheck.record?.finishedAt),
+    commandRecordDurationMs: commandRecordCheck.record?.durationMs ?? null,
+    requiredArgs,
+    diagnostics,
+  };
+}
+
+function checkCommandOutputEvidenceFileNames(candidate) {
+  const diagnostics = [];
+  for (const [field, fileName] of [
+    ['stdout', candidate.stdoutFileName],
+    ['stderr', candidate.stderrFileName],
+  ]) {
+    if (!fileName) {
+      diagnostics.push(
+        `最新命令证据 manifest.files.${field}.path 必须存在。`,
+      );
+      continue;
+    }
+    if (!isSafeEvidenceFileName(fileName)) {
+      diagnostics.push(
+        `最新命令证据 manifest.files.${field}.path 只能是证据目录内的普通文件名，实际为 ${formatNullable(fileName)}。`,
+      );
+    }
+  }
+  return diagnostics;
+}
+
+async function readCommandRecord(candidate) {
+  const fileName = candidate.commandRecordFileName;
+  if (!fileName) {
+    return {
+      ok: false,
+      path: null,
+      record: null,
+      diagnostics: ['最新命令证据 manifest.files.commandRecord.path 必须存在。'],
+    };
+  }
+  if (!isSafeEvidenceFileName(fileName)) {
+    return {
+      ok: false,
+      path: null,
+      record: null,
+      diagnostics: [
+        `最新命令证据 manifest.files.commandRecord.path 只能是证据目录内的普通文件名，实际为 ${formatNullable(fileName)}。`,
+      ],
+    };
+  }
+
+  const recordPath = path.join(candidate.bundleDir, fileName);
+  try {
+    const stats = await lstat(recordPath);
+    if (stats.isSymbolicLink()) {
+      return {
+        ok: false,
+        path: recordPath,
+        record: null,
+        diagnostics: ['最新命令证据 command-record.json 不能是符号链接。'],
+      };
+    }
+    if (!stats.isFile()) {
+      return {
+        ok: false,
+        path: recordPath,
+        record: null,
+        diagnostics: ['最新命令证据 command-record.json 必须是普通文件。'],
+      };
+    }
+    const content = await readFile(recordPath, 'utf8');
+    const record = JSON.parse(content);
+    if (!record || typeof record !== 'object' || Array.isArray(record)) {
+      return {
+        ok: false,
+        path: recordPath,
+        record: null,
+        diagnostics: ['最新命令证据 command-record.json 顶层必须是 JSON object。'],
+      };
+    }
+    return { ok: true, path: recordPath, record, diagnostics: [] };
+  } catch (error) {
+    return {
+      ok: false,
+      path: recordPath,
+      record: null,
+      diagnostics: [
+        `读取最新命令证据 command-record.json 失败: ${error.message}`,
+      ],
+    };
+  }
+}
+
+function checkCommandRecordObject(
+  record,
+  label,
+  candidate,
+  expectedExecutable,
+  requiredArgs = [],
+) {
+  const diagnostics = [];
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    return {
+      ok: false,
+      record: null,
+      diagnostics: [`最新命令证据 ${label} 必须是 JSON object。`],
+    };
+  }
+  const checks = [
+    ['schemaVersion', 1],
+    ['phase', candidate.phase],
+    ['name', candidate.commandName],
+    ['exitCode', candidate.summaryExitCode],
+    ['signal', candidate.summarySignal],
+  ];
+  if (candidate.cutoverRunId !== null || record.cutoverRunId !== undefined) {
+    checks.push(['cutoverRunId', candidate.cutoverRunId]);
+  }
+  if (
+    candidate.expectedExecutable !== null ||
+    record.expectedExecutable !== undefined
+  ) {
+    checks.push(['expectedExecutable', candidate.expectedExecutable]);
+  }
+  for (const [field, expected] of checks) {
+    const actual = record[field] ?? null;
+    if (actual !== expected) {
+      diagnostics.push(
+        `最新命令证据 ${label}.${field} 必须是 ${formatNullable(expected)}，实际为 ${formatNullable(actual)}。`,
+      );
+    }
+  }
+  for (const [field, expected] of [
+    ['stdoutPath', candidate.stdoutFileName],
+    ['stderrPath', candidate.stderrFileName],
+  ]) {
+    const actual = record[field] ?? null;
+    if (actual !== expected) {
+      diagnostics.push(
+        `最新命令证据 ${label}.${field} 必须是 ${formatNullable(expected)}，实际为 ${formatNullable(actual)}。`,
+      );
+    }
+  }
+  diagnostics.push(...checkCommandRecordInvocation(record, label));
+  diagnostics.push(
+    ...validateRequiredAbsolutePath(record.executable, `${label}.executable`),
+  );
+  const effectiveExpectedExecutable =
+    expectedExecutable || candidate.expectedExecutable;
+  if (effectiveExpectedExecutable) {
+    if (record.expectedExecutable !== effectiveExpectedExecutable) {
+      diagnostics.push(
+        `最新命令证据 ${label}.expectedExecutable 必须是 ${effectiveExpectedExecutable}，实际为 ${formatNullable(record.expectedExecutable)}。`,
+      );
+    }
+    if (record.executable !== effectiveExpectedExecutable) {
+      diagnostics.push(
+        `最新命令证据 ${label}.executable 必须是 ${effectiveExpectedExecutable}，实际为 ${formatNullable(record.executable)}。`,
+      );
+    }
+  }
+  diagnostics.push(...checkRequiredCommandArgs(record, label, requiredArgs));
+  diagnostics.push(...checkCommandRecordTimes(record, label, candidate));
+  return {
+    ok: diagnostics.length === 0,
+    record,
+    diagnostics,
+  };
+}
+
+function checkRequiredCommandArgs(record, label, requiredArgs) {
+  const diagnostics = [];
+  if (requiredArgs.length === 0) {
+    return diagnostics;
+  }
+  if (!Array.isArray(record.args)) {
+    diagnostics.push(
+      `最新命令证据 ${label}.args 必须是字符串数组，才能校验必需参数 ${formatNullable(requiredArgs)}。`,
+    );
+    return diagnostics;
+  }
+  for (const requiredArg of requiredArgs) {
+    if (!record.args.includes(requiredArg)) {
+      diagnostics.push(
+        `最新命令证据 ${label}.args 必须包含 ${formatNullable(requiredArg)}。`,
+      );
+    }
+  }
+  return diagnostics;
+}
+
+function checkCommandRecordInvocation(record, label) {
+  const diagnostics = [];
+  if (!Array.isArray(record.args)) {
+    diagnostics.push(`最新命令证据 ${label}.args 必须是字符串数组。`);
+  } else if (record.args.some((item) => typeof item !== 'string')) {
+    diagnostics.push(`最新命令证据 ${label}.args 必须只包含字符串。`);
+  } else if (record.args.some((item) => /[\0\r\n]/u.test(item))) {
+    diagnostics.push(
+      `最新命令证据 ${label}.args 不能包含换行或 NUL 字符。`,
+    );
+  }
+  if (typeof record.command !== 'string' || record.command.length === 0) {
+    diagnostics.push(`最新命令证据 ${label}.command 必须是非空字符串。`);
+  }
+  if (typeof record.cwd !== 'string' || !path.isAbsolute(record.cwd)) {
+    diagnostics.push(`最新命令证据 ${label}.cwd 必须是绝对路径字符串。`);
+  }
+  if (record.error !== null && typeof record.error !== 'string') {
+    diagnostics.push(`最新命令证据 ${label}.error 必须是字符串或 null。`);
+  }
+  return diagnostics;
+}
+
+function checkCommandRecordTimes(record, label, candidate) {
+  const diagnostics = [];
+  const startedAt = normalizeIsoTime(record.startedAt);
+  const finishedAt = normalizeIsoTime(record.finishedAt);
+  if (!startedAt) {
+    diagnostics.push(`最新命令证据 ${label}.startedAt 必须是合法 ISO 时间。`);
+  }
+  if (!finishedAt) {
+    diagnostics.push(`最新命令证据 ${label}.finishedAt 必须是合法 ISO 时间。`);
+  }
+  if (startedAt && finishedAt) {
+    const startedMs = Date.parse(startedAt);
+    const finishedMs = Date.parse(finishedAt);
+    if (finishedMs < startedMs) {
+      diagnostics.push(
+        `最新命令证据 ${label}.finishedAt 不能早于 startedAt。`,
+      );
+    }
+    if (candidate.generatedAt) {
+      const generatedMs = Date.parse(candidate.generatedAt);
+      if (generatedMs < finishedMs) {
+        diagnostics.push(
+          `最新命令证据 manifest.generatedAt 不能早于 ${label}.finishedAt。`,
+        );
+      }
+    }
+    const durationMs = record.durationMs;
+    if (!Number.isSafeInteger(durationMs) || durationMs < 0) {
+      diagnostics.push(
+        `最新命令证据 ${label}.durationMs 必须是非负安全整数。`,
+      );
+    } else {
+      const actualDurationMs = finishedMs - startedMs;
+      if (durationMs !== actualDurationMs) {
+        diagnostics.push(
+          `最新命令证据 ${label}.durationMs 必须等于 finishedAt - startedAt，实际记录 ${durationMs}ms，计算值 ${actualDurationMs}ms。`,
+        );
+      }
+    }
+  }
+  return diagnostics;
+}
+
+function compareCommandRecords(embeddedRecord, fileRecord) {
+  const diagnostics = [];
+  const scalarFields = [
+    'schemaVersion',
+    'name',
+    'phase',
+    'cutoverRunId',
+    'expectedExecutable',
+    'executable',
+    'command',
+    'cwd',
+    'error',
+    'stdoutPath',
+    'stderrPath',
+    'exitCode',
+    'signal',
+  ];
+  for (const field of scalarFields) {
+    const embedded = embeddedRecord[field] ?? null;
+    const file = fileRecord[field] ?? null;
+    if (embedded !== file) {
+      diagnostics.push(
+        `最新命令证据 manifest.command.${field} 与 command-record.json.${field} 必须一致，manifest=${formatNullable(embedded)}，command-record=${formatNullable(file)}。`,
+      );
+    }
+  }
+  for (const field of ['args']) {
+    const embedded = embeddedRecord[field] ?? null;
+    const file = fileRecord[field] ?? null;
+    if (!jsonValuesEqual(embedded, file)) {
+      diagnostics.push(
+        `最新命令证据 manifest.command.${field} 与 command-record.json.${field} 必须一致，manifest=${formatNullable(embedded)}，command-record=${formatNullable(file)}。`,
+      );
+    }
+  }
+  return diagnostics;
+}
+
+function jsonValuesEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function phaseStatus(verify, manifestCheck) {
+  if (!manifestCheck.ok) {
+    return 'MANIFEST_FAILED';
+  }
+  if (!verify.ok) {
+    return 'VERIFY_FAILED';
+  }
+  return 'OK';
+}
+
+function commandStatus(verify, manifestCheck) {
+  if (!manifestCheck.ok) {
+    return 'MANIFEST_FAILED';
+  }
+  if (!verify.ok) {
+    return 'VERIFY_FAILED';
+  }
+  return 'OK';
+}
+
+function formatNullable(value) {
+  return value === null || value === undefined ? '<missing>' : JSON.stringify(value);
+}
+
+function isSafeEvidenceFileName(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    !/[\0\r\n]/u.test(value) &&
+    !path.isAbsolute(value) &&
+    !value.includes('/') &&
+    !value.includes('\\') &&
+    value !== '.' &&
+    value !== '..'
+  );
+}
+
+function buildTimelineAudit(phases, commands, timelineMaxSpanMs) {
+  const selected = [];
+  const missing = [];
+  for (const expected of CUTOVER_TIMELINE_ORDER) {
+    const item =
+      expected.type === 'phase'
+        ? phases.find((phase) => phase.phase === expected.phase)
+        : commands.find(
+            (command) =>
+              command.phase === expected.phase &&
+              command.commandName === expected.commandName,
+          );
+    if (!item) {
+      missing.push(expected);
+      continue;
+    }
+    selected.push({
+      ...expected,
+      generatedAt: item.generatedAt,
+      latestBundleDir: item.latestBundleDir,
+      manifestPath: item.manifestPath,
+      cutoverRunId: item.cutoverRunId,
+      status: item.status,
+    });
+  }
+
+  if (selected.length === 0 || missing.length > 0) {
+    return {
+      ok: true,
+      checked: false,
+      failedCount: 0,
+      reason:
+        selected.length === 0
+          ? '未要求标准直连切换时间线证据。'
+          : '仅在标准直连切换时间线的阶段和命令证据都被要求时检查顺序。',
+      maxSpanMs: timelineMaxSpanMs,
+      spanMs: null,
+      firstGeneratedAt: null,
+      lastGeneratedAt: null,
+      expectedOrder: CUTOVER_TIMELINE_ORDER,
+      missing,
+      items: selected,
+      diagnostics: [],
+    };
+  }
+
+  const diagnostics = [];
+  const failureBreakdown = {
+    nonOkItems: 0,
+    missingGeneratedAt: 0,
+    cutoverRunIdMismatch: 0,
+    outOfOrder: 0,
+    spanExceeded: 0,
+  };
+  const nonOkItems = selected.filter((item) => item.status !== 'OK');
+  failureBreakdown.nonOkItems = nonOkItems.length;
+  if (nonOkItems.length > 0) {
+    diagnostics.push(
+      `标准切换时间线包含非 OK 证据: ${nonOkItems
+        .map((item) => `${formatTimelineItem(item)}=${item.status}`)
+        .join(', ')}。`,
+    );
+  }
+  const timelineCutoverRunIds = selected.map((item) => ({
+    item: formatTimelineItem(item),
+    cutoverRunId: item.cutoverRunId,
+  }));
+  const hasDeclaredCutoverRunId = timelineCutoverRunIds.some(
+    (item) => item.cutoverRunId !== null,
+  );
+  const distinctCutoverRunIds = new Set(
+    timelineCutoverRunIds.map((item) => item.cutoverRunId ?? '<missing>'),
+  );
+  if (hasDeclaredCutoverRunId && distinctCutoverRunIds.size > 1) {
+    failureBreakdown.cutoverRunIdMismatch = 1;
+    diagnostics.push(
+      `标准切换时间线包含不同 cutoverRunId 或缺少 cutoverRunId: ${timelineCutoverRunIds
+        .map((item) => `${item.item}=${formatNullable(item.cutoverRunId)}`)
+        .join(', ')}，疑似混入不同切换批次证据。`,
+    );
+  }
+  const parsedTimes = [];
+  for (const item of selected) {
+    if (!item.generatedAt) {
+      failureBreakdown.missingGeneratedAt += 1;
+      diagnostics.push(
+        `${formatTimelineItem(item)} 缺少合法 manifest.generatedAt，无法证明切换时间线。`,
+      );
+      parsedTimes.push(null);
+      continue;
+    }
+    parsedTimes.push(Date.parse(item.generatedAt));
+  }
+  for (let index = 1; index < selected.length; index += 1) {
+    const previous = selected[index - 1];
+    const current = selected[index];
+    const previousTime = parsedTimes[index - 1];
+    const currentTime = parsedTimes[index];
+    if (
+      previousTime !== null &&
+      currentTime !== null &&
+      currentTime < previousTime
+    ) {
+      failureBreakdown.outOfOrder += 1;
+      diagnostics.push(
+        `${formatTimelineItem(current)} 的 manifest.generatedAt 早于 ${formatTimelineItem(previous)}，疑似混入不同切换窗口证据。`,
+      );
+    }
+  }
+
+  let firstGeneratedAt = null;
+  let lastGeneratedAt = null;
+  let spanMs = null;
+  if (parsedTimes.every((time) => time !== null && !Number.isNaN(time))) {
+    const firstTime = parsedTimes[0];
+    const lastTime = parsedTimes.at(-1);
+    firstGeneratedAt = selected[0].generatedAt;
+    lastGeneratedAt = selected.at(-1).generatedAt;
+    spanMs = lastTime - firstTime;
+    if (spanMs > timelineMaxSpanMs) {
+      failureBreakdown.spanExceeded = 1;
+      diagnostics.push(
+        `标准切换时间线从 ${firstGeneratedAt} 到 ${lastGeneratedAt} 的时间跨度 ${spanMs}ms 超过 ${timelineMaxSpanMs}ms，疑似混入不同切换窗口证据。`,
+      );
+    }
+  }
+  const timelineFailedCount = Object.values(failureBreakdown).reduce(
+    (sum, count) => sum + count,
+    0,
+  );
+
+  return {
+    ok: diagnostics.length === 0,
+    checked: true,
+    failedCount: timelineFailedCount,
+    failureBreakdown,
+    maxSpanMs: timelineMaxSpanMs,
+    spanMs,
+    firstGeneratedAt,
+    lastGeneratedAt,
+    cutoverRunIds: timelineCutoverRunIds,
+    expectedOrder: CUTOVER_TIMELINE_ORDER,
+    items: selected,
+    diagnostics,
+  };
+}
+
+function formatTimelineItem(item) {
+  if (item.type === 'command') {
+    return `${item.phase}:${item.commandName}`;
+  }
+  return item.phase;
+}
+
+function compareEvidenceCandidates(left, right) {
+  const leftTime = Date.parse(left.generatedAt);
+  const rightTime = Date.parse(right.generatedAt);
+  if (leftTime !== rightTime) {
+    return leftTime - rightTime;
+  }
+  return left.directoryName.localeCompare(right.directoryName);
+}
+
+function sortedUnique(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function normalizeIsoTime(value) {
+  if (
+    !value ||
+    typeof value !== 'string' ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value)
+  ) {
+    return null;
+  }
+  const time = Date.parse(value);
+  if (Number.isNaN(time)) {
+    return null;
+  }
+  const normalized = new Date(time).toISOString();
+  return normalized === value ? normalized : null;
+}
+
+async function runVerifier(verifyScript, bundleDir) {
+  const result = await execFileJson(process.execPath, [
+    '--',
+    verifyScript,
+    '--bundle-dir',
+    bundleDir,
+    '--require-summary-ok',
+  ]);
+  const parsed = parseJsonOutput(result.stdout);
+  return {
+    ok:
+      result.exitCode === 0 &&
+      parsed.ok &&
+      parsed.value?.ok === true &&
+      parsed.value?.requireSummaryOk === true,
+    exitCode: result.exitCode,
+    stdoutJson: parsed.ok,
+    checkedCount: parsed.value?.checkedCount ?? null,
+    failedCount: parsed.value?.failedCount ?? null,
+    requireSummaryOk: parsed.value?.requireSummaryOk ?? null,
+    summary: parsed.value?.summary ?? null,
+    stderr: result.stderr,
+    error: result.error,
+  };
+}
+
+function execFileJson(command, args) {
+  return new Promise((resolve) => {
+    execFile(
+      command,
+      args,
+      {
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024,
+        shell: false,
+      },
+      (error, stdout, stderr) => {
+        resolve({
+          exitCode:
+            typeof error?.code === 'number' ? error.code : error ? 1 : 0,
+          stdout: stdout || '',
+          stderr: stderr || '',
+          error: error?.message || null,
+        });
+      },
+    );
+  });
+}
+
+function parseJsonOutput(stdout) {
+  try {
+    return { ok: true, value: JSON.parse(stdout) };
+  } catch {
+    return { ok: false, value: null };
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
diff --git a/scripts/ops/pingora-cutover-evidence-bundle.mjs b/scripts/ops/pingora-cutover-evidence-bundle.mjs
new file mode 100644
index 000000000..bdc4c6f4e
--- /dev/null
+++ b/scripts/ops/pingora-cutover-evidence-bundle.mjs
@@ -0,0 +1,1274 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import {
+  access,
+  chmod,
+  lstat,
+  mkdir,
+  readFile,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import path from 'node:path';
+
+const GATEWAY_MODES = new Set(['nginx', 'pingora-direct']);
+const PINGORA_ENV_MODES = new Set(['shadow', 'direct']);
+const BUNDLE_DIR_MODE = 0o750;
+const EVIDENCE_FILE_MODE = 0o640;
+const SECRET_VALUE_FLAGS = new Set([
+  '--direct-probe-token',
+  '--probe-token',
+  '--pingora-shadow-probe-token',
+  '--rollback-pingora-shadow-probe-token',
+]);
+const DIRECT_LIVE_JSON_PATTERN = /\{\s*"ok"\s*:/u;
+
+const config = parseArgs(process.argv.slice(2));
+const startedAt = new Date();
+const bundleDir = await createBundleDir(
+  config.outputRoot,
+  config.phase,
+  startedAt,
+);
+const snapshotArgs = buildSnapshotArgs(config);
+const snapshotRun = await runEvidenceCommand({
+  name: 'pingora-cutover-status-snapshot',
+  executable: 'node',
+  args: [config.snapshotScript, ...snapshotArgs],
+  stdoutFile: 'snapshot.stdout.txt',
+  stderrFile: 'snapshot.stderr.txt',
+  jsonFile: 'snapshot.json',
+  parseErrorFile: 'snapshot-parse-error.txt',
+  commandFile: 'snapshot-command.json',
+  parseJson: parseSnapshotJson,
+});
+const manifestPath = path.join(bundleDir, 'manifest.json');
+const snapshot = snapshotRun.parsed;
+const snapshotStatus = snapshot.ok
+  ? snapshot.value?.summary?.status ||
+    (snapshotRun.result.code === 0 ? 'OK' : 'CRITICAL')
+  : 'CRITICAL';
+
+let directLiveRun = null;
+if (
+  config.runDirectLive &&
+  snapshotRun.result.code === 0 &&
+  snapshot.ok &&
+  (!config.failOnCritical || snapshotStatus !== 'CRITICAL')
+) {
+  directLiveRun = await runEvidenceCommand({
+    name: 'pingora-direct-live',
+    executable: 'node',
+    args: [config.directLiveScript, ...buildDirectLiveArgs(config)],
+    stdoutFile: 'direct-live.stdout.txt',
+    stderrFile: 'direct-live.stderr.txt',
+    jsonFile: 'direct-live.json',
+    parseErrorFile: 'direct-live-parse-error.txt',
+    commandFile: 'direct-live-command.json',
+    parseJson: parseDirectLiveJson,
+  });
+}
+
+const directLiveAccessLog = summarizeDirectLiveAccessLog(directLiveRun);
+const directLiveStaticHeaders = summarizeDirectLiveStaticHeaders(directLiveRun);
+const pingoraEnvShadow = summarizePingoraEnvShadow(snapshotRun);
+const directLiveStatus = directLiveRun
+  ? isDirectLiveEvidenceOk(
+      directLiveRun,
+      directLiveAccessLog,
+      directLiveStaticHeaders,
+    )
+    ? 'OK'
+    : 'CRITICAL'
+  : 'SKIPPED';
+const snapshotCriticalCount = snapshot.ok
+  ? Number(snapshot.value?.summary?.criticalCount || 0)
+  : 1;
+const directLiveCriticalCount = directLiveStatus === 'CRITICAL' ? 1 : 0;
+const bundleStatus =
+  snapshotStatus === 'CRITICAL' || directLiveStatus === 'CRITICAL'
+    ? 'CRITICAL'
+    : snapshotStatus;
+const manifest = {
+  schemaVersion: 1,
+  generatedAt: new Date().toISOString(),
+  phase: config.phase,
+  ...(config.cutoverRunId ? { cutoverRunId: config.cutoverRunId } : {}),
+  releaseRoot: config.releaseRoot,
+  outputRoot: config.outputRoot,
+  bundleDir,
+  summary: {
+    status: bundleStatus,
+    snapshotStatus,
+    snapshotExitCode: snapshotRun.result.code,
+    directLiveStatus,
+    directLiveExitCode: directLiveRun?.result.code ?? null,
+    directLiveAccessLog: directLiveAccessLog?.summary ?? null,
+    directLiveStaticHeaders: directLiveStaticHeaders?.summary ?? null,
+    pingoraEnvShadow: pingoraEnvShadow?.summary ?? null,
+    criticalCount: snapshotCriticalCount + directLiveCriticalCount,
+    warningCount: snapshot.ok
+      ? Number(snapshot.value?.summary?.warningCount || 0)
+      : 0,
+  },
+  files: {
+    manifest: path.basename(manifestPath),
+    snapshot: snapshot.ok ? snapshotRun.files.json : null,
+    snapshotParseError: snapshot.ok ? null : snapshotRun.files.parseError,
+    snapshotStdout: snapshotRun.files.stdout,
+    snapshotStderr: snapshotRun.files.stderr,
+    snapshotCommand: snapshotRun.files.command,
+    directLive: directLiveRun?.parsed.ok ? directLiveRun.files.json : null,
+    directLiveParseError:
+      directLiveRun && !directLiveRun.parsed.ok
+        ? directLiveRun.files.parseError
+        : null,
+    directLiveStdout: directLiveRun ? directLiveRun.files.stdout : null,
+    directLiveStderr: directLiveRun ? directLiveRun.files.stderr : null,
+    directLiveCommand: directLiveRun ? directLiveRun.files.command : null,
+  },
+  commands: [
+    snapshotRun.commandRecord,
+    ...(directLiveRun ? [directLiveRun.commandRecord] : []),
+  ],
+};
+await writeEvidenceFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+const directLiveOk =
+  !config.runDirectLive ||
+  isDirectLiveEvidenceOk(
+    directLiveRun,
+    directLiveAccessLog,
+    directLiveStaticHeaders,
+  );
+const result = {
+  ok:
+    snapshotRun.result.code === 0 &&
+    snapshot.ok &&
+    (!config.failOnCritical || snapshotStatus !== 'CRITICAL') &&
+    directLiveOk,
+  phase: config.phase,
+  cutoverRunId: config.cutoverRunId || null,
+  status: bundleStatus,
+  bundleDir,
+  manifestPath,
+  snapshotPath: snapshot.ok ? snapshotRun.jsonPath : null,
+  snapshotParseErrorPath: snapshot.ok ? null : snapshotRun.parseErrorPath,
+  directLivePath: directLiveRun?.parsed.ok ? directLiveRun.jsonPath : null,
+  directLiveParseErrorPath:
+    directLiveRun && !directLiveRun.parsed.ok
+      ? directLiveRun.parseErrorPath
+      : null,
+};
+console.log(`${JSON.stringify(result, null, 2)}\n`);
+
+if (!result.ok) {
+  process.exit(1);
+}
+
+function summarizePingoraEnvShadow(snapshotRun) {
+  if (!snapshotRun.parsed.ok) {
+    return {
+      ok: false,
+      summary: {
+        present: false,
+        listen: '',
+        tlsListen: '',
+        httpRedirectListen: '',
+        ok: false,
+        diagnostics: ['snapshot JSON parse failed'],
+      },
+    };
+  }
+
+  const pingoraEnv = snapshotRun.parsed.value?.pingoraEnv;
+  const values = pingoraEnv?.values;
+  if (!values || typeof values !== 'object' || Array.isArray(values)) {
+    return {
+      ok: false,
+      summary: {
+        present: false,
+        listen: '',
+        tlsListen: '',
+        httpRedirectListen: '',
+        ok: false,
+        diagnostics: ['snapshot JSON missing pingoraEnv.values'],
+      },
+    };
+  }
+
+  const summary = {
+    present: true,
+    mode: String(pingoraEnv?.posture?.mode || ''),
+    shadowReady: pingoraEnv?.posture?.shadowReady === true,
+    directReady: pingoraEnv?.posture?.directReady === true,
+    listen: String(values.listen || ''),
+    tlsListen: String(values.tlsListen || ''),
+    httpRedirectListen: String(values.httpRedirectListen || ''),
+    tlsCertFile: String(values.tlsCertFile || ''),
+    tlsKeyFile: String(values.tlsKeyFile || ''),
+    ok: false,
+    diagnostics: [],
+  };
+  if (summary.listen !== '127.0.0.1:18081') {
+    summary.diagnostics.push(
+      `listen 应为 127.0.0.1:18081，实际 ${summary.listen || '-'}`,
+    );
+  }
+  if (summary.tlsListen !== '') {
+    summary.diagnostics.push(
+      `tlsListen 应为空，实际 ${summary.tlsListen}`,
+    );
+  }
+  if (summary.httpRedirectListen !== '') {
+    summary.diagnostics.push(
+      `httpRedirectListen 应为空，实际 ${summary.httpRedirectListen}`,
+    );
+  }
+  if (summary.tlsCertFile !== '') {
+    summary.diagnostics.push(
+      `tlsCertFile 应为空，实际 ${summary.tlsCertFile}`,
+    );
+  }
+  if (summary.tlsKeyFile !== '') {
+    summary.diagnostics.push(
+      `tlsKeyFile 应为空，实际 ${summary.tlsKeyFile}`,
+    );
+  }
+  if (summary.mode && summary.mode !== 'shadow') {
+    summary.diagnostics.push(`mode 应为 shadow，实际 ${summary.mode}`);
+  }
+  if (summary.shadowReady === false) {
+    summary.diagnostics.push('shadowReady 应为 true');
+  }
+  summary.ok = summary.diagnostics.length === 0;
+  return { ok: summary.ok, summary };
+}
+
+function summarizeDirectLiveAccessLog(directLiveRun) {
+  if (!directLiveRun) {
+    return null;
+  }
+  if (!directLiveRun.parsed.ok) {
+    return {
+      ok: false,
+      summary: {
+        present: false,
+        reason: 'direct live JSON parse failed',
+      },
+    };
+  }
+  const accessLogCheck = directLiveRun.parsed.value?.results?.find(
+    (item) => item?.name === 'direct-access-log',
+  );
+  if (!accessLogCheck) {
+    return {
+      ok: false,
+      summary: {
+        present: false,
+        reason: 'direct live JSON missing direct-access-log result',
+      },
+    };
+  }
+
+  const summary = {
+    present: true,
+    logFile: accessLogCheck.logFile || '',
+    sinceLines: coerceNonNegativeInteger(accessLogCheck.sinceLines),
+    scannedLineCount: coerceNonNegativeInteger(
+      accessLogCheck.scannedLineCount,
+    ),
+    checked: coerceNonNegativeInteger(accessLogCheck.checked),
+    matchedCount: coerceNonNegativeInteger(accessLogCheck.matchedCount),
+    missingCount: coerceNonNegativeInteger(accessLogCheck.missingCount),
+    mismatchCount: coerceNonNegativeInteger(accessLogCheck.mismatchCount),
+    missingDetailsCount: Array.isArray(accessLogCheck.missing)
+      ? accessLogCheck.missing.length
+      : null,
+    mismatchDetailsCount: Array.isArray(accessLogCheck.mismatches)
+      ? accessLogCheck.mismatches.length
+      : null,
+  };
+  const ok =
+    summary.checked !== null &&
+    summary.matchedCount === summary.checked &&
+    summary.missingCount === 0 &&
+    summary.mismatchCount === 0 &&
+    summary.missingDetailsCount === 0 &&
+    summary.mismatchDetailsCount === 0;
+
+  return { ok, summary };
+}
+
+function summarizeDirectLiveStaticHeaders(directLiveRun) {
+  if (!directLiveRun) {
+    return null;
+  }
+  if (!directLiveRun.parsed.ok) {
+    return {
+      ok: false,
+      summary: {
+        present: false,
+        reason: 'direct live JSON parse failed',
+      },
+    };
+  }
+
+  const staticAssetCheck = directLiveRun.parsed.value?.results?.find(
+    (item) => item?.name === 'https-static-asset',
+  );
+  if (!staticAssetCheck) {
+    return {
+      ok: false,
+      summary: {
+        present: false,
+        skipped: false,
+        reason: 'direct live JSON missing https-static-asset result',
+      },
+    };
+  }
+  if (staticAssetCheck.skipped) {
+    return {
+      ok: true,
+      summary: {
+        present: false,
+        skipped: true,
+        reason: staticAssetCheck.reason || '',
+      },
+    };
+  }
+
+  const normal = summarizeStaticHeaderEntry(staticAssetCheck);
+  const fingerprinted = summarizeStaticHeaderEntry(
+    staticAssetCheck.fingerprinted,
+    {
+      expectedCacheControl: 'public, max-age=31536000, immutable',
+    },
+  );
+  const diagnostics = [
+    ...normal.diagnostics.map((item) => `normal: ${item}`),
+    ...(fingerprinted.present
+      ? fingerprinted.diagnostics.map((item) => `fingerprinted: ${item}`)
+      : []),
+  ];
+  const summary = {
+    present: true,
+    normal,
+    fingerprinted,
+    diagnostics,
+  };
+  return {
+    ok: normal.ok && (!fingerprinted.present || fingerprinted.ok),
+    summary,
+  };
+}
+
+function summarizeStaticHeaderEntry(entry, options = {}) {
+  if (!entry || entry.skipped) {
+    return {
+      ok: true,
+      present: false,
+      skipped: Boolean(entry?.skipped),
+      reason: entry?.reason || '',
+      diagnostics: [],
+    };
+  }
+
+  const summary = {
+    present: true,
+    path: safePathFromUrl(entry.url),
+    statusCode: coerceNonNegativeInteger(entry.statusCode),
+    cacheControl: entry.headers?.['cache-control'] || '',
+    etag: entry.headers?.etag || '',
+    lastModified: entry.headers?.['last-modified'] || '',
+    acceptRanges: entry.headers?.['accept-ranges'] || '',
+    contentLength: entry.headers?.['content-length'] || '',
+    rangeStatusCode: coerceNonNegativeInteger(entry.range?.statusCode),
+    rangeContentRange: entry.range?.headers?.['content-range'] || '',
+    rangeContentLength: entry.range?.headers?.['content-length'] || '',
+    etag304StatusCode: coerceNonNegativeInteger(
+      entry.notModified?.etag?.statusCode,
+    ),
+    lastModified304StatusCode: coerceNonNegativeInteger(
+      entry.notModified?.lastModified?.statusCode,
+    ),
+  };
+  const diagnostics = [];
+  if (summary.statusCode !== 200) {
+    diagnostics.push(`GET statusCode 应为 200，实际 ${formatValue(summary.statusCode)}`);
+  }
+  if (!summary.cacheControl) {
+    diagnostics.push('缺少 Cache-Control');
+  }
+  if (
+    options.expectedCacheControl &&
+    summary.cacheControl !== options.expectedCacheControl
+  ) {
+    diagnostics.push(
+      `Cache-Control 应为 ${options.expectedCacheControl}，实际 ${summary.cacheControl || '-'}`,
+    );
+  }
+  if (!summary.etag) {
+    diagnostics.push('缺少 ETag');
+  }
+  if (!summary.lastModified) {
+    diagnostics.push('缺少 Last-Modified');
+  }
+  if (summary.acceptRanges !== 'bytes') {
+    diagnostics.push(
+      `Accept-Ranges 应为 bytes，实际 ${summary.acceptRanges || '-'}`,
+    );
+  }
+  if (!summary.contentLength) {
+    diagnostics.push('缺少 Content-Length');
+  }
+  if (summary.rangeStatusCode !== 206) {
+    diagnostics.push(
+      `Range statusCode 应为 206，实际 ${formatValue(summary.rangeStatusCode)}`,
+    );
+  }
+  if (!/^bytes 0-0\/\d+$/u.test(summary.rangeContentRange)) {
+    diagnostics.push(
+      `Range Content-Range 应匹配 bytes 0-0/<len>，实际 ${summary.rangeContentRange || '-'}`,
+    );
+  }
+  if (summary.rangeContentLength !== '1') {
+    diagnostics.push(
+      `Range Content-Length 应为 1，实际 ${summary.rangeContentLength || '-'}`,
+    );
+  }
+  if (summary.etag304StatusCode !== 304) {
+    diagnostics.push(
+      `ETag 304 statusCode 应为 304，实际 ${formatValue(summary.etag304StatusCode)}`,
+    );
+  }
+  if (summary.lastModified304StatusCode !== 304) {
+    diagnostics.push(
+      `Last-Modified 304 statusCode 应为 304，实际 ${formatValue(summary.lastModified304StatusCode)}`,
+    );
+  }
+
+  return {
+    ok: diagnostics.length === 0,
+    ...summary,
+    diagnostics,
+  };
+}
+
+function safePathFromUrl(value) {
+  if (!value) {
+    return '';
+  }
+  try {
+    return new URL(value).pathname;
+  } catch {
+    return '';
+  }
+}
+
+function coerceNonNegativeInteger(value) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0) {
+    return null;
+  }
+  return number;
+}
+
+function isDirectLiveEvidenceOk(
+  directLiveRun,
+  directLiveAccessLog,
+  directLiveStaticHeaders,
+) {
+  return Boolean(
+    directLiveRun &&
+      directLiveRun.result.code === 0 &&
+      directLiveRun.parsed.ok &&
+      directLiveRun.parsed.value?.ok !== false &&
+      directLiveAccessLog?.ok &&
+      directLiveStaticHeaders?.ok,
+  );
+}
+
+function formatValue(value) {
+  return value === null || value === undefined ? '-' : String(value);
+}
+
+function parseArgs(argv) {
+  const result = {
+    phase: process.env.GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_PHASE || 'manual',
+    cutoverRunId: process.env.GENARRATIVE_PINGORA_CUTOVER_RUN_ID || '',
+    releaseRoot:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_RELEASE_ROOT ||
+      '/opt/genarrative/current',
+    outputRoot:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_ROOT ||
+      '/var/log/genarrative/pingora-cutover-evidence',
+    healthPatrolEnvFile:
+      process.env.GENARRATIVE_HEALTH_PATROL_ENV_FILE ||
+      '/etc/genarrative/health-patrol.env',
+    pingoraEnvFile:
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE ||
+      '/etc/genarrative/pingora-gateway.env',
+    snapshotScript: '',
+    directLiveScript: '',
+    runDirectLive: readBoolEnv(
+      'GENARRATIVE_PINGORA_CUTOVER_EVIDENCE_RUN_DIRECT_LIVE',
+    ),
+    directHttpsBaseUrl:
+      process.env.GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL || '',
+    directHttpBaseUrl:
+      process.env.GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL || '',
+    directHost: process.env.GENARRATIVE_PINGORA_DIRECT_HOST || '',
+    directRedirectHost:
+      process.env.GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST || '',
+    directRedirectBaseUrl:
+      process.env.GENARRATIVE_PINGORA_DIRECT_REDIRECT_BASE_URL || '',
+    directProbeToken: process.env.GENARRATIVE_PINGORA_DIRECT_PROBE_TOKEN || '',
+    directSpacetimeDatabase:
+      process.env.GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE || '',
+    directPingoraAccessLog:
+      process.env.GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG || '',
+    directAccessLogSinceLines:
+      process.env.GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES || '2000',
+    expectedGatewayMode:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_GATEWAY_MODE || '',
+    expectedPingoraEnvMode:
+      process.env.GENARRATIVE_PINGORA_EXPECTED_ENV_MODE || '',
+    expectedPublicBaseUrl:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL || '',
+    expectedPublicHost:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_HOST || null,
+    requireEmptyPublicHost: readBoolEnv(
+      'GENARRATIVE_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST',
+    ),
+    runHealthPatrol: readBoolEnv(
+      'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL',
+    ),
+    requirePingoraGateway: readBoolEnv(
+      'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_REQUIRE_PINGORA_GATEWAY',
+    ),
+    timeoutMs: parseOptionalPositiveInt(
+      process.env.GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS,
+      5000,
+      'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS',
+    ),
+    failOnCritical: readBoolEnv(
+      'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL',
+    ),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--phase':
+        result.phase = requireValue(argv, ++index, arg);
+        break;
+      case '--cutover-run-id':
+        result.cutoverRunId = requireValue(argv, ++index, arg);
+        break;
+      case '--release-root':
+        result.releaseRoot = requireValue(argv, ++index, arg);
+        break;
+      case '--output-root':
+        result.outputRoot = requireValue(argv, ++index, arg);
+        break;
+      case '--health-patrol-env-file':
+        result.healthPatrolEnvFile = requireValue(argv, ++index, arg);
+        break;
+      case '--pingora-env-file':
+        result.pingoraEnvFile = requireValue(argv, ++index, arg);
+        break;
+      case '--snapshot-script':
+        result.snapshotScript = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-live-script':
+        result.directLiveScript = requireValue(argv, ++index, arg);
+        break;
+      case '--run-direct-live':
+        result.runDirectLive = true;
+        break;
+      case '--direct-https-base-url':
+        result.directHttpsBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-http-base-url':
+        result.directHttpBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-host':
+        result.directHost = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-redirect-host':
+        result.directRedirectHost = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-redirect-base-url':
+        result.directRedirectBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-probe-token':
+        result.directProbeToken = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-spacetime-database':
+        result.directSpacetimeDatabase = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-pingora-access-log':
+        result.directPingoraAccessLog = requireValue(argv, ++index, arg);
+        break;
+      case '--direct-access-log-since-lines':
+        result.directAccessLogSinceLines = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-gateway-mode':
+        result.expectedGatewayMode = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-pingora-env-mode':
+        result.expectedPingoraEnvMode = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-public-base-url':
+        result.expectedPublicBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-public-host':
+        result.expectedPublicHost = requireValue(argv, ++index, arg);
+        break;
+      case '--require-empty-public-host':
+        result.requireEmptyPublicHost = true;
+        break;
+      case '--run-health-patrol':
+        result.runHealthPatrol = true;
+        break;
+      case '--require-pingora-gateway':
+        result.requirePingoraGateway = true;
+        break;
+      case '--timeout-ms':
+        result.timeoutMs = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          arg,
+        );
+        break;
+      case '--fail-on-critical':
+        result.failOnCritical = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  result.snapshotScript =
+    result.snapshotScript ||
+    path.join(
+      result.releaseRoot,
+      'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    );
+  result.directLiveScript =
+    result.directLiveScript ||
+    path.join(result.releaseRoot, 'scripts/check-pingora-direct-live.mjs');
+
+  validateConfig(result);
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/ops/pingora-cutover-evidence-bundle.mjs [options]
+
+Options:
+  --phase <name>                    写入 manifest 的阶段标签，例如 pre-cutover / post-enable / post-rollback。
+  --cutover-run-id <id>             可选，写入 manifest 的本次切换批次 ID；正式 runbook 会用同一 ID 串联所有阶段和命令证据。
+  --release-root <path>             current release 根目录，默认 /opt/genarrative/current。
+  --output-root <path>              证据包输出根目录，默认 /var/log/genarrative/pingora-cutover-evidence。
+  --health-patrol-env-file <path>   health-patrol env 文件，默认 /etc/genarrative/health-patrol.env。
+  --pingora-env-file <path>         pingora-gateway env 文件，默认 /etc/genarrative/pingora-gateway.env。
+  --snapshot-script <path>          状态快照脚本，默认 current release 随包脚本。
+  --direct-live-script <path>       direct live smoke 脚本，默认 current release 随包脚本。
+  --run-direct-live                 额外执行 direct live smoke，并把 request_id / access log 结果归档。
+  --direct-https-base-url <url>     透传给 direct live smoke 的 HTTPS 入口。
+  --direct-http-base-url <url>      透传给 direct live smoke 的 HTTP redirect / ACME 入口。
+  --direct-host <host>              透传给 direct live smoke 的正式 Host/SNI。
+  --direct-redirect-host <host>     透传给 direct live smoke 的 redirect Location host。
+  --direct-redirect-base-url <url>  可选，透传给 direct live smoke 的 redirect Location HTTPS base URL。
+  --direct-probe-token <token>      可选，透传给 direct live smoke 的内部探针 token；证据中会脱敏。
+  --direct-spacetime-database <db>  透传给 direct live smoke 的 SpacetimeDB 数据库名。
+  --direct-pingora-access-log <path>
+                                    透传给 direct live smoke 的 Pingora access log 路径。
+  --direct-access-log-since-lines <n>
+                                    透传给 direct live smoke 的 access log tail 行数，默认 2000。
+  --expected-gateway-mode <mode>    可选，nginx 或 pingora-direct；会透传给状态快照。
+  --expected-pingora-env-mode <mode>
+                                    可选，shadow 或 direct；会透传给状态快照。
+  --expected-public-base-url <url>  可选，要求 health-patrol public base URL 与该值一致。
+  --expected-public-host <host>     可选，要求 health-patrol public Host 与该值一致。
+  --require-empty-public-host       可选，要求 health-patrol public Host 为空。
+  --run-health-patrol               让状态快照执行 current release 随包生产巡检脚本并收录结果。
+  --require-pingora-gateway         让状态快照自审 current release 的 Pingora 二进制、checksum 和 manifest。
+  --timeout-ms <ms>                 透传给状态快照脚本的 systemctl / 子检查超时，默认 5000。
+  --fail-on-critical                如果快照中出现 CRITICAL，则证据包脚本也以退出码 1 结束。
+
+该脚本只写 --output-root 下的新证据目录，且 --output-root 不能是符号链接或非目录路径；证据目录权限固定 0750，证据文件权限固定 0640；不写 /etc、不 reload systemd、不修改 Nginx 或 Pingora。
+`);
+}
+
+function validateConfig(config) {
+  validatePhase(config.phase);
+  if (config.cutoverRunId) {
+    validateSafeName(config.cutoverRunId, '--cutover-run-id');
+  }
+  for (const [label, value] of [
+    ['--release-root', config.releaseRoot],
+    ['--output-root', config.outputRoot],
+    ['--health-patrol-env-file', config.healthPatrolEnvFile],
+    ['--pingora-env-file', config.pingoraEnvFile],
+    ['--snapshot-script', config.snapshotScript],
+    ['--direct-live-script', config.directLiveScript],
+  ]) {
+    if (!path.isAbsolute(value)) {
+      throw new Error(`${label} 必须是绝对路径。`);
+    }
+    if (path.resolve(value) === path.parse(path.resolve(value)).root) {
+      throw new Error(`${label} 不能是文件系统根目录。`);
+    }
+  }
+  if (
+    config.expectedGatewayMode &&
+    !GATEWAY_MODES.has(config.expectedGatewayMode)
+  ) {
+    throw new Error(
+      `--expected-gateway-mode 只支持 nginx 或 pingora-direct: ${config.expectedGatewayMode}`,
+    );
+  }
+  if (
+    config.expectedPingoraEnvMode &&
+    !PINGORA_ENV_MODES.has(config.expectedPingoraEnvMode)
+  ) {
+    throw new Error(
+      `--expected-pingora-env-mode 只支持 shadow 或 direct: ${config.expectedPingoraEnvMode}`,
+    );
+  }
+  if (config.expectedPublicHost !== null) {
+    validateHostOption(config.expectedPublicHost, '--expected-public-host');
+  }
+  if (config.expectedPublicHost !== null && config.requireEmptyPublicHost) {
+    throw new Error(
+      '--expected-public-host 和 --require-empty-public-host 不能同时使用。',
+    );
+  }
+  if (config.expectedPublicBaseUrl) {
+    validateHttpUrl(config.expectedPublicBaseUrl, '--expected-public-base-url');
+  }
+  if (config.runDirectLive) {
+    validateDirectLiveConfig(config);
+  }
+  validateEvidenceCommandArgs('状态快照命令参数', buildSnapshotArgs(config));
+  if (config.runDirectLive) {
+    validateEvidenceCommandArgs('direct live 命令参数', buildDirectLiveArgs(config));
+  }
+}
+
+function validateDirectLiveConfig(config) {
+  if (!config.directHttpsBaseUrl) {
+    throw new Error('--run-direct-live 必须提供 --direct-https-base-url。');
+  }
+  validateHttpsUrl(config.directHttpsBaseUrl, '--direct-https-base-url');
+  if (!config.directHttpBaseUrl) {
+    throw new Error('--run-direct-live 必须提供 --direct-http-base-url。');
+  }
+  validateHttpOnlyUrl(config.directHttpBaseUrl, '--direct-http-base-url');
+  if (!config.directHost) {
+    throw new Error('--run-direct-live 必须提供 --direct-host。');
+  }
+  validateHostOption(config.directHost, '--direct-host');
+  if (!config.directRedirectHost) {
+    throw new Error('--run-direct-live 必须提供 --direct-redirect-host。');
+  }
+  validateHostOption(config.directRedirectHost, '--direct-redirect-host');
+  if (config.directRedirectBaseUrl) {
+    validateHttpsBaseUrl(config.directRedirectBaseUrl, '--direct-redirect-base-url');
+  }
+  if (!config.directSpacetimeDatabase) {
+    throw new Error('--run-direct-live 必须提供 --direct-spacetime-database。');
+  }
+  validateNoControlCharacters(
+    config.directSpacetimeDatabase,
+    '--direct-spacetime-database',
+  );
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(config.directSpacetimeDatabase)) {
+    throw new Error(
+      '--direct-spacetime-database 必须匹配 SpacetimeDB 数据库名规则 ^[a-z0-9]+(-[a-z0-9]+)*$。',
+    );
+  }
+  if (config.directProbeToken) {
+    validateNoControlCharacters(config.directProbeToken, '--direct-probe-token');
+  }
+  if (!config.directPingoraAccessLog) {
+    throw new Error('--run-direct-live 必须提供 --direct-pingora-access-log。');
+  }
+  validateSafeAbsoluteFilePath(
+    config.directPingoraAccessLog,
+    '--direct-pingora-access-log',
+  );
+  validateNoControlCharacters(
+    config.directAccessLogSinceLines,
+    '--direct-access-log-since-lines',
+  );
+  if (!/^[1-9][0-9]*$/u.test(String(config.directAccessLogSinceLines))) {
+    throw new Error('--direct-access-log-since-lines 必须是正整数。');
+  }
+}
+
+function validatePhase(value) {
+  validateSafeName(value, '--phase');
+}
+
+function validateSafeName(value, label) {
+  const text = String(value || '');
+  if (!/^[0-9A-Za-z._-]+$/u.test(text)) {
+    throw new Error(
+      `${label} 只能包含 ASCII 字母、数字、点、下划线或短横线。`,
+    );
+  }
+}
+
+function validateEvidenceCommandArgs(label, args) {
+  for (const arg of args) {
+    if (/[\0\r\n]/u.test(String(arg))) {
+      throw new Error(`${label}不能包含换行或 NUL 字符。`);
+    }
+  }
+}
+
+function validateSafeAbsoluteFilePath(value, label) {
+  validateNoControlCharacters(value, label);
+  if (!path.isAbsolute(value)) {
+    throw new Error(`${label} 必须是绝对路径。`);
+  }
+  if (path.resolve(value) === path.parse(path.resolve(value)).root) {
+    throw new Error(`${label} 不能是文件系统根目录。`);
+  }
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function readBoolEnv(name) {
+  const value = process.env[name];
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return false;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${name} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function parseOptionalPositiveInt(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parseRequiredPositiveInt(raw, label);
+}
+
+function parseRequiredPositiveInt(raw, label) {
+  validateNoControlCharacters(raw, label);
+  const text = String(raw ?? '').trim();
+  if (!/^[1-9][0-9]*$/u.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  return Number.parseInt(text, 10);
+}
+
+function validateHttpUrl(value, label) {
+  validateNoControlCharacters(value, label);
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error('unsupported protocol');
+    }
+  } catch {
+    throw new Error(`${label} 必须是合法 http(s) URL: ${value}`);
+  }
+}
+
+function validateHttpsUrl(value, label) {
+  validateHttpUrl(value, label);
+  if (new URL(value).protocol !== 'https:') {
+    throw new Error(`${label} 必须使用 https://。`);
+  }
+}
+
+function validateHttpsBaseUrl(value, label) {
+  validateHttpsUrl(value, label);
+  const parsed = new URL(value);
+  if (
+    parsed.pathname !== '/' ||
+    parsed.search ||
+    parsed.hash ||
+    parsed.username ||
+    parsed.password
+  ) {
+    throw new Error(
+      `${label} 只能是 HTTPS base URL，不能包含路径、查询、片段或认证信息。`,
+    );
+  }
+}
+
+function validateHttpOnlyUrl(value, label) {
+  validateHttpUrl(value, label);
+  if (new URL(value).protocol !== 'http:') {
+    throw new Error(`${label} 必须使用 http://。`);
+  }
+}
+
+function validateHostOption(value, label) {
+  const raw = String(value);
+  validateNoControlCharacters(raw, label);
+  if (raw !== raw.trim() || raw.includes('://') || /[\s/?#@]/.test(raw)) {
+    throw new Error(
+      `${label} 只能是 host 或 host:port，不能包含 scheme、路径、查询、片段或空白字符`,
+    );
+  }
+  try {
+    const parsed = new URL(`https://${raw}`);
+    if (
+      !parsed.hostname ||
+      parsed.pathname !== '/' ||
+      parsed.search ||
+      parsed.hash ||
+      parsed.username ||
+      parsed.password
+    ) {
+      throw new Error('invalid host');
+    }
+  } catch {
+    throw new Error(`${label} 不是合法的 host 或 host:port`);
+  }
+}
+
+async function createBundleDir(outputRoot, phase, date) {
+  await validateOutputRootForWriting(outputRoot);
+  await mkdir(outputRoot, { recursive: true });
+  await validateOutputRootForWriting(outputRoot);
+  await access(outputRoot, fsConstants.W_OK);
+  const baseName = `${formatTimestampForPath(date)}-${phase}`;
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const suffix = attempt === 0 ? '' : `-${attempt}`;
+    const bundleDir = path.join(outputRoot, `${baseName}${suffix}`);
+    try {
+      await mkdir(bundleDir, { recursive: false, mode: BUNDLE_DIR_MODE });
+      await chmod(bundleDir, BUNDLE_DIR_MODE);
+      return bundleDir;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw error;
+      }
+    }
+  }
+  throw new Error(`无法创建唯一证据目录: ${path.join(outputRoot, baseName)}`);
+}
+
+async function validateOutputRootForWriting(outputRoot) {
+  const target = path.resolve(outputRoot);
+  const root = path.parse(target).root;
+  let current = root;
+  const segments = path
+    .relative(root, target)
+    .split(path.sep)
+    .filter(Boolean);
+
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    let stats;
+    try {
+      stats = await lstat(current);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        return;
+      }
+      throw error;
+    }
+
+    if (stats.isSymbolicLink()) {
+      if (current === target) {
+        throw new Error(`--output-root 不能是符号链接: ${current}`);
+      }
+      throw new Error(`--output-root 上级目录不能是符号链接: ${current}`);
+    }
+
+    if (!stats.isDirectory()) {
+      if (current === target) {
+        throw new Error(`--output-root 已存在但不是目录: ${current}`);
+      }
+      throw new Error(`--output-root 上级路径已存在但不是目录: ${current}`);
+    }
+  }
+}
+
+async function writeEvidenceFile(filePath, content) {
+  await writeFile(filePath, content, {
+    encoding: 'utf8',
+    flag: 'wx',
+    mode: EVIDENCE_FILE_MODE,
+  });
+  await chmod(filePath, EVIDENCE_FILE_MODE);
+}
+
+async function buildEvidenceFileMetadata(filePath) {
+  const [stats, content] = await Promise.all([stat(filePath), readFile(filePath)]);
+  return {
+    path: path.basename(filePath),
+    sizeBytes: stats.size,
+    sha256: createHash('sha256').update(content).digest('hex'),
+  };
+}
+
+function formatTimestampForPath(date) {
+  return date
+    .toISOString()
+    .replace(/[-:]/gu, '')
+    .replace(/\.\d{3}Z$/u, 'Z');
+}
+
+function buildSnapshotArgs(config) {
+  return [
+    '--phase',
+    config.phase,
+    '--release-root',
+    config.releaseRoot,
+    '--health-patrol-env-file',
+    config.healthPatrolEnvFile,
+    '--pingora-env-file',
+    config.pingoraEnvFile,
+    ...(config.expectedGatewayMode
+      ? ['--expected-gateway-mode', config.expectedGatewayMode]
+      : []),
+    ...(config.expectedPingoraEnvMode
+      ? ['--expected-pingora-env-mode', config.expectedPingoraEnvMode]
+      : []),
+    ...(config.expectedPublicBaseUrl
+      ? ['--expected-public-base-url', config.expectedPublicBaseUrl]
+      : []),
+    ...(config.expectedPublicHost !== null
+      ? ['--expected-public-host', config.expectedPublicHost]
+      : []),
+    ...(config.requireEmptyPublicHost ? ['--require-empty-public-host'] : []),
+    ...(config.runHealthPatrol ? ['--run-health-patrol'] : []),
+    ...(config.requirePingoraGateway ? ['--require-pingora-gateway'] : []),
+    '--timeout-ms',
+    String(config.timeoutMs),
+    ...(config.failOnCritical ? ['--fail-on-critical'] : []),
+  ];
+}
+
+function buildDirectLiveArgs(config) {
+  return [
+    '--https-base-url',
+    config.directHttpsBaseUrl,
+    '--http-base-url',
+    config.directHttpBaseUrl,
+    '--host',
+    config.directHost,
+    '--redirect-host',
+    config.directRedirectHost,
+    ...(config.directRedirectBaseUrl
+      ? ['--redirect-base-url', config.directRedirectBaseUrl]
+      : []),
+    ...(config.directProbeToken
+      ? ['--probe-token', config.directProbeToken]
+      : []),
+    '--spacetime-database',
+    config.directSpacetimeDatabase,
+    '--require-wss-upgrade',
+    '--pingora-access-log',
+    config.directPingoraAccessLog,
+    '--access-log-since-lines',
+    config.directAccessLogSinceLines,
+    '--json',
+  ];
+}
+
+async function runEvidenceCommand({
+  name,
+  executable,
+  args,
+  stdoutFile,
+  stderrFile,
+  jsonFile,
+  parseErrorFile,
+  commandFile,
+  parseJson,
+}) {
+  const startedAt = new Date();
+  const result = await runCommand(executable, args);
+  const finishedAt = new Date();
+  const stdoutPath = path.join(bundleDir, stdoutFile);
+  const stderrPath = path.join(bundleDir, stderrFile);
+  const jsonPath = path.join(bundleDir, jsonFile);
+  const parseErrorPath = path.join(bundleDir, parseErrorFile);
+  const commandPath = path.join(bundleDir, commandFile);
+
+  await writeEvidenceFile(stdoutPath, result.stdout);
+  await writeEvidenceFile(stderrPath, result.stderr || result.error);
+
+  const parsed = parseJson(result.stdout);
+  let jsonMetadata = null;
+  let parseErrorMetadata = null;
+  if (parsed.ok) {
+    await writeEvidenceFile(jsonPath, `${JSON.stringify(parsed.value, null, 2)}\n`);
+    jsonMetadata = await buildEvidenceFileMetadata(jsonPath);
+  } else {
+    await writeEvidenceFile(parseErrorPath, `${parsed.error}\n`);
+    parseErrorMetadata = await buildEvidenceFileMetadata(parseErrorPath);
+  }
+
+  const commandRecord = {
+    name,
+    executable,
+    args: redactSecretArgs(args),
+    command: formatCommand(executable, args),
+    exitCode: result.code,
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    durationMs: finishedAt.getTime() - startedAt.getTime(),
+    stdoutPath: path.basename(stdoutPath),
+    stderrPath: path.basename(stderrPath),
+  };
+  await writeEvidenceFile(
+    commandPath,
+    `${JSON.stringify(commandRecord, null, 2)}\n`,
+  );
+  const files = {
+    stdout: await buildEvidenceFileMetadata(stdoutPath),
+    stderr: await buildEvidenceFileMetadata(stderrPath),
+    json: jsonMetadata,
+    parseError: parseErrorMetadata,
+    command: await buildEvidenceFileMetadata(commandPath),
+  };
+
+  return {
+    result,
+    parsed,
+    stdoutPath,
+    stderrPath,
+    jsonPath,
+    parseErrorPath,
+    commandPath,
+    commandRecord,
+    files,
+  };
+}
+
+function runCommand(command, args) {
+  return new Promise((resolve) => {
+    execFile(
+      command,
+      args,
+      {
+        env: process.env,
+        windowsHide: true,
+        maxBuffer: 2 * 1024 * 1024,
+      },
+      (error, stdout, stderr) => {
+        resolve({
+          code: typeof error?.code === 'number' ? error.code : error ? 1 : 0,
+          stdout: String(stdout || ''),
+          stderr: String(stderr || ''),
+          error: error ? error.message : '',
+        });
+      },
+    );
+  });
+}
+
+function parseSnapshotJson(stdout) {
+  try {
+    return { ok: true, value: JSON.parse(stdout) };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+function parseDirectLiveJson(stdout) {
+  const match = DIRECT_LIVE_JSON_PATTERN.exec(stdout);
+  if (!match) {
+    return {
+      ok: false,
+      error: 'direct live stdout 中未找到 JSON 结果对象。',
+    };
+  }
+  const jsonText = extractJsonObject(stdout, match.index);
+  if (!jsonText) {
+    return {
+      ok: false,
+      error: 'direct live stdout 中未找到完整 JSON 结果对象。',
+    };
+  }
+  try {
+    return { ok: true, value: JSON.parse(jsonText) };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+function extractJsonObject(text, startIndex) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let index = startIndex; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === '{') {
+      depth += 1;
+      continue;
+    }
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        return text.slice(startIndex, index + 1);
+      }
+    }
+  }
+
+  return '';
+}
+
+function formatCommand(command, args) {
+  return [command, ...redactSecretArgs(args)].join(' ');
+}
+
+function redactSecretArgs(args) {
+  return args.map((arg, index) =>
+    index > 0 && SECRET_VALUE_FLAGS.has(args[index - 1]) ? '<redacted>' : arg,
+  );
+}
diff --git a/scripts/ops/pingora-cutover-evidence-verify.mjs b/scripts/ops/pingora-cutover-evidence-verify.mjs
new file mode 100644
index 000000000..8c920a414
--- /dev/null
+++ b/scripts/ops/pingora-cutover-evidence-verify.mjs
@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { access, lstat, readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const config = parseArgs(process.argv.slice(2));
+const manifestPath = await resolveManifestPath(config);
+const bundleDir = path.dirname(manifestPath);
+await validateBundleDir(bundleDir);
+
+const manifest = await readManifest(manifestPath);
+validateManifestSchemaVersion(manifest);
+const { verifications, registeredFileNames } =
+  await verifyManifestFiles(bundleDir, manifest);
+const extraFiles = config.allowExtraFiles
+  ? []
+  : await findExtraEvidenceEntries(bundleDir, registeredFileNames);
+const summaryVerification = config.requireSummaryOk
+  ? verifySummaryOk(manifest)
+  : null;
+const failed = verifications.filter((item) => item.status !== 'OK');
+const failedCount =
+  failed.length +
+  extraFiles.length +
+  (summaryVerification && summaryVerification.status !== 'OK' ? 1 : 0);
+
+console.log(
+  `${JSON.stringify(
+    {
+      ok: failedCount === 0,
+      manifestPath,
+      bundleDir,
+      checkedCount: verifications.length,
+      failedCount,
+      allowExtraFiles: config.allowExtraFiles,
+      requireSummaryOk: config.requireSummaryOk,
+      summary: summaryVerification,
+      files: verifications,
+      extraFiles,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (failedCount > 0) {
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const result = {
+    manifestPath: '',
+    bundleDir: '',
+    allowExtraFiles: false,
+    requireSummaryOk: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--manifest':
+        result.manifestPath = requireValue(argv, ++index, arg);
+        break;
+      case '--bundle-dir':
+        result.bundleDir = requireValue(argv, ++index, arg);
+        break;
+      case '--allow-extra-files':
+        result.allowExtraFiles = true;
+        break;
+      case '--require-summary-ok':
+        result.requireSummaryOk = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (result.manifestPath && result.bundleDir) {
+    throw new Error('--manifest 和 --bundle-dir 只能二选一。');
+  }
+  if (!result.manifestPath && !result.bundleDir) {
+    throw new Error('必须提供 --manifest 或 --bundle-dir。');
+  }
+  for (const [label, value] of [
+    ['--manifest', result.manifestPath],
+    ['--bundle-dir', result.bundleDir],
+  ]) {
+    if (!value) {
+      continue;
+    }
+    if (!path.isAbsolute(value)) {
+      throw new Error(`${label} 必须是绝对路径。`);
+    }
+    if (isFilesystemRootPath(value)) {
+      throw new Error(`${label} 不能是文件系统根目录。`);
+    }
+    validateNoControlCharacters(value, label);
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/ops/pingora-cutover-evidence-verify.mjs --manifest <path/to/manifest.json>
+  node scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <path>
+
+Options:
+  --allow-extra-files  允许证据目录中存在 manifest.files 未登记的额外条目；默认拒绝，正式切换归档不应使用。
+  --require-summary-ok 要求 manifest.summary.status 必须是 OK；正式切换 runbook 的即时验真步骤必须使用。
+
+该脚本只读校验 Pingora 直连切换证据目录中的 schemaVersion=1 manifest.files 元数据，确认每个已登记文件的 path / sizeBytes / sha256 与实际文件一致，并默认拒绝证据目录中混入未登记文件、目录或符号链接；null 文件条目会跳过。正式切换 runbook 还会用 --require-summary-ok 把 manifest.summary.status 非 OK 的证据作为失败处理。脚本不会修改证据目录、不会 reload systemd、不会访问 Nginx 或 Pingora。
+`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+async function resolveManifestPath(config) {
+  if (config.manifestPath) {
+    return path.resolve(config.manifestPath);
+  }
+  return path.join(path.resolve(config.bundleDir), 'manifest.json');
+}
+
+async function validateBundleDir(bundleDir) {
+  const resolved = path.resolve(bundleDir);
+  if (isFilesystemRootPath(resolved)) {
+    throw new Error('证据目录不能是文件系统根目录。');
+  }
+  const stats = await lstat(resolved);
+  if (stats.isSymbolicLink()) {
+    throw new Error(`证据目录不能是符号链接: ${resolved}`);
+  }
+  if (!stats.isDirectory()) {
+    throw new Error(`证据目录必须是目录: ${resolved}`);
+  }
+  await access(resolved, fsConstants.R_OK | fsConstants.X_OK);
+}
+
+async function readManifest(manifestPath) {
+  const stats = await lstat(manifestPath);
+  if (stats.isSymbolicLink()) {
+    throw new Error(`manifest 不能是符号链接: ${manifestPath}`);
+  }
+  if (!stats.isFile()) {
+    throw new Error(`manifest 必须是文件: ${manifestPath}`);
+  }
+  let content;
+  try {
+    content = await readFile(manifestPath, 'utf8');
+  } catch (error) {
+    throw new Error(`读取 manifest 失败: ${error.message}`);
+  }
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`manifest 不是合法 JSON: ${error.message}`);
+  }
+}
+
+function validateManifestSchemaVersion(manifest) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error('manifest 顶层必须是 JSON object。');
+  }
+  if (manifest.schemaVersion !== 1) {
+    throw new Error('manifest.schemaVersion 必须是 1。');
+  }
+}
+
+async function verifyManifestFiles(bundleDir, manifest) {
+  if (!manifest.files || typeof manifest.files !== 'object') {
+    throw new Error('manifest 缺少 files object。');
+  }
+
+  const verifications = [];
+  const registeredFileNames = new Set(['manifest.json']);
+  for (const [key, value] of Object.entries(manifest.files)) {
+    if (value === null) {
+      continue;
+    }
+    if (typeof value === 'string') {
+      if (key === 'manifest' && value === 'manifest.json') {
+        continue;
+      }
+      throw new Error(
+        `manifest.files.${key} 必须使用 { path, sizeBytes, sha256 } 元数据对象。`,
+      );
+    }
+    validateMetadata(key, value);
+    registeredFileNames.add(value.path);
+    verifications.push(await verifyMetadata(bundleDir, key, value));
+  }
+  return { verifications, registeredFileNames };
+}
+
+function verifySummaryOk(manifest) {
+  const status = manifest?.summary?.status;
+  if (status === 'OK') {
+    return {
+      status: 'OK',
+      expectedStatus: 'OK',
+      actualStatus: status,
+      reason: null,
+    };
+  }
+  return {
+    status: 'MISMATCH',
+    expectedStatus: 'OK',
+    actualStatus: status ?? null,
+    reason: 'manifest.summary.status is not OK',
+  };
+}
+
+async function findExtraEvidenceEntries(bundleDir, registeredFileNames) {
+  const entries = await readdir(bundleDir, { withFileTypes: true });
+  const extras = [];
+  for (const entry of entries) {
+    if (registeredFileNames.has(entry.name)) {
+      continue;
+    }
+    extras.push({
+      path: entry.name,
+      status: 'MISMATCH',
+      reason: entry.isSymbolicLink()
+        ? 'extra symlink not registered in manifest.files'
+        : entry.isDirectory()
+        ? 'extra directory not registered in manifest.files'
+        : 'extra file not registered in manifest.files',
+    });
+  }
+  return extras.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function validateMetadata(key, value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`manifest.files.${key} 必须是元数据对象或 null。`);
+  }
+  if (typeof value.path !== 'string' || value.path.length === 0) {
+    throw new Error(`manifest.files.${key}.path 必须是非空字符串。`);
+  }
+  if (
+    /[\0\r\n]/u.test(value.path) ||
+    path.isAbsolute(value.path) ||
+    value.path.includes('/') ||
+    value.path.includes('\\') ||
+    value.path === '.' ||
+    value.path === '..' ||
+    value.path.includes('..')
+  ) {
+    throw new Error(
+      `manifest.files.${key}.path 只能是证据目录内的安全文件名: ${value.path}`,
+    );
+  }
+  if (!Number.isSafeInteger(value.sizeBytes) || value.sizeBytes < 0) {
+    throw new Error(`manifest.files.${key}.sizeBytes 必须是非负安全整数。`);
+  }
+  if (typeof value.sha256 !== 'string' || !/^[0-9a-f]{64}$/u.test(value.sha256)) {
+    throw new Error(`manifest.files.${key}.sha256 必须是 64 位小写十六进制。`);
+  }
+}
+
+async function verifyMetadata(bundleDir, key, metadata) {
+  const filePath = path.join(bundleDir, metadata.path);
+  const expectedPath = path.resolve(bundleDir, metadata.path);
+  if (path.dirname(expectedPath) !== path.resolve(bundleDir)) {
+    throw new Error(`manifest.files.${key}.path 超出证据目录: ${metadata.path}`);
+  }
+  let stats;
+  let content;
+  try {
+    const linkStats = await lstat(filePath);
+    if (linkStats.isSymbolicLink()) {
+      return {
+        key,
+        path: metadata.path,
+        status: 'MISMATCH',
+        reason: 'file is symlink',
+      };
+    }
+    if (!linkStats.isFile()) {
+      return {
+        key,
+        path: metadata.path,
+        status: 'MISMATCH',
+        reason: 'not a regular file',
+      };
+    }
+    [stats, content] = await Promise.all([stat(filePath), readFile(filePath)]);
+  } catch (error) {
+    return {
+      key,
+      path: metadata.path,
+      status: 'MISMATCH',
+      reason: error?.code === 'ENOENT' ? 'missing file' : error.message,
+    };
+  }
+
+  const actualSha256 = createHash('sha256').update(content).digest('hex');
+  const sizeMatches = stats.size === metadata.sizeBytes;
+  const sha256Matches = actualSha256 === metadata.sha256;
+  return {
+    key,
+    path: metadata.path,
+    status: sizeMatches && sha256Matches ? 'OK' : 'MISMATCH',
+    expectedSizeBytes: metadata.sizeBytes,
+    actualSizeBytes: stats.size,
+    expectedSha256: metadata.sha256,
+    actualSha256,
+    reason:
+      sizeMatches && sha256Matches
+        ? null
+        : [
+            ...(sizeMatches ? [] : ['size mismatch']),
+            ...(sha256Matches ? [] : ['sha256 mismatch']),
+          ].join(', '),
+  };
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
diff --git a/scripts/ops/pingora-cutover-status-snapshot.mjs b/scripts/ops/pingora-cutover-status-snapshot.mjs
new file mode 100644
index 000000000..5b35b5f5b
--- /dev/null
+++ b/scripts/ops/pingora-cutover-status-snapshot.mjs
@@ -0,0 +1,1052 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const STATUS_RANK = {
+  OK: 0,
+  WARNING: 1,
+  CRITICAL: 2,
+};
+
+const GATEWAY_MODES = new Set(['nginx', 'pingora-direct']);
+const PINGORA_ENV_MODES = new Set(['shadow', 'direct']);
+const SERVICES = [
+  'genarrative-api.service',
+  'spacetimedb.service',
+  'nginx.service',
+  'genarrative-pingora-gateway.service',
+];
+const RELEASE_ARTIFACTS = [
+  'scripts/ops/pingora-cutover-status-snapshot.mjs',
+  'scripts/ops/pingora-current-release-audit.mjs',
+  'scripts/ops/pingora-direct-rehearsal-status.mjs',
+  'scripts/ops/pingora-cutover-evidence-audit.mjs',
+  'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+  'scripts/ops/pingora-cutover-command-evidence.mjs',
+  'scripts/ops/pingora-cutover-evidence-verify.mjs',
+  'scripts/ops/production-health-patrol.mjs',
+  'scripts/check-production-health-patrol-env.mjs',
+  'scripts/check-pingora-release-readiness.mjs',
+  'scripts/check-pingora-direct-preflight.mjs',
+  'scripts/check-pingora-direct-live.mjs',
+  'scripts/check-pingora-canary-live.mjs',
+  'scripts/check-pingora-canary-access-log-parity.mjs',
+  'scripts/deploy/pingora-direct-enable.sh',
+  'scripts/deploy/pingora-direct-rollback.sh',
+  'scripts/deploy/pingora-realpath-canary-enable.sh',
+  'scripts/deploy/pingora-realpath-canary-disable.sh',
+  'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+  'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+  'deploy/systemd/genarrative-pingora-gateway.service',
+  'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
+  'deploy/nginx/snippets/genarrative-pingora-canary.conf',
+  'deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf',
+  'deploy/pingora/pingora-gateway.env.example',
+];
+const SECRET_ENV_KEY_PATTERN =
+  /(?:TOKEN|SECRET|PASSWORD|PRIVATE_KEY|ACCESS_KEY|API_KEY|AUTH|CREDENTIAL)/iu;
+
+const config = parseArgs(process.argv.slice(2));
+const snapshot = await buildSnapshot(config);
+
+console.log(`${JSON.stringify(snapshot, null, 2)}\n`);
+
+if (config.failOnCritical && snapshot.summary.status === 'CRITICAL') {
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const result = {
+    phase: process.env.GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_PHASE || 'manual',
+    releaseRoot:
+      process.env.GENARRATIVE_PINGORA_CUTOVER_RELEASE_ROOT ||
+      '/opt/genarrative/current',
+    healthPatrolEnvFile:
+      process.env.GENARRATIVE_HEALTH_PATROL_ENV_FILE ||
+      '/etc/genarrative/health-patrol.env',
+    pingoraEnvFile:
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE ||
+      '/etc/genarrative/pingora-gateway.env',
+    expectedPingoraEnvMode:
+      process.env.GENARRATIVE_PINGORA_EXPECTED_ENV_MODE || '',
+    expectedGatewayMode:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_GATEWAY_MODE || '',
+    expectedPublicBaseUrl:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL || '',
+    expectedPublicHost:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_HOST || null,
+    requireEmptyPublicHost: readBoolEnv(
+      'GENARRATIVE_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST',
+    ),
+    runHealthPatrol: readBoolEnv(
+      'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL',
+    ),
+    requirePingoraGateway: readBoolEnv(
+      'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_REQUIRE_PINGORA_GATEWAY',
+    ),
+    timeoutMs: parseOptionalPositiveInt(
+      process.env.GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS,
+      5000,
+      'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS',
+    ),
+    failOnCritical: readBoolEnv(
+      'GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL',
+    ),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--phase':
+        result.phase = requireValue(argv, ++index, arg);
+        break;
+      case '--release-root':
+        result.releaseRoot = requireValue(argv, ++index, arg);
+        break;
+      case '--health-patrol-env-file':
+        result.healthPatrolEnvFile = requireValue(argv, ++index, arg);
+        break;
+      case '--pingora-env-file':
+        result.pingoraEnvFile = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-pingora-env-mode':
+        result.expectedPingoraEnvMode = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-gateway-mode':
+        result.expectedGatewayMode = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-public-base-url':
+        result.expectedPublicBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-public-host':
+        result.expectedPublicHost = requireValue(argv, ++index, arg);
+        break;
+      case '--require-empty-public-host':
+        result.requireEmptyPublicHost = true;
+        break;
+      case '--run-health-patrol':
+        result.runHealthPatrol = true;
+        break;
+      case '--require-pingora-gateway':
+        result.requirePingoraGateway = true;
+        break;
+      case '--timeout-ms':
+        result.timeoutMs = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          arg,
+        );
+        break;
+      case '--fail-on-critical':
+        result.failOnCritical = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (!path.isAbsolute(result.releaseRoot)) {
+    throw new Error('--release-root 必须是绝对路径。');
+  }
+  validateNoControlCharacters(result.releaseRoot, '--release-root');
+  if (isFilesystemRootPath(result.releaseRoot)) {
+    throw new Error('--release-root 不能是文件系统根目录。');
+  }
+  if (!path.isAbsolute(result.healthPatrolEnvFile)) {
+    throw new Error('--health-patrol-env-file 必须是绝对路径。');
+  }
+  validateNoControlCharacters(
+    result.healthPatrolEnvFile,
+    '--health-patrol-env-file',
+  );
+  if (isFilesystemRootPath(result.healthPatrolEnvFile)) {
+    throw new Error('--health-patrol-env-file 不能是文件系统根目录。');
+  }
+  if (!path.isAbsolute(result.pingoraEnvFile)) {
+    throw new Error('--pingora-env-file 必须是绝对路径。');
+  }
+  validateNoControlCharacters(result.pingoraEnvFile, '--pingora-env-file');
+  if (isFilesystemRootPath(result.pingoraEnvFile)) {
+    throw new Error('--pingora-env-file 不能是文件系统根目录。');
+  }
+  if (
+    result.expectedGatewayMode &&
+    !GATEWAY_MODES.has(result.expectedGatewayMode)
+  ) {
+    throw new Error(
+      `--expected-gateway-mode 只支持 nginx 或 pingora-direct: ${result.expectedGatewayMode}`,
+    );
+  }
+  if (
+    result.expectedPingoraEnvMode &&
+    !PINGORA_ENV_MODES.has(result.expectedPingoraEnvMode)
+  ) {
+    throw new Error(
+      `--expected-pingora-env-mode 只支持 shadow 或 direct: ${result.expectedPingoraEnvMode}`,
+    );
+  }
+  if (result.expectedPublicHost !== null) {
+    validateHostOption(result.expectedPublicHost, '--expected-public-host');
+  }
+  if (result.expectedPublicHost !== null && result.requireEmptyPublicHost) {
+    throw new Error(
+      '--expected-public-host 和 --require-empty-public-host 不能同时使用。',
+    );
+  }
+  if (result.expectedPublicBaseUrl) {
+    validateHttpUrl(result.expectedPublicBaseUrl, '--expected-public-base-url');
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/ops/pingora-cutover-status-snapshot.mjs [options]
+
+Options:
+  --phase <name>                    写入 JSON 的阶段标签，例如 pre-cutover / post-enable / post-rollback。
+  --release-root <path>             current release 根目录，默认 /opt/genarrative/current。
+  --health-patrol-env-file <path>   health-patrol env 文件，默认 /etc/genarrative/health-patrol.env。
+  --pingora-env-file <path>         pingora-gateway env 文件，默认 /etc/genarrative/pingora-gateway.env。
+  --expected-gateway-mode <mode>    可选，nginx 或 pingora-direct；提供后会检查 env 和 systemd capability 方向。
+  --expected-pingora-env-mode <mode>
+                                    可选，shadow 或 direct；提供后会检查 active Pingora env 姿态。
+  --expected-public-base-url <url>  可选，要求 health-patrol public base URL 与该值一致。
+  --expected-public-host <host>     可选，要求 health-patrol public Host 与该值一致。
+  --require-empty-public-host       可选，要求 health-patrol public Host 为空。
+  --run-health-patrol               读取 env 后执行 current release 随包生产巡检脚本并收录结果。
+  --require-pingora-gateway         要求 current release 自审确认 pingora-gateway、checksum 和 manifest。
+  --timeout-ms <ms>                 systemctl / 子检查超时，默认 5000。
+  --fail-on-critical                如果快照中出现 CRITICAL，则以退出码 1 结束。
+
+该脚本只读采集状态，不写 /etc、不 reload systemd、不修改 Nginx 或 Pingora。
+`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function readBoolEnv(name) {
+  const value = process.env[name];
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return false;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${name} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function parseOptionalPositiveInt(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parseRequiredPositiveInt(raw, label);
+}
+
+function parseRequiredPositiveInt(raw, label) {
+  const text = String(raw ?? '').trim();
+  if (!/^[1-9][0-9]*$/u.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  return Number.parseInt(text, 10);
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function validateHttpUrl(value, label) {
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error('unsupported protocol');
+    }
+  } catch {
+    throw new Error(`${label} 必须是合法 http(s) URL: ${value}`);
+  }
+}
+
+function validateHostOption(value, label) {
+  const raw = String(value);
+  if (raw !== raw.trim() || raw.includes('://') || /[\s/?#@]/.test(raw)) {
+    throw new Error(
+      `${label} 只能是 host 或 host:port，不能包含 scheme、路径、查询、片段或空白字符`,
+    );
+  }
+  try {
+    const parsed = new URL(`https://${raw}`);
+    if (
+      !parsed.hostname ||
+      parsed.pathname !== '/' ||
+      parsed.search ||
+      parsed.hash ||
+      parsed.username ||
+      parsed.password
+    ) {
+      throw new Error('invalid host');
+    }
+  } catch {
+    throw new Error(`${label} 不是合法的 host 或 host:port`);
+  }
+}
+
+async function buildSnapshot(input) {
+  const context = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    phase: input.phase,
+    releaseRoot: input.releaseRoot,
+  };
+  const healthPatrolEnv = await inspectHealthPatrolEnv(input);
+  const pingoraEnv = await inspectPingoraEnv(input);
+  const secrets = collectSecretValues(healthPatrolEnv, pingoraEnv);
+  delete healthPatrolEnv.secretValues;
+  delete pingoraEnv.secretValues;
+  const releaseArtifacts = await inspectReleaseArtifacts(input);
+  const systemd = await inspectSystemd(input);
+  const checks = await runChecks(input, healthPatrolEnv, secrets);
+  const summary = summarize([
+    healthPatrolEnv.status,
+    pingoraEnv.status,
+    releaseArtifacts.status,
+    systemd.status,
+    ...checks.map((check) => check.status),
+  ]);
+
+  return {
+    ...context,
+    summary,
+    healthPatrolEnv,
+    pingoraEnv,
+    releaseArtifacts,
+    systemd,
+    checks,
+  };
+}
+
+async function inspectHealthPatrolEnv(input) {
+  const parsed = await readEnvFile(input.healthPatrolEnvFile);
+  if (parsed.status === 'CRITICAL') {
+    return parsed;
+  }
+
+  const values = parsed.values;
+  const publicHost = values.GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST || '';
+  const publicBaseUrl =
+    values.GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL || '';
+  const gatewayMode = values.GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE || '';
+  const diagnostics = [];
+  let status = 'OK';
+
+  if (input.expectedGatewayMode && gatewayMode !== input.expectedGatewayMode) {
+    diagnostics.push(
+      `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE 应为 ${input.expectedGatewayMode}，实际 ${gatewayMode || '(空)'}`,
+    );
+    status = maxStatus(status, 'CRITICAL');
+  }
+  if (
+    input.expectedPublicBaseUrl &&
+    normalizeBaseUrl(publicBaseUrl) !== normalizeBaseUrl(input.expectedPublicBaseUrl)
+  ) {
+    diagnostics.push(
+      `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL 应为 ${normalizeBaseUrl(input.expectedPublicBaseUrl)}，实际 ${publicBaseUrl || '(空)'}`,
+    );
+    status = maxStatus(status, 'CRITICAL');
+  }
+  if (input.expectedPublicHost !== null && publicHost !== input.expectedPublicHost) {
+    diagnostics.push(
+      `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 应为 ${input.expectedPublicHost}，实际 ${publicHost || '(空)'}`,
+    );
+    status = maxStatus(status, 'CRITICAL');
+  }
+  if (input.requireEmptyPublicHost && publicHost) {
+    diagnostics.push(
+      `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST 应为空，实际 ${publicHost}`,
+    );
+    status = maxStatus(status, 'CRITICAL');
+  }
+
+  return {
+    path: input.healthPatrolEnvFile,
+    status,
+    secretValues: collectSecretValuesFromEnv(values),
+    values: {
+      gatewayMode,
+      publicBaseUrl,
+      publicHost,
+      apiBaseUrl: values.GENARRATIVE_HEALTH_PATROL_API_BASE_URL || '',
+      spacetimeBaseUrl:
+        values.GENARRATIVE_HEALTH_PATROL_SPACETIME_BASE_URL || '',
+      pingoraBaseUrl:
+        values.GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL || '',
+      hasPingoraProbeToken: Boolean(
+        values.GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN ||
+          values.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN,
+      ),
+    },
+    diagnostics,
+  };
+}
+
+async function inspectPingoraEnv(input) {
+  const parsed = await readEnvFile(input.pingoraEnvFile);
+  if (parsed.status === 'CRITICAL') {
+    return {
+      ...parsed,
+      values: {},
+      posture: {
+        expectedMode: input.expectedPingoraEnvMode || '',
+        mode: 'unknown',
+        shadowReady: false,
+        directReady: false,
+        diagnostics: parsed.diagnostics || [],
+      },
+    };
+  }
+  const values = parsed.values;
+  const envValues = {
+    listen: values.GENARRATIVE_PINGORA_GATEWAY_LISTEN || '',
+    tlsListen: values.GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN || '',
+    httpRedirectListen:
+      values.GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN || '',
+    tlsCertFile: values.GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE || '',
+    tlsKeyFile: values.GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE || '',
+    forwardedProto:
+      values.GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO || '',
+    trustXForwardedFor:
+      values.GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR || '',
+    trustedFrontProxyConfirmed:
+      values.GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED || '',
+    protectionEnabled:
+      values.GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED || '',
+    instanceCount:
+      values.GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT || '',
+    sharedProtectionConfirmed:
+      values.GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED || '',
+    hasProbeToken: Boolean(values.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN),
+    accessLogFile:
+      values.GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE || '',
+  };
+  const posture = summarizePingoraEnvPosture(
+    envValues,
+    input.expectedPingoraEnvMode,
+  );
+  const diagnostics = [...parsed.diagnostics, ...posture.diagnostics];
+  const status =
+    input.expectedPingoraEnvMode && posture.diagnostics.length > 0
+      ? 'CRITICAL'
+      : parsed.status;
+  return {
+    path: input.pingoraEnvFile,
+    status,
+    secretValues: collectSecretValuesFromEnv(values),
+    values: envValues,
+    posture,
+    diagnostics,
+  };
+}
+
+function summarizePingoraEnvPosture(values, expectedMode) {
+  const shadowReady =
+    values.listen === '127.0.0.1:18081' &&
+    values.tlsListen === '' &&
+    values.httpRedirectListen === '' &&
+    values.tlsCertFile === '' &&
+    values.tlsKeyFile === '';
+  const directReady =
+    values.tlsListen !== '' &&
+    values.httpRedirectListen !== '' &&
+    values.tlsCertFile !== '' &&
+    values.tlsKeyFile !== '' &&
+    values.forwardedProto === 'https';
+  const mode = directReady ? 'direct' : shadowReady ? 'shadow' : 'mixed';
+  const diagnostics = [];
+
+  if (expectedMode === 'shadow') {
+    if (values.listen !== '127.0.0.1:18081') {
+      diagnostics.push(
+        `Pingora shadow env 要求 listen=127.0.0.1:18081，实际 ${values.listen || '-'}`,
+      );
+    }
+    for (const [label, value] of [
+      ['tlsListen', values.tlsListen],
+      ['httpRedirectListen', values.httpRedirectListen],
+      ['tlsCertFile', values.tlsCertFile],
+      ['tlsKeyFile', values.tlsKeyFile],
+    ]) {
+      if (value !== '') {
+        diagnostics.push(
+          `Pingora shadow env 要求 ${label} 为空，实际 ${value}`,
+        );
+      }
+    }
+  }
+
+  if (expectedMode === 'direct') {
+    for (const [label, value] of [
+      ['tlsListen', values.tlsListen],
+      ['httpRedirectListen', values.httpRedirectListen],
+      ['tlsCertFile', values.tlsCertFile],
+      ['tlsKeyFile', values.tlsKeyFile],
+    ]) {
+      if (value === '') {
+        diagnostics.push(`Pingora direct env 要求 ${label} 已配置。`);
+      }
+    }
+    if (values.forwardedProto !== 'https') {
+      diagnostics.push(
+        `Pingora direct env 要求 forwardedProto=https，实际 ${values.forwardedProto || '-'}`,
+      );
+    }
+  }
+
+  return {
+    expectedMode: expectedMode || '',
+    mode,
+    shadowReady,
+    directReady,
+    diagnostics,
+  };
+}
+
+async function readEnvFile(filePath) {
+  let text;
+  try {
+    text = await readFile(filePath, 'utf8');
+  } catch (error) {
+    return {
+      path: filePath,
+      status: 'CRITICAL',
+      values: {},
+      diagnostics: [`无法读取 env 文件: ${error.message}`],
+    };
+  }
+
+  const values = {};
+  const diagnostics = [];
+  for (const [index, rawLine] of text.split(/\r?\n/u).entries()) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    if (line.startsWith('export ')) {
+      line = line.slice('export '.length).trim();
+    }
+    const equalsIndex = line.indexOf('=');
+    if (equalsIndex <= 0) {
+      diagnostics.push(`第 ${index + 1} 行不是 KEY=VALUE 格式`);
+      continue;
+    }
+    const key = line.slice(0, equalsIndex).trim();
+    values[key] = stripQuotes(line.slice(equalsIndex + 1).trim());
+  }
+
+  return {
+    path: filePath,
+    status: diagnostics.length > 0 ? 'WARNING' : 'OK',
+    values,
+    diagnostics,
+  };
+}
+
+function collectSecretValuesFromEnv(values) {
+  const secrets = [];
+  for (const [key, value] of Object.entries(values || {})) {
+    if (!SECRET_ENV_KEY_PATTERN.test(key) || typeof value !== 'string') {
+      continue;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length > 0) {
+      secrets.push(trimmed);
+    }
+  }
+  return secrets;
+}
+
+function collectSecretValues(...envSnapshots) {
+  const secrets = new Set();
+  for (const snapshot of envSnapshots) {
+    for (const value of snapshot?.secretValues || []) {
+      if (typeof value === 'string' && value.trim()) {
+        secrets.add(value.trim());
+      }
+    }
+  }
+  return [...secrets].sort((left, right) => right.length - left.length);
+}
+
+function stripQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function normalizeBaseUrl(value) {
+  if (!value) {
+    return '';
+  }
+  try {
+    return new URL(value).toString().replace(/\/+$/u, '');
+  } catch {
+    return value;
+  }
+}
+
+async function inspectReleaseArtifacts(input) {
+  const artifacts = [];
+  for (const relativePath of RELEASE_ARTIFACTS) {
+    const fullPath = path.join(input.releaseRoot, relativePath);
+    const artifact = {
+      path: relativePath,
+      exists: false,
+      executable: false,
+      status: 'CRITICAL',
+    };
+    try {
+      const fileStat = await stat(fullPath);
+      artifact.exists = fileStat.isFile() || fileStat.isDirectory();
+      if (fileStat.isFile()) {
+        try {
+          await access(fullPath, fsConstants.X_OK);
+          artifact.executable = true;
+        } catch {
+          artifact.executable = false;
+        }
+      }
+      artifact.status = artifact.exists ? 'OK' : 'CRITICAL';
+    } catch {
+      artifact.status = 'CRITICAL';
+    }
+    artifacts.push(artifact);
+  }
+
+  const status = artifacts.some((artifact) => artifact.status === 'CRITICAL')
+    ? 'CRITICAL'
+    : 'OK';
+  return {
+    status,
+    artifacts,
+  };
+}
+
+async function inspectSystemd(input) {
+  const services = [];
+  for (const service of SERVICES) {
+    services.push(await inspectService(service, input));
+  }
+  const pingoraUnit = await inspectPingoraUnit(input);
+  return {
+    status: summarize([
+      ...services.map((service) => service.status),
+      pingoraUnit.status,
+    ]).status,
+    services,
+    pingoraUnit,
+  };
+}
+
+async function inspectService(service, input) {
+  const expected = isServiceExpected(service, input.expectedGatewayMode);
+  const result = await runCommand('systemctl', ['is-active', service], input);
+  const state = result.stdout.trim() || result.stderr.trim() || result.error;
+  let status = 'OK';
+  let summary = state || 'unknown';
+  if (result.code === 0 && state === 'active') {
+    summary = 'active';
+  } else if (expected) {
+    status = 'CRITICAL';
+  } else {
+    summary = state ? `${state} (not required)` : 'not required';
+  }
+  return {
+    name: service,
+    expectedActive: expected,
+    activeState: state,
+    status,
+    summary,
+    command: result.command,
+  };
+}
+
+function isServiceExpected(service, gatewayMode) {
+  if (
+    service === 'genarrative-api.service' ||
+    service === 'spacetimedb.service'
+  ) {
+    return Boolean(gatewayMode);
+  }
+  if (service === 'nginx.service') {
+    return gatewayMode === 'nginx';
+  }
+  if (service === 'genarrative-pingora-gateway.service') {
+    return gatewayMode === 'pingora-direct';
+  }
+  return false;
+}
+
+async function inspectPingoraUnit(input) {
+  const catResult = await runCommand(
+    'systemctl',
+    ['cat', 'genarrative-pingora-gateway.service'],
+    input,
+  );
+  const showResult = await runCommand(
+    'systemctl',
+    [
+      'show',
+      'genarrative-pingora-gateway.service',
+      '--property=FragmentPath',
+      '--property=DropInPaths',
+      '--property=User',
+      '--property=ExecStart',
+      '--no-pager',
+    ],
+    input,
+  );
+
+  const unitText = catResult.stdout;
+  const hasAmbientCapability = unitText.includes(
+    'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+  );
+  const hasCapabilityBoundingSet = unitText.includes(
+    'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+  );
+  const environmentFiles = [
+    ...unitText.matchAll(/^\s*EnvironmentFile=(.+)$/gmu),
+  ].map((match) => match[1].trim());
+  const environmentFileMatchesPingoraEnvFile = environmentFilesInclude(
+    environmentFiles,
+    input.pingoraEnvFile,
+  );
+  const show = parseSystemctlShow(showResult.stdout);
+  const diagnostics = [];
+  let status = 'OK';
+
+  if (catResult.code !== 0) {
+    diagnostics.push(`systemctl cat 失败: ${catResult.stderr || catResult.error}`);
+    status = 'CRITICAL';
+  }
+  if (showResult.code !== 0) {
+    diagnostics.push(
+      `systemctl show 失败: ${showResult.stderr || showResult.error}`,
+    );
+    status = 'CRITICAL';
+  }
+  if (catResult.code === 0 && !environmentFileMatchesPingoraEnvFile) {
+    diagnostics.push(
+      `systemctl cat genarrative-pingora-gateway.service EnvironmentFile 未包含本次 --pingora-env-file: ${input.pingoraEnvFile}`,
+    );
+    status = 'CRITICAL';
+  }
+  if (input.expectedGatewayMode === 'pingora-direct') {
+    if (!hasAmbientCapability || !hasCapabilityBoundingSet) {
+      diagnostics.push(
+        'pingora-direct 模式必须在 systemd 最终配置中包含 CAP_NET_BIND_SERVICE。',
+      );
+      status = 'CRITICAL';
+    }
+  }
+  if (input.expectedGatewayMode === 'nginx') {
+    if (hasAmbientCapability || hasCapabilityBoundingSet) {
+      diagnostics.push(
+        'nginx 模式下 systemd 最终配置不应残留 CAP_NET_BIND_SERVICE。',
+      );
+      status = 'CRITICAL';
+    }
+  }
+
+  return {
+    status,
+    hasAmbientCapability,
+    hasCapabilityBoundingSet,
+    environmentFiles,
+    environmentFileMatchesPingoraEnvFile,
+    fragmentPath: show.FragmentPath || '',
+    dropInPaths: show.DropInPaths || '',
+    user: show.User || '',
+    execStart: show.ExecStart || '',
+    diagnostics,
+    commands: [catResult.command, showResult.command],
+  };
+}
+
+function environmentFilesInclude(environmentFiles, expectedPath) {
+  return environmentFiles.some((entry) =>
+    splitSystemdEnvironmentFileEntry(entry).includes(expectedPath),
+  );
+}
+
+function splitSystemdEnvironmentFileEntry(entry) {
+  const files = [];
+  for (const word of String(entry || '').split(/\s+/u)) {
+    if (!word) {
+      continue;
+    }
+    let normalized = word.trim();
+    if (normalized.startsWith('-')) {
+      normalized = normalized.slice(1);
+    }
+    if (
+      (normalized.startsWith('"') && normalized.endsWith('"')) ||
+      (normalized.startsWith("'") && normalized.endsWith("'"))
+    ) {
+      normalized = normalized.slice(1, -1);
+    }
+    if (normalized) {
+      files.push(normalized);
+    }
+  }
+  return files;
+}
+
+function parseSystemctlShow(text) {
+  const result = {};
+  for (const line of text.split(/\r?\n/u)) {
+    const equalsIndex = line.indexOf('=');
+    if (equalsIndex <= 0) {
+      continue;
+    }
+    result[line.slice(0, equalsIndex)] = line.slice(equalsIndex + 1);
+  }
+  return result;
+}
+
+async function runChecks(input, healthPatrolEnv, secrets) {
+  const checks = [];
+  checks.push(await runCurrentReleaseAudit(input, secrets));
+  if (input.expectedGatewayMode) {
+    checks.push(await runHealthPatrolEnvCheck(input, secrets));
+  }
+  if (input.runHealthPatrol) {
+    checks.push(await runProductionHealthPatrol(input, healthPatrolEnv, secrets));
+  }
+  return checks;
+}
+
+async function runCurrentReleaseAudit(input, secrets) {
+  const script = path.join(
+    input.releaseRoot,
+    'scripts/ops/pingora-current-release-audit.mjs',
+  );
+  const result = await runCommand(
+    'node',
+    [
+      '--',
+      script,
+      '--release-root',
+      input.releaseRoot,
+      ...(input.requirePingoraGateway ? ['--require-pingora-gateway'] : []),
+      '--systemd-show',
+      '--timeout-ms',
+      String(input.timeoutMs),
+    ],
+    input,
+  );
+  const parsed = parseJsonObject(result.stdout);
+  const details = parsed.ok
+    ? {
+        summary: parsed.value.summary,
+        pingoraGateway: parsed.value.pingoraGateway,
+        checksums: parsed.value.checksums,
+        releaseManifest: parsed.value.releaseManifest,
+        systemd: parsed.value.systemd,
+      }
+    : {
+        parseError: parsed.error,
+      };
+  const check = commandCheck('current-release-audit', result, secrets, details);
+  if (!parsed.ok) {
+    check.status = 'CRITICAL';
+    check.stderr = trimForJson(
+      [check.stderr, `无法解析 current release 自审 JSON: ${parsed.error}`]
+        .filter(Boolean)
+        .join('\n'),
+    );
+  }
+  return check;
+}
+
+async function runHealthPatrolEnvCheck(input, secrets) {
+  const script = path.join(
+    input.releaseRoot,
+    'scripts/check-production-health-patrol-env.mjs',
+  );
+  const args = [
+    '--',
+    script,
+    '--env-file',
+    input.healthPatrolEnvFile,
+    '--expected-gateway-mode',
+    input.expectedGatewayMode,
+  ];
+  if (input.expectedPublicBaseUrl) {
+    args.push('--expected-public-base-url', input.expectedPublicBaseUrl);
+  }
+  if (input.expectedPublicHost !== null) {
+    args.push('--expected-public-host', input.expectedPublicHost);
+  }
+  if (input.requireEmptyPublicHost) {
+    args.push('--require-empty-public-host');
+  }
+  const result = await runCommand('node', args, input);
+  return commandCheck('health-patrol-env-check', result, secrets);
+}
+
+async function runProductionHealthPatrol(input, healthPatrolEnv, secrets) {
+  const script = path.join(
+    input.releaseRoot,
+    'scripts/ops/production-health-patrol.mjs',
+  );
+  const rawEnv = await readEnvFile(input.healthPatrolEnvFile);
+  const env = {
+    ...process.env,
+    ...readEnvValuesForChild(rawEnv.status === 'CRITICAL' ? healthPatrolEnv : rawEnv),
+  };
+  const result = await runCommand(
+    'node',
+    ['--', script, '--json'],
+    input,
+    env,
+  );
+  return commandCheck('production-health-patrol', result, secrets);
+}
+
+function readEnvValuesForChild(healthPatrolEnv) {
+  if (!healthPatrolEnv.values) {
+    return {};
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(healthPatrolEnv.values)) {
+    if (typeof value === 'string') {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function commandCheck(name, result, secrets = [], details = undefined) {
+  return {
+    name,
+    status: result.code === 0 ? 'OK' : 'CRITICAL',
+    code: result.code,
+    command: result.command,
+    stdout: trimForJson(redactSecrets(result.stdout, secrets)),
+    stderr: trimForJson(redactSecrets(result.stderr || result.error, secrets)),
+    ...(details === undefined ? {} : { details }),
+  };
+}
+
+function redactSecrets(value, secrets) {
+  let text = String(value || '');
+  for (const secret of secrets) {
+    if (!secret) {
+      continue;
+    }
+    text = text.split(secret).join('<redacted>');
+  }
+  return text;
+}
+
+function runCommand(command, args, input, env = process.env) {
+  validateNoControlCharacters(command, '子命令可执行文件');
+  for (const arg of args) {
+    validateNoControlCharacters(arg, '子命令参数');
+  }
+  return new Promise((resolve) => {
+    execFile(
+      command,
+      args,
+      {
+        env,
+        timeout: input.timeoutMs,
+        windowsHide: true,
+        maxBuffer: 1024 * 1024,
+      },
+      (error, stdout, stderr) => {
+        resolve({
+          command: formatCommand(command, args),
+          code: typeof error?.code === 'number' ? error.code : error ? 1 : 0,
+          stdout: String(stdout || ''),
+          stderr: String(stderr || ''),
+          timedOut: Boolean(error?.killed),
+          error: error ? error.message : '',
+        });
+      },
+    );
+  });
+}
+
+function formatCommand(command, args) {
+  const secretValueFlags = new Set([
+    '--pingora-probe-token',
+    '--probe-token',
+    '--direct-probe-token',
+  ]);
+  const redactedArgs = args.map((arg, index) =>
+    index > 0 && secretValueFlags.has(args[index - 1]) ? '<redacted>' : arg,
+  );
+  return [command, ...redactedArgs].join(' ');
+}
+
+function trimForJson(value) {
+  const text = String(value || '').trim();
+  if (text.length <= 1000) {
+    return text;
+  }
+  return `${text.slice(0, 1000)}...<truncated>`;
+}
+
+function parseJsonObject(value) {
+  try {
+    return { ok: true, value: JSON.parse(value) };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+function summarize(statuses) {
+  const normalized = statuses.filter(Boolean);
+  const status = normalized.reduce(
+    (current, item) => maxStatus(current, item),
+    'OK',
+  );
+  return {
+    status,
+    criticalCount: normalized.filter((item) => item === 'CRITICAL').length,
+    warningCount: normalized.filter((item) => item === 'WARNING').length,
+  };
+}
+
+function maxStatus(left, right) {
+  return STATUS_RANK[right] > STATUS_RANK[left] ? right : left;
+}
diff --git a/scripts/ops/pingora-direct-rehearsal-status.mjs b/scripts/ops/pingora-direct-rehearsal-status.mjs
new file mode 100644
index 000000000..91dfe13bd
--- /dev/null
+++ b/scripts/ops/pingora-direct-rehearsal-status.mjs
@@ -0,0 +1,966 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const STATUS_RANK = {
+  OK: 0,
+  WARNING: 1,
+  CRITICAL: 2,
+};
+
+const PUBLIC_GATEWAYS = new Set(['none', 'nginx', 'pingora-direct']);
+const GATEWAY_MODES = new Set(['nginx', 'pingora-direct']);
+const DEFAULT_PORTS = [80, 443, 18081, 18083];
+const SECRET_ENV_KEY_PATTERN =
+  /(?:TOKEN|SECRET|PASSWORD|PRIVATE_KEY|ACCESS_KEY|API_KEY|AUTH|CREDENTIAL)/iu;
+
+const config = parseArgs(process.argv.slice(2));
+const status = await buildStatus(config);
+
+console.log(`${JSON.stringify(status, null, 2)}\n`);
+
+if (config.failOnCritical && status.summary.status === 'CRITICAL') {
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const result = {
+    releaseRoot:
+      process.env.GENARRATIVE_PINGORA_REHEARSAL_RELEASE_ROOT ||
+      '/opt/genarrative/current',
+    healthPatrolEnvFile:
+      process.env.GENARRATIVE_HEALTH_PATROL_ENV_FILE ||
+      '/etc/genarrative/health-patrol.env',
+    pingoraEnvFile:
+      process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE ||
+      '/etc/genarrative/pingora-gateway.env',
+    realpathConfigFile:
+      process.env.GENARRATIVE_PINGORA_REALPATH_CANARY_CONFIG_FILE ||
+      '/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf',
+    expectedPublicGateway:
+      process.env.GENARRATIVE_PINGORA_REHEARSAL_EXPECT_PUBLIC_GATEWAY ||
+      'none',
+    expectedHealthPatrolGatewayMode:
+      process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_GATEWAY_MODE || '',
+    requireRealpathCanary: readBoolEnv(
+      'GENARRATIVE_PINGORA_REHEARSAL_REQUIRE_REALPATH_CANARY',
+    ),
+    requirePingoraShadow: readBoolEnv(
+      'GENARRATIVE_PINGORA_REHEARSAL_REQUIRE_PINGORA_SHADOW',
+    ),
+    requireCurrentReleaseGateway: readBoolEnv(
+      'GENARRATIVE_PINGORA_REHEARSAL_REQUIRE_CURRENT_RELEASE_GATEWAY',
+    ),
+    timeoutMs: parseOptionalPositiveInt(
+      process.env.GENARRATIVE_PINGORA_REHEARSAL_TIMEOUT_MS,
+      5000,
+      'GENARRATIVE_PINGORA_REHEARSAL_TIMEOUT_MS',
+    ),
+    failOnCritical: readBoolEnv(
+      'GENARRATIVE_PINGORA_REHEARSAL_FAIL_ON_CRITICAL',
+    ),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--release-root':
+        result.releaseRoot = requireValue(argv, ++index, arg);
+        break;
+      case '--health-patrol-env-file':
+        result.healthPatrolEnvFile = requireValue(argv, ++index, arg);
+        break;
+      case '--pingora-env-file':
+        result.pingoraEnvFile = requireValue(argv, ++index, arg);
+        break;
+      case '--realpath-config-file':
+        result.realpathConfigFile = requireValue(argv, ++index, arg);
+        break;
+      case '--expect-public-gateway':
+        result.expectedPublicGateway = requireValue(argv, ++index, arg);
+        break;
+      case '--expected-health-patrol-gateway-mode':
+        result.expectedHealthPatrolGatewayMode = requireValue(
+          argv,
+          ++index,
+          arg,
+        );
+        break;
+      case '--require-realpath-canary':
+        result.requireRealpathCanary = true;
+        break;
+      case '--require-pingora-shadow':
+        result.requirePingoraShadow = true;
+        break;
+      case '--require-current-release-gateway':
+        result.requireCurrentReleaseGateway = true;
+        break;
+      case '--timeout-ms':
+        result.timeoutMs = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          arg,
+        );
+        break;
+      case '--fail-on-critical':
+        result.failOnCritical = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  validateConfig(result);
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/ops/pingora-direct-rehearsal-status.mjs [options]
+
+Options:
+  --release-root <path>             current release 根目录，默认 /opt/genarrative/current。
+  --health-patrol-env-file <path>   health-patrol env 文件，默认 /etc/genarrative/health-patrol.env。
+  --pingora-env-file <path>         pingora-gateway env 文件，默认 /etc/genarrative/pingora-gateway.env。
+  --realpath-config-file <path>     realpath canary Nginx 配置，默认 /etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf。
+  --expect-public-gateway <mode>    可选，none / nginx / pingora-direct；nginx 模式会要求 80/443 仍由 Nginx 接流。
+  --expected-health-patrol-gateway-mode <mode>
+                                    可选，nginx 或 pingora-direct；不传时随 --expect-public-gateway 推导。
+  --require-realpath-canary         要求 realpath canary 配置存在，且 127.0.0.1:18083 由 Nginx 监听。
+  --require-pingora-shadow          要求 Pingora shadow 127.0.0.1:18081 正在监听。
+  --require-current-release-gateway 要求 current release 自审确认 pingora-gateway、checksum 和 manifest。
+  --timeout-ms <ms>                 systemctl / ss / 子检查超时，默认 5000。
+  --fail-on-critical                如果状态中出现 CRITICAL，则以退出码 1 结束。
+
+该脚本只读采集 dev / release 上的 Pingora 直连切换彩排状态，不写 /etc、不 reload systemd、不修改 Nginx 或 Pingora。
+`);
+}
+
+function validateConfig(input) {
+  for (const [label, value] of [
+    ['--release-root', input.releaseRoot],
+    ['--health-patrol-env-file', input.healthPatrolEnvFile],
+    ['--pingora-env-file', input.pingoraEnvFile],
+    ['--realpath-config-file', input.realpathConfigFile],
+  ]) {
+    validateSafeAbsoluteFilePath(value, label);
+  }
+
+  if (!PUBLIC_GATEWAYS.has(input.expectedPublicGateway)) {
+    throw new Error(
+      `--expect-public-gateway 只支持 none / nginx / pingora-direct: ${input.expectedPublicGateway}`,
+    );
+  }
+  if (
+    input.expectedHealthPatrolGatewayMode &&
+    !GATEWAY_MODES.has(input.expectedHealthPatrolGatewayMode)
+  ) {
+    throw new Error(
+      `--expected-health-patrol-gateway-mode 只支持 nginx 或 pingora-direct: ${input.expectedHealthPatrolGatewayMode}`,
+    );
+  }
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function readBoolEnv(name) {
+  const value = process.env[name];
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return false;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${name} 必须是布尔值 true/false 或 1/0。`);
+}
+
+function parseOptionalPositiveInt(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parseRequiredPositiveInt(raw, label);
+}
+
+function parseRequiredPositiveInt(raw, label) {
+  const text = String(raw ?? '').trim();
+  if (!/^[1-9][0-9]*$/u.test(text)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  return Number.parseInt(text, 10);
+}
+
+function validateSafeAbsoluteFilePath(value, label) {
+  validateNoControlCharacters(value, label);
+  if (!path.isAbsolute(value)) {
+    throw new Error(`${label} 必须是绝对路径。`);
+  }
+  if (isFilesystemRootPath(value)) {
+    throw new Error(`${label} 不能是文件系统根目录。`);
+  }
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
+
+async function buildStatus(input) {
+  const healthPatrolEnv = await inspectHealthPatrolEnv(input);
+  const pingoraEnv = await inspectPingoraEnv(input);
+  const secrets = collectSecretValues(healthPatrolEnv, pingoraEnv);
+  delete healthPatrolEnv.secretValues;
+  delete pingoraEnv.secretValues;
+  const services = await inspectServices(input);
+  const systemd = await inspectPingoraSystemd(input);
+  const ports = await inspectPorts(input);
+  const realpathCanary = await inspectRealpathCanary(input, ports);
+  const currentReleaseAudit = await inspectCurrentRelease(input, secrets);
+  const publicBoundary = inspectPublicBoundary(input, ports, systemd);
+  const checks = [
+    healthPatrolEnv.status,
+    pingoraEnv.status,
+    services.status,
+    systemd.status,
+    ports.status,
+    realpathCanary.status,
+    currentReleaseAudit.status,
+    publicBoundary.status,
+  ];
+
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    summary: summarize(checks),
+    releaseRoot: input.releaseRoot,
+    expectations: {
+      publicGateway: input.expectedPublicGateway,
+      healthPatrolGatewayMode: expectedHealthPatrolGatewayMode(input),
+      requireRealpathCanary: input.requireRealpathCanary,
+      requirePingoraShadow: input.requirePingoraShadow,
+      requireCurrentReleaseGateway: input.requireCurrentReleaseGateway,
+    },
+    publicBoundary,
+    ports,
+    services,
+    systemd,
+    healthPatrolEnv,
+    pingoraEnv,
+    realpathCanary,
+    currentReleaseAudit,
+  };
+}
+
+async function inspectHealthPatrolEnv(input) {
+  const parsed = await readEnvFile(input.healthPatrolEnvFile);
+  if (parsed.status === 'CRITICAL') {
+    return parsed;
+  }
+
+  const values = parsed.values;
+  const expectedMode = expectedHealthPatrolGatewayMode(input);
+  const gatewayMode = values.GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE || '';
+  const diagnostics = [...parsed.diagnostics];
+  let status = parsed.status;
+
+  if (expectedMode && gatewayMode !== expectedMode) {
+    diagnostics.push(
+      `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE 应为 ${expectedMode}，实际 ${gatewayMode || '(空)'}`,
+    );
+    status = maxStatus(status, 'CRITICAL');
+  }
+
+  return {
+    path: input.healthPatrolEnvFile,
+    status,
+    secretValues: collectSecretValuesFromEnv(values),
+    values: {
+      gatewayMode,
+      publicBaseUrl:
+        values.GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL || '',
+      publicHost: values.GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST || '',
+      apiBaseUrl: values.GENARRATIVE_HEALTH_PATROL_API_BASE_URL || '',
+      pingoraBaseUrl:
+        values.GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL || '',
+      hasPingoraProbeToken: Boolean(
+        values.GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN ||
+          values.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN,
+      ),
+    },
+    diagnostics,
+  };
+}
+
+function expectedHealthPatrolGatewayMode(input) {
+  if (input.expectedHealthPatrolGatewayMode) {
+    return input.expectedHealthPatrolGatewayMode;
+  }
+  if (input.expectedPublicGateway === 'nginx') {
+    return 'nginx';
+  }
+  if (input.expectedPublicGateway === 'pingora-direct') {
+    return 'pingora-direct';
+  }
+  return '';
+}
+
+async function inspectPingoraEnv(input) {
+  const parsed = await readEnvFile(input.pingoraEnvFile);
+  if (parsed.status === 'CRITICAL') {
+    return {
+      ...parsed,
+      values: {},
+    };
+  }
+  const values = parsed.values;
+  return {
+    path: input.pingoraEnvFile,
+    status: parsed.status,
+    secretValues: collectSecretValuesFromEnv(values),
+    values: {
+      listen: values.GENARRATIVE_PINGORA_GATEWAY_LISTEN || '',
+      tlsListen: values.GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN || '',
+      httpRedirectListen:
+        values.GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN || '',
+      tlsCertFile: values.GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE || '',
+      hasTlsKeyFile: Boolean(
+        values.GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE,
+      ),
+      hasProbeToken: Boolean(values.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN),
+      accessLogFile:
+        values.GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE || '',
+      compressionAlgorithms:
+        values.GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS || '',
+      trustXForwardedFor:
+        values.GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR || '',
+    },
+    diagnostics: parsed.diagnostics,
+  };
+}
+
+async function readEnvFile(filePath) {
+  let text;
+  try {
+    text = await readFile(filePath, 'utf8');
+  } catch (error) {
+    return {
+      path: filePath,
+      status: 'CRITICAL',
+      values: {},
+      diagnostics: [`无法读取 env 文件: ${error.message}`],
+    };
+  }
+
+  const values = {};
+  const diagnostics = [];
+  for (const [index, rawLine] of text.split(/\r?\n/u).entries()) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    if (line.startsWith('export ')) {
+      line = line.slice('export '.length).trim();
+    }
+    const equalsIndex = line.indexOf('=');
+    if (equalsIndex <= 0) {
+      diagnostics.push(`第 ${index + 1} 行不是 KEY=VALUE 格式`);
+      continue;
+    }
+    const key = line.slice(0, equalsIndex).trim();
+    values[key] = stripQuotes(line.slice(equalsIndex + 1).trim());
+  }
+
+  return {
+    path: filePath,
+    status: diagnostics.length > 0 ? 'WARNING' : 'OK',
+    values,
+    diagnostics,
+  };
+}
+
+function stripQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function collectSecretValuesFromEnv(values) {
+  const secrets = [];
+  for (const [key, value] of Object.entries(values || {})) {
+    if (!SECRET_ENV_KEY_PATTERN.test(key) || typeof value !== 'string') {
+      continue;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length > 0) {
+      secrets.push(trimmed);
+    }
+  }
+  return secrets;
+}
+
+function collectSecretValues(...envSnapshots) {
+  const secrets = new Set();
+  for (const snapshot of envSnapshots) {
+    for (const value of snapshot?.secretValues || []) {
+      if (typeof value === 'string' && value.trim()) {
+        secrets.add(value.trim());
+      }
+    }
+  }
+  return [...secrets].sort((left, right) => right.length - left.length);
+}
+
+async function inspectServices(input) {
+  const serviceNames = [
+    'nginx.service',
+    'genarrative-pingora-gateway.service',
+    'genarrative-api.service',
+    'spacetimedb.service',
+  ];
+  const services = [];
+  for (const service of serviceNames) {
+    services.push(await inspectService(service, input));
+  }
+  return {
+    status: summarize(services.map((service) => service.status)).status,
+    services,
+  };
+}
+
+async function inspectService(service, input) {
+  const result = await runCommand('systemctl', ['is-active', service], input);
+  const state = result.stdout.trim() || result.stderr.trim() || result.error;
+  let status = 'OK';
+  if (service === 'nginx.service' && input.expectedPublicGateway === 'nginx') {
+    status = result.code === 0 && state === 'active' ? 'OK' : 'CRITICAL';
+  } else if (
+    service === 'genarrative-pingora-gateway.service' &&
+    (input.requirePingoraShadow ||
+      input.expectedPublicGateway === 'pingora-direct')
+  ) {
+    status = result.code === 0 && state === 'active' ? 'OK' : 'CRITICAL';
+  } else if (
+    (service === 'genarrative-api.service' ||
+      service === 'spacetimedb.service') &&
+    result.code !== 0
+  ) {
+    status = 'WARNING';
+  }
+  return {
+    name: service,
+    activeState: state || 'unknown',
+    status,
+    command: result.command,
+  };
+}
+
+async function inspectPingoraSystemd(input) {
+  const catResult = await runCommand(
+    'systemctl',
+    ['cat', 'genarrative-pingora-gateway.service'],
+    input,
+  );
+  const showResult = await runCommand(
+    'systemctl',
+    [
+      'show',
+      'genarrative-pingora-gateway.service',
+      '--property=FragmentPath',
+      '--property=DropInPaths',
+      '--property=User',
+      '--property=ExecStart',
+      '--no-pager',
+    ],
+    input,
+  );
+  const unitText = catResult.stdout;
+  const hasAmbientCapability = unitText.includes(
+    'AmbientCapabilities=CAP_NET_BIND_SERVICE',
+  );
+  const hasCapabilityBoundingSet = unitText.includes(
+    'CapabilityBoundingSet=CAP_NET_BIND_SERVICE',
+  );
+  const environmentFiles = [
+    ...unitText.matchAll(/^\s*EnvironmentFile=(.+)$/gmu),
+  ].map((match) => match[1].trim());
+  const environmentFileMatchesPingoraEnvFile = environmentFilesInclude(
+    environmentFiles,
+    input.pingoraEnvFile,
+  );
+  const show = parseSystemctlShow(showResult.stdout);
+  const diagnostics = [];
+  let status = 'OK';
+
+  if (catResult.code !== 0) {
+    diagnostics.push(`systemctl cat 失败: ${catResult.stderr || catResult.error}`);
+    status = 'CRITICAL';
+  }
+  if (showResult.code !== 0) {
+    diagnostics.push(
+      `systemctl show 失败: ${showResult.stderr || showResult.error}`,
+    );
+    status = 'CRITICAL';
+  }
+  if (catResult.code === 0 && !environmentFileMatchesPingoraEnvFile) {
+    diagnostics.push(
+      `systemctl cat genarrative-pingora-gateway.service EnvironmentFile 未包含本次 --pingora-env-file: ${input.pingoraEnvFile}`,
+    );
+    status = 'CRITICAL';
+  }
+  if (
+    input.expectedPublicGateway === 'nginx' &&
+    (hasAmbientCapability || hasCapabilityBoundingSet)
+  ) {
+    diagnostics.push(
+      'Nginx 接公网阶段不应残留 Pingora 低端口 CAP_NET_BIND_SERVICE。',
+    );
+    status = 'CRITICAL';
+  }
+  if (
+    input.expectedPublicGateway === 'pingora-direct' &&
+    (!hasAmbientCapability || !hasCapabilityBoundingSet)
+  ) {
+    diagnostics.push(
+      'pingora-direct 接公网阶段必须在 systemd 最终配置中包含 CAP_NET_BIND_SERVICE。',
+    );
+    status = 'CRITICAL';
+  }
+
+  return {
+    status,
+    hasAmbientCapability,
+    hasCapabilityBoundingSet,
+    environmentFiles,
+    environmentFileMatchesPingoraEnvFile,
+    fragmentPath: show.FragmentPath || '',
+    dropInPaths: show.DropInPaths || '',
+    user: show.User || '',
+    execStart: show.ExecStart || '',
+    diagnostics,
+    commands: [catResult.command, showResult.command],
+  };
+}
+
+function environmentFilesInclude(environmentFiles, expectedPath) {
+  return environmentFiles.some((entry) =>
+    splitSystemdEnvironmentFileEntry(entry).includes(expectedPath),
+  );
+}
+
+function splitSystemdEnvironmentFileEntry(entry) {
+  const files = [];
+  for (const word of String(entry || '').split(/\s+/u)) {
+    if (!word) {
+      continue;
+    }
+    let normalized = word.trim();
+    if (normalized.startsWith('-')) {
+      normalized = normalized.slice(1);
+    }
+    if (
+      (normalized.startsWith('"') && normalized.endsWith('"')) ||
+      (normalized.startsWith("'") && normalized.endsWith("'"))
+    ) {
+      normalized = normalized.slice(1, -1);
+    }
+    if (normalized) {
+      files.push(normalized);
+    }
+  }
+  return files;
+}
+
+function parseSystemctlShow(text) {
+  const result = {};
+  for (const line of text.split(/\r?\n/u)) {
+    const equalsIndex = line.indexOf('=');
+    if (equalsIndex <= 0) {
+      continue;
+    }
+    result[line.slice(0, equalsIndex)] = line.slice(equalsIndex + 1);
+  }
+  return result;
+}
+
+async function inspectPorts(input) {
+  const result = await runCommand('ss', ['-H', '-ltnp'], input);
+  const listeners = result.code === 0 ? parseSsOutput(result.stdout) : [];
+  const byPort = {};
+  const statuses = [];
+  for (const port of DEFAULT_PORTS) {
+    const portListeners = listeners.filter((item) => item.port === port);
+    const entry = inspectPort(port, portListeners, input);
+    byPort[String(port)] = entry;
+    statuses.push(entry.status);
+  }
+  if (result.code !== 0) {
+    statuses.push('CRITICAL');
+  }
+  return {
+    status: summarize(statuses).status,
+    command: result.command,
+    error: result.code === 0 ? '' : trimForJson(result.stderr || result.error),
+    byPort,
+  };
+}
+
+function parseSsOutput(stdout) {
+  const listeners = [];
+  for (const line of String(stdout || '').split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const parts = trimmed.split(/\s+/u);
+    const local = parts[3] || '';
+    const port = parsePortFromLocalAddress(local);
+    if (!port) {
+      continue;
+    }
+    const processText = parts.slice(5).join(' ');
+    const processNames = [
+      ...new Set([...processText.matchAll(/"([^"]+)"/gu)].map((match) => match[1])),
+    ];
+    listeners.push({
+      localAddress: local,
+      port,
+      loopback: isLoopbackLocalAddress(local),
+      processNames,
+    });
+  }
+  return listeners;
+}
+
+function parsePortFromLocalAddress(value) {
+  const bracketMatch = String(value).match(/^\[[^\]]+\]:(\d+)$/u);
+  const plainMatch = String(value).match(/:(\d+)$/u);
+  const portText = bracketMatch?.[1] || plainMatch?.[1] || '';
+  const port = Number.parseInt(portText, 10);
+  return Number.isInteger(port) && port > 0 ? port : null;
+}
+
+function isLoopbackLocalAddress(value) {
+  const text = String(value || '').toLowerCase();
+  return (
+    text.startsWith('127.') ||
+    text.startsWith('[::1]') ||
+    text.startsWith('::1') ||
+    text.startsWith('localhost:')
+  );
+}
+
+function inspectPort(port, listeners, input) {
+  const hasNginx = listeners.some((listener) =>
+    listener.processNames.some((name) => name.toLowerCase().includes('nginx')),
+  );
+  const hasPingora = listeners.some((listener) =>
+    listener.processNames.some((name) => name.toLowerCase().includes('pingora')),
+  );
+  const hasUnknownProcess =
+    listeners.length > 0 &&
+    listeners.some((listener) => listener.processNames.length === 0);
+  const loopbackOnly =
+    listeners.length > 0 && listeners.every((listener) => listener.loopback);
+  const diagnostics = [];
+  let status = 'OK';
+
+  if ([80, 443].includes(port)) {
+    if (input.expectedPublicGateway === 'nginx') {
+      if (listeners.length === 0) {
+        diagnostics.push(`${port} 未监听，Nginx 公网入口未就绪。`);
+        status = 'CRITICAL';
+      }
+      if (!hasNginx) {
+        diagnostics.push(`${port} 未看到 Nginx 监听。`);
+        status = 'CRITICAL';
+      }
+      if (hasPingora) {
+        diagnostics.push(`${port} 已被 Pingora 监听，不能作为未切公网彩排状态。`);
+        status = 'CRITICAL';
+      }
+    }
+    if (input.expectedPublicGateway === 'pingora-direct') {
+      if (!hasPingora) {
+        diagnostics.push(`${port} 未看到 Pingora 监听。`);
+        status = 'CRITICAL';
+      }
+      if (hasNginx) {
+        diagnostics.push(`${port} 仍由 Nginx 监听。`);
+        status = 'CRITICAL';
+      }
+    }
+  }
+
+  if (port === 18081 && input.requirePingoraShadow) {
+    if (!hasPingora) {
+      diagnostics.push('18081 未看到 Pingora shadow 监听。');
+      status = 'CRITICAL';
+    }
+    if (!loopbackOnly) {
+      diagnostics.push('Pingora shadow 18081 必须只监听 loopback。');
+      status = 'CRITICAL';
+    }
+  }
+
+  if (port === 18083 && input.requireRealpathCanary) {
+    if (!hasNginx) {
+      diagnostics.push('18083 未看到 Nginx realpath canary 监听。');
+      status = 'CRITICAL';
+    }
+    if (!loopbackOnly) {
+      diagnostics.push('Nginx realpath canary 18083 必须只监听 loopback。');
+      status = 'CRITICAL';
+    }
+  }
+
+  if (
+    hasUnknownProcess &&
+    ([80, 443].includes(port) ||
+      (port === 18081 && input.requirePingoraShadow) ||
+      (port === 18083 && input.requireRealpathCanary))
+  ) {
+    diagnostics.push('ss 未返回进程名，无法确认监听归属。');
+    status = maxStatus(status, 'WARNING');
+  }
+
+  return {
+    port,
+    status,
+    listening: listeners.length > 0,
+    loopbackOnly,
+    hasNginx,
+    hasPingora,
+    hasUnknownProcess,
+    listeners,
+    diagnostics,
+  };
+}
+
+async function inspectRealpathCanary(input, ports) {
+  const diagnostics = [];
+  let status = 'OK';
+  let exists = false;
+  let templateLooksValid = false;
+  try {
+    const fileStat = await stat(input.realpathConfigFile);
+    exists = fileStat.isFile();
+  } catch {
+    exists = false;
+  }
+
+  if (!exists) {
+    diagnostics.push(`realpath canary 配置不存在: ${input.realpathConfigFile}`);
+    status = input.requireRealpathCanary ? 'CRITICAL' : 'WARNING';
+  } else {
+    const content = await readFile(input.realpathConfigFile, 'utf8');
+    const requiredSnippets = [
+      'listen 127.0.0.1:18083',
+      'genarrative-pingora-realpath-canary.access.log',
+      'X-Genarrative-Nginx-Handoff pingora-realpath-canary',
+    ];
+    const missing = requiredSnippets.filter((snippet) => !content.includes(snippet));
+    templateLooksValid = missing.length === 0;
+    if (missing.length > 0) {
+      diagnostics.push(`realpath canary 配置缺少关键片段: ${missing.join(', ')}`);
+      status = 'CRITICAL';
+    }
+  }
+
+  const portStatus = ports.byPort['18083'];
+  if (input.requireRealpathCanary && portStatus?.status === 'CRITICAL') {
+    status = 'CRITICAL';
+  }
+
+  return {
+    path: input.realpathConfigFile,
+    status,
+    exists,
+    templateLooksValid,
+    port: portStatus,
+    diagnostics,
+  };
+}
+
+async function inspectCurrentRelease(input, secrets) {
+  const script = path.join(
+    input.releaseRoot,
+    'scripts/ops/pingora-current-release-audit.mjs',
+  );
+  try {
+    await access(script, fsConstants.R_OK);
+  } catch (error) {
+    return {
+      status: 'CRITICAL',
+      script,
+      code: null,
+      diagnostics: [`无法读取 current release 自审脚本: ${error.message}`],
+    };
+  }
+
+  const args = [
+    '--',
+    script,
+    '--release-root',
+    input.releaseRoot,
+    '--systemd-show',
+    '--timeout-ms',
+    String(input.timeoutMs),
+  ];
+  if (input.requireCurrentReleaseGateway) {
+    args.push('--require-pingora-gateway');
+  }
+  const result = await runCommand('node', args, input);
+  const parsed = parseJsonObject(result.stdout);
+  let status = result.code === 0 ? 'OK' : 'CRITICAL';
+  const diagnostics = [];
+  if (!parsed.ok) {
+    diagnostics.push(`无法解析 current release 自审 JSON: ${parsed.error}`);
+    status = 'CRITICAL';
+  }
+  return {
+    status,
+    script,
+    code: result.code,
+    command: result.command,
+    summary: parsed.ok ? parsed.value?.summary || null : null,
+    pingoraGateway: parsed.ok ? parsed.value?.pingoraGateway || null : null,
+    releaseManifest: parsed.ok ? parsed.value?.releaseManifest || null : null,
+    stdout: trimForJson(redactSecrets(result.stdout, secrets)),
+    stderr: trimForJson(redactSecrets(result.stderr || result.error, secrets)),
+    diagnostics,
+  };
+}
+
+function inspectPublicBoundary(input, ports, systemd) {
+  const diagnostics = [];
+  let status = 'OK';
+  if (input.expectedPublicGateway === 'none') {
+    return {
+      status,
+      expectedPublicGateway: input.expectedPublicGateway,
+      diagnostics,
+    };
+  }
+
+  for (const port of [80, 443]) {
+    const portStatus = ports.byPort[String(port)];
+    if (portStatus?.status === 'CRITICAL') {
+      status = 'CRITICAL';
+      diagnostics.push(...portStatus.diagnostics);
+    }
+  }
+  if (systemd.status === 'CRITICAL') {
+    status = 'CRITICAL';
+    diagnostics.push(...systemd.diagnostics);
+  }
+
+  return {
+    status,
+    expectedPublicGateway: input.expectedPublicGateway,
+    diagnostics,
+  };
+}
+
+function runCommand(command, args, input, env = process.env) {
+  validateNoControlCharacters(command, '子命令可执行文件');
+  for (const arg of args) {
+    validateNoControlCharacters(arg, '子命令参数');
+  }
+  return new Promise((resolve) => {
+    execFile(
+      command,
+      args,
+      {
+        env,
+        timeout: input.timeoutMs,
+        windowsHide: true,
+        maxBuffer: 1024 * 1024,
+      },
+      (error, stdout, stderr) => {
+        resolve({
+          command: formatCommand(command, args),
+          code: typeof error?.code === 'number' ? error.code : error ? 1 : 0,
+          stdout: String(stdout || ''),
+          stderr: String(stderr || ''),
+          timedOut: Boolean(error?.killed),
+          error: error ? error.message : '',
+        });
+      },
+    );
+  });
+}
+
+function formatCommand(command, args) {
+  return [command, ...args].join(' ');
+}
+
+function redactSecrets(value, secrets) {
+  let text = String(value || '');
+  for (const secret of secrets) {
+    if (!secret) {
+      continue;
+    }
+    text = text.split(secret).join('<redacted>');
+  }
+  return text;
+}
+
+function trimForJson(value) {
+  const text = String(value || '').trim();
+  if (text.length <= 1000) {
+    return text;
+  }
+  return `${text.slice(0, 1000)}...<truncated>`;
+}
+
+function parseJsonObject(value) {
+  try {
+    return { ok: true, value: JSON.parse(value) };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+function summarize(statuses) {
+  const normalized = statuses.filter(Boolean);
+  const status = normalized.reduce(
+    (current, item) => maxStatus(current, item),
+    'OK',
+  );
+  return {
+    status,
+    criticalCount: normalized.filter((item) => item === 'CRITICAL').length,
+    warningCount: normalized.filter((item) => item === 'WARNING').length,
+  };
+}
+
+function maxStatus(left, right) {
+  return STATUS_RANK[right] > STATUS_RANK[left] ? right : left;
+}
diff --git a/scripts/ops/production-health-patrol.mjs b/scripts/ops/production-health-patrol.mjs
index 01a1265c7..60eab89f9 100644
--- a/scripts/ops/production-health-patrol.mjs
+++ b/scripts/ops/production-health-patrol.mjs
@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
-import {execFile} from 'node:child_process';
+import { execFile } from 'node:child_process';
 import http from 'node:http';
 import https from 'node:https';
-import {mkdir, writeFile} from 'node:fs/promises';
-import {dirname} from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
 
 const STATUS_RANK = {
   OK: 0,
@@ -24,7 +24,14 @@ const DEFAULT_SERVICES = [
   'spacetimedb.service',
   'nginx.service',
 ];
+const PINGORA_DIRECT_SERVICES = [
+  'genarrative-api.service',
+  'genarrative-external-generation-controller.service',
+  'spacetimedb.service',
+  'genarrative-pingora-gateway.service',
+];
 const WORKER_SERVICE_PATTERN = 'genarrative-external-generation-worker@*.service';
+const GATEWAY_MODES = new Set(['nginx', 'pingora-direct']);
 
 function usage() {
   console.log(`Usage:
@@ -34,7 +41,11 @@ Options:
   --api-base-url <url>          API direct base URL, default http://127.0.0.1:8082
   --spacetime-base-url <url>    SpacetimeDB base URL, default http://127.0.0.1:3101
   --public-base-url <url>       Nginx/public base URL, default http://127.0.0.1
+  --public-host <host>          Optional public Host header, useful when probing 127.0.0.1
   --public-path <path>          Public API path to probe; repeatable
+  --gateway-mode <mode>         nginx or pingora-direct, default nginx
+  --pingora-base-url <url>      Optional Pingora shadow gateway base URL
+  --pingora-probe-token <token> Optional Pingora shadow probe token
   --status-file <path>          Write the last patrol result as JSON
   --timeout-ms <ms>             HTTP/command timeout, default 5000
   --slow-ms <ms>                Mark successful probes slower than this as WARNING, default 3000
@@ -46,15 +57,32 @@ Options:
 
 function readBoolEnv(name, fallback = false) {
   const value = process.env[name];
-  if (!value) {
+  if (value === undefined || value === null || String(value).trim() === '') {
     return fallback;
   }
-  return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${name} 必须是布尔值 true/false 或 1/0。`);
 }
 
-function parsePositiveInt(raw, fallback) {
-  const value = Number.parseInt(String(raw ?? ''), 10);
-  return Number.isFinite(value) && value > 0 ? value : fallback;
+function parseOptionalPositiveInt(raw, fallback, label) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    return fallback;
+  }
+  return parseRequiredPositiveInt(raw, label);
+}
+
+function parseRequiredPositiveInt(raw, label) {
+  const valueText = String(raw ?? '').trim();
+  if (!/^[1-9]\d*$/.test(valueText)) {
+    throw new Error(`${label} 必须是正整数。`);
+  }
+  return Number.parseInt(valueText, 10);
 }
 
 function parseArgs(argv) {
@@ -67,17 +95,26 @@ function parseArgs(argv) {
       'http://127.0.0.1:3101',
     publicBaseUrl:
       process.env.GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL ||
-      process.env.GENARRATIVE_HEALTH_PATROL_API_BASE_URL ||
-      'http://127.0.0.1:8082',
+      'http://127.0.0.1',
+    publicHost: process.env.GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST || '',
     publicPaths: [],
+    gatewayMode: process.env.GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE || 'nginx',
+    pingoraBaseUrl:
+      process.env.GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL || '',
+    pingoraProbeToken:
+      process.env.GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN ||
+      process.env.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN ||
+      '',
     statusFile: process.env.GENARRATIVE_HEALTH_PATROL_STATUS_FILE || '',
-    timeoutMs: parsePositiveInt(
+    timeoutMs: parseOptionalPositiveInt(
       process.env.GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS,
       5000,
+      'GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS',
     ),
-    slowMs: parsePositiveInt(
+    slowMs: parseOptionalPositiveInt(
       process.env.GENARRATIVE_HEALTH_PATROL_SLOW_MS,
       3000,
+      'GENARRATIVE_HEALTH_PATROL_SLOW_MS',
     ),
     failOnWarning: readBoolEnv('GENARRATIVE_HEALTH_PATROL_FAIL_ON_WARNING'),
     skipJournal: readBoolEnv('GENARRATIVE_HEALTH_PATROL_SKIP_JOURNAL'),
@@ -102,17 +139,35 @@ function parseArgs(argv) {
       case '--public-base-url':
         config.publicBaseUrl = requireValue(argv, ++index, arg);
         break;
+      case '--public-host':
+        config.publicHost = requireValue(argv, ++index, arg);
+        break;
       case '--public-path':
         config.publicPaths.push(requireValue(argv, ++index, arg));
         break;
+      case '--gateway-mode':
+        config.gatewayMode = requireValue(argv, ++index, arg);
+        break;
+      case '--pingora-base-url':
+        config.pingoraBaseUrl = requireValue(argv, ++index, arg);
+        break;
+      case '--pingora-probe-token':
+        config.pingoraProbeToken = requireValue(argv, ++index, arg);
+        break;
       case '--status-file':
         config.statusFile = requireValue(argv, ++index, arg);
         break;
       case '--timeout-ms':
-        config.timeoutMs = parsePositiveInt(requireValue(argv, ++index, arg), 5000);
+        config.timeoutMs = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          '--timeout-ms',
+        );
         break;
       case '--slow-ms':
-        config.slowMs = parsePositiveInt(requireValue(argv, ++index, arg), 3000);
+        config.slowMs = parseRequiredPositiveInt(
+          requireValue(argv, ++index, arg),
+          '--slow-ms',
+        );
         break;
       case '--fail-on-warning':
         config.failOnWarning = true;
@@ -131,6 +186,15 @@ function parseArgs(argv) {
   if (config.publicPaths.length === 0) {
     config.publicPaths = DEFAULT_PUBLIC_PATHS;
   }
+  config.gatewayMode = config.gatewayMode.trim();
+  if (!GATEWAY_MODES.has(config.gatewayMode)) {
+    throw new Error(
+      `--gateway-mode 只支持 nginx 或 pingora-direct: ${config.gatewayMode}`,
+    );
+  }
+  if (config.publicHost) {
+    validateHostOption(config.publicHost, '--public-host');
+  }
 
   return config;
 }
@@ -149,9 +213,22 @@ function joinUrl(baseUrl, path) {
   return `${base}${suffix}`;
 }
 
+function validateHostOption(value, flag) {
+  if (
+    value.includes('://') ||
+    value.includes('/') ||
+    value.includes('?') ||
+    value.includes('#')
+  ) {
+    throw new Error(`${flag} 只接受域名或 host:port，不要填 URL、路径或查询。`);
+  }
+}
+
 function maxStatus(checks) {
   return checks.reduce((current, check) => {
-    return STATUS_RANK[check.status] > STATUS_RANK[current] ? check.status : current;
+    return STATUS_RANK[check.status] > STATUS_RANK[current]
+      ? check.status
+      : current;
   }, 'OK');
 }
 
@@ -177,12 +254,7 @@ function runCommand(command, args, timeoutMs) {
       (error, stdout, stderr) => {
         resolve({
           command: [command, ...args].join(' '),
-          code:
-            typeof error?.code === 'number'
-              ? error.code
-              : error
-                ? 1
-                : 0,
+          code: typeof error?.code === 'number' ? error.code : error ? 1 : 0,
           signal: error?.signal || '',
           stdout: String(stdout || ''),
           stderr: String(stderr || ''),
@@ -273,7 +345,7 @@ async function checkActiveWorkerInstances(config) {
   );
 }
 
-function requestUrl(url, timeoutMs) {
+function requestUrl(url, timeoutMs, headers = {}) {
   return new Promise((resolve) => {
     const startedAt = Date.now();
     const parsed = new URL(url);
@@ -286,6 +358,7 @@ function requestUrl(url, timeoutMs) {
         headers: {
           'User-Agent': 'genarrative-health-patrol/1.0',
           Accept: 'application/json,text/plain,*/*',
+          ...headers,
         },
       },
       (response) => {
@@ -319,9 +392,17 @@ function requestUrl(url, timeoutMs) {
   });
 }
 
-async function checkHttp(name, url, config) {
-  const result = await requestUrl(url, config.timeoutMs);
-  const curlCommand = `curl -fsS --max-time ${Math.ceil(config.timeoutMs / 1000)} ${url}`;
+async function checkHttp(name, url, config, headers = {}) {
+  const result = await requestUrl(url, config.timeoutMs, headers);
+  const headerArgs = Object.entries(headers)
+    .map(
+      ([key, value]) =>
+        ` -H '${key}: ${key.toLowerCase() === 'host' ? value : '***'}'`,
+    )
+    .join('');
+  const curlCommand = `curl -fsS --max-time ${Math.ceil(
+    config.timeoutMs / 1000,
+  )}${headerArgs} ${url}`;
 
   if (result.error) {
     return checkResult(name, 'CRITICAL', `请求失败: ${result.error}`, {
@@ -356,24 +437,125 @@ async function checkHttp(name, url, config) {
     );
   }
 
-  return checkResult(name, 'OK', `HTTP ${result.statusCode} ${result.elapsedMs}ms`, {
-    command: curlCommand,
-    elapsedMs: result.elapsedMs,
+  return checkResult(
+    name,
+    'OK',
+    `HTTP ${result.statusCode} ${result.elapsedMs}ms`,
+    {
+      command: curlCommand,
+      elapsedMs: result.elapsedMs,
+    },
+  );
+}
+
+async function checkPingoraShadow(config) {
+  if (!config.pingoraBaseUrl || !config.pingoraProbeToken) {
+    return checkResult(
+      'pingora:shadow-probe',
+      'WARNING',
+      'Pingora shadow 巡检配置不完整，需同时配置 base URL 与 probe token',
+    );
+  }
+
+  const path = '/__genarrative_pingora/healthz';
+  const url = joinUrl(config.pingoraBaseUrl, path);
+  const result = await requestUrl(url, config.timeoutMs, {
+    'X-Genarrative-Pingora-Probe': config.pingoraProbeToken,
   });
+  const command = `curl -fsS --max-time ${Math.ceil(
+    config.timeoutMs / 1000,
+  )} -H 'X-Genarrative-Pingora-Probe: ***' ${url}`;
+
+  if (result.error) {
+    return checkResult(
+      'pingora:shadow-probe',
+      'CRITICAL',
+      `请求失败: ${result.error}`,
+      {
+        command,
+        elapsedMs: result.elapsedMs,
+      },
+    );
+  }
+
+  if (result.statusCode < 200 || result.statusCode >= 300) {
+    return checkResult(
+      'pingora:shadow-probe',
+      'CRITICAL',
+      `HTTP ${result.statusCode}，耗时 ${result.elapsedMs}ms`,
+      {
+        command,
+        elapsedMs: result.elapsedMs,
+        body: result.body.trim(),
+      },
+    );
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(result.body);
+  } catch {
+    return checkResult(
+      'pingora:shadow-probe',
+      'CRITICAL',
+      `响应不是合法 JSON，耗时 ${result.elapsedMs}ms`,
+      {
+        command,
+        elapsedMs: result.elapsedMs,
+        body: result.body.trim(),
+      },
+    );
+  }
+
+  if (payload?.ok !== true || payload?.gateway !== 'pingora-shadow') {
+    return checkResult(
+      'pingora:shadow-probe',
+      'CRITICAL',
+      `响应不是 Pingora shadow 探针，耗时 ${result.elapsedMs}ms`,
+      {
+        command,
+        elapsedMs: result.elapsedMs,
+        body: result.body.trim(),
+      },
+    );
+  }
+
+  if (result.elapsedMs > config.slowMs) {
+    return checkResult(
+      'pingora:shadow-probe',
+      'WARNING',
+      `HTTP ${result.statusCode} 但耗时偏高: ${result.elapsedMs}ms`,
+      {
+        command,
+        elapsedMs: result.elapsedMs,
+      },
+    );
+  }
+
+  return checkResult(
+    'pingora:shadow-probe',
+    'OK',
+    `HTTP ${result.statusCode} ${result.elapsedMs}ms`,
+    {
+      command,
+      elapsedMs: result.elapsedMs,
+      maintenance: Boolean(payload.maintenance),
+    },
+  );
+}
+
+function gatewayServiceNames(config) {
+  return config.gatewayMode === 'pingora-direct'
+    ? PINGORA_DIRECT_SERVICES
+    : DEFAULT_SERVICES;
 }
 
 async function checkRecentJournal(config) {
+  const serviceNames = [
+    ...new Set([...gatewayServiceNames(config), WORKER_SERVICE_PATTERN]),
+  ];
   const args = [
-    '-u',
-    'genarrative-api.service',
-    '-u',
-    'genarrative-external-generation-controller.service',
-    '-u',
-    WORKER_SERVICE_PATTERN,
-    '-u',
-    'spacetimedb.service',
-    '-u',
-    'nginx.service',
+    ...serviceNames.flatMap((serviceName) => ['-u', serviceName]),
     '--since',
     '15 minutes ago',
     '-p',
@@ -387,10 +569,15 @@ async function checkRecentJournal(config) {
   const result = await runCommand('journalctl', args, config.timeoutMs);
 
   if (result.code !== 0) {
-    return checkResult('journal:recent-errors', 'WARNING', '无法读取最近错误日志', {
-      command: result.command,
-      stderr: result.stderr.trim() || result.error,
-    });
+    return checkResult(
+      'journal:recent-errors',
+      'WARNING',
+      '无法读取最近错误日志',
+      {
+        command: result.command,
+        stderr: result.stderr.trim() || result.error,
+      },
+    );
   }
 
   const lines = result.stdout
@@ -399,9 +586,14 @@ async function checkRecentJournal(config) {
     .filter((line) => line && line !== '-- No entries --');
 
   if (lines.length === 0) {
-    return checkResult('journal:recent-errors', 'OK', '最近 15 分钟无 err..alert 日志', {
-      command: result.command,
-    });
+    return checkResult(
+      'journal:recent-errors',
+      'OK',
+      '最近 15 分钟无 err..alert 日志',
+      {
+        command: result.command,
+      },
+    );
   }
 
   return checkResult(
@@ -419,7 +611,7 @@ async function writeStatusFile(statusFile, payload) {
   if (!statusFile) {
     return;
   }
-  await mkdir(dirname(statusFile), {recursive: true});
+  await mkdir(dirname(statusFile), { recursive: true });
   await writeFile(statusFile, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
 }
 
@@ -484,13 +676,25 @@ async function main() {
   const config = parseArgs(process.argv.slice(2));
   const checks = [];
 
-  for (const serviceName of DEFAULT_SERVICES) {
+  for (const serviceName of gatewayServiceNames(config)) {
     checks.push(await checkService(serviceName, config.timeoutMs));
   }
   checks.push(await checkActiveWorkerInstances(config));
 
-  checks.push(await checkHttp('api:/healthz', joinUrl(config.apiBaseUrl, '/healthz'), config));
-  checks.push(await checkHttp('api:/readyz', joinUrl(config.apiBaseUrl, '/readyz'), config));
+  checks.push(
+    await checkHttp(
+      'api:/healthz',
+      joinUrl(config.apiBaseUrl, '/healthz'),
+      config,
+    ),
+  );
+  checks.push(
+    await checkHttp(
+      'api:/readyz',
+      joinUrl(config.apiBaseUrl, '/readyz'),
+      config,
+    ),
+  );
   checks.push(
     await checkHttp(
       'spacetimedb:/v1/ping',
@@ -500,11 +704,21 @@ async function main() {
   );
 
   for (const path of config.publicPaths) {
+    const headers = config.publicHost ? { Host: config.publicHost } : {};
     checks.push(
-      await checkHttp(`public:${path}`, joinUrl(config.publicBaseUrl, path), config),
+      await checkHttp(
+        `public:${path}`,
+        joinUrl(config.publicBaseUrl, path),
+        config,
+        headers,
+      ),
     );
   }
 
+  if (config.pingoraBaseUrl || config.pingoraProbeToken) {
+    checks.push(await checkPingoraShadow(config));
+  }
+
   if (!config.skipJournal) {
     checks.push(await checkRecentJournal(config));
   }
@@ -513,6 +727,7 @@ async function main() {
     status: maxStatus(checks),
     checkedAt: new Date().toISOString(),
     host: process.env.HOSTNAME || '',
+    gatewayMode: config.gatewayMode,
     checks,
   };
 
@@ -534,6 +749,8 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error(`[health-patrol] CRITICAL ${error instanceof Error ? error.message : String(error)}`);
+  console.error(
+    `[health-patrol] CRITICAL ${error instanceof Error ? error.message : String(error)}`,
+  );
   process.exit(2);
 });
diff --git a/server-rs/Cargo.lock b/server-rs/Cargo.lock
index a9d508fa5..1e719b24d 100644
--- a/server-rs/Cargo.lock
+++ b/server-rs/Cargo.lock
@@ -18,6 +18,15 @@ version = "0.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "366ffbaa4442f4684d91e2cd7c5ea7c4ed8add41959a31447066e279e432b618"
 
+[[package]]
+name = "addr2line"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
+dependencies = [
+ "gimli",
+]
+
 [[package]]
 name = "adler2"
 version = "2.0.1"
@@ -66,6 +75,12 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "aliasable"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "250f629c0161ad8107cf89319e990051fae62832fd343083bea452d93e2205fd"
+
 [[package]]
 name = "alloc-no-stdlib"
 version = "2.0.4"
@@ -74,13 +89,19 @@ checksum = "cc7bb162ec39d46ab1ca8c77bf72e890535becd1751bb45f64c597edb4c8c6b3"
 
 [[package]]
 name = "alloc-stdlib"
-version = "0.2.2"
+version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "94fb8275041c72129eb51b7d0322c29b8387a0386127718b096429201a5d6ece"
+checksum = "0e76a019e91224d279006ff972f1e984179a6e9feb050adba6ce8274aef23195"
 dependencies = [
  "alloc-no-stdlib",
 ]
 
+[[package]]
+name = "allocator-api2"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
+
 [[package]]
 name = "android-activity"
 version = "0.6.1"
@@ -88,7 +109,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0f2a1bb052857d5dd49572219344a7332b31b76405648eabac5bc68978251bcd"
 dependencies = [
  "android-properties",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "cc",
  "jni",
  "libc",
@@ -115,6 +136,56 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "anyhow"
 version = "1.0.102"
@@ -123,9 +194,9 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
 [[package]]
 name = "anymap3"
-version = "1.0.1"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "170433209e817da6aae2c51aa0dd443009a613425dd041ebfb2492d1c4c11a25"
+checksum = "fb5dfbc6d8d2675589ccbe4d0fd61df2419075625f8c1a62325e718e2b0049f9"
 
 [[package]]
 name = "api-server"
@@ -181,7 +252,7 @@ dependencies = [
  "shared-contracts",
  "shared-kernel",
  "shared-logging",
- "socket2 0.6.3",
+ "socket2 0.6.4",
  "spacetime-client",
  "time",
  "tokio",
@@ -231,10 +302,19 @@ dependencies = [
  "objc2-foundation 0.3.2",
  "parking_lot",
  "percent-encoding",
- "windows-sys 0.59.0",
+ "windows-sys 0.60.2",
  "x11rb",
 ]
 
+[[package]]
+name = "arc-swap"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a3a1fd6f75306b68087b831f025c712524bcb19aad54e557b1129cfa0a2b207"
+dependencies = [
+ "rustversion",
+]
+
 [[package]]
 name = "argon2"
 version = "0.5.3"
@@ -265,6 +345,45 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "175571dd1d178ced59193a6fc02dde1b972eb0bc56c892cde9beeceac5bf0f6b"
 
+[[package]]
+name = "asn1-rs"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5493c3bedbacf7fd7382c6346bbd66687d12bbaad3a89a2d2c303ee6cf20b048"
+dependencies = [
+ "asn1-rs-derive",
+ "asn1-rs-impl",
+ "displaydoc",
+ "nom",
+ "num-traits",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
+[[package]]
+name = "asn1-rs-derive"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "965c2d33e53cb6b267e148a4cb0760bc01f4904c1cd4bb4002a085bb016d1490"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+ "synstructure",
+]
+
+[[package]]
+name = "asn1-rs-impl"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b18050c2cd6fe86c3a76584ef5e0baf286d038cda203eb6223df2cc413565f7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
 [[package]]
 name = "async-stream"
 version = "0.3.6"
@@ -284,7 +403,7 @@ checksum = "c7c24de15d275a1ecfd47a380fb4d5ec9bfe0933f309ed5e705b775596a3574d"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -295,7 +414,7 @@ checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -306,9 +425,31 @@ checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
 [[package]]
 name = "autocfg"
-version = "1.5.0"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "aws-lc-rs"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ec2f1fc3ec205783a5da9a7e6c1509cc69dedf09a1949e412c1e18469326d00"
+dependencies = [
+ "aws-lc-sys",
+ "zeroize",
+]
+
+[[package]]
+name = "aws-lc-sys"
+version = "0.41.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a2f9779ce85b93ab6170dd940ad0169b5766ff848247aff13bb788b832fe3f4"
+dependencies = [
+ "cc",
+ "cmake",
+ "dunce",
+ "fs_extra",
+]
 
 [[package]]
 name = "axum"
@@ -321,10 +462,10 @@ dependencies = [
  "bytes",
  "form_urlencoded",
  "futures-util",
- "http 1.4.0",
+ "http 1.4.2",
  "http-body 1.0.1",
  "http-body-util",
- "hyper 1.9.0",
+ "hyper 1.10.1",
  "hyper-util",
  "itoa",
  "matchit",
@@ -354,7 +495,7 @@ checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1"
 dependencies = [
  "bytes",
  "futures-core",
- "http 1.4.0",
+ "http 1.4.2",
  "http-body 1.0.1",
  "http-body-util",
  "mime",
@@ -365,6 +506,21 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "backtrace"
+version = "0.3.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6"
+dependencies = [
+ "addr2line",
+ "cfg-if",
+ "libc",
+ "miniz_oxide",
+ "object",
+ "rustc-demangle",
+ "windows-link",
+]
+
 [[package]]
 name = "base64"
 version = "0.21.7"
@@ -415,9 +571,9 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
 
 [[package]]
 name = "bitflags"
-version = "2.11.1"
+version = "2.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
 [[package]]
 name = "blake2"
@@ -430,9 +586,9 @@ dependencies = [
 
 [[package]]
 name = "blake3"
-version = "1.8.4"
+version = "1.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4d2d5991425dfd0785aed03aedcf0b321d61975c9b5b3689c774a2610ae0b51e"
+checksum = "0aa83c34e62843d924f905e0f5c866eb1dd6545fc4d719e803d9ba6030371fce"
 dependencies = [
  "arrayref",
  "arrayvec",
@@ -491,10 +647,30 @@ dependencies = [
 ]
 
 [[package]]
-name = "bumpalo"
-version = "3.20.2"
+name = "bs58"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
+checksum = "bf88ba1141d185c399bee5288d850d63b8369520c1eafc32a0430b5b6c287bf4"
+dependencies = [
+ "tinyvec",
+]
+
+[[package]]
+name = "bstr"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63044e1ae8e69f3b5a92c736ca6269b8d12fa7efe39bf34ddb06d102cf0e2cab"
+dependencies = [
+ "memchr",
+ "regex-automata",
+ "serde",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "bytemuck"
@@ -513,9 +689,15 @@ checksum = "f9abbd1bc6865053c427f7198e6af43bfdedc55ab791faed4fbd361d789575ff"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
+[[package]]
+name = "byteorder"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
+
 [[package]]
 name = "byteorder-lite"
 version = "0.1.0"
@@ -530,9 +712,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "bytestring"
-version = "1.5.0"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "113b4343b5f6617e7ad401ced8de3cc8b012e73a594347c307b90db3e9271289"
+checksum = "86566c496f2f47d9b8147a4c8b02ffdb69c919fe0c2b2e7195d22cbba0e635c9"
 dependencies = [
  "bytes",
  "serde_core",
@@ -544,7 +726,7 @@ version = "0.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b99da2f8558ca23c71f4fd15dc57c906239752dd27ff3c00a1d56b685b7cbfec"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "log",
  "polling",
  "rustix 0.38.44",
@@ -558,7 +740,7 @@ version = "0.14.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4dbf9978365bac10f54d1d4b04f7ce4427e51f71d61f2fe15e3fed5166474df7"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "polling",
  "rustix 1.1.4",
  "slab",
@@ -609,9 +791,9 @@ dependencies = [
 
 [[package]]
 name = "cc"
-version = "1.2.60"
+version = "1.2.64"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
+checksum = "dad887fd958be91b5098c0248def011f4523ab786cd411be668777e55063501f"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -619,6 +801,34 @@ dependencies = [
  "shlex",
 ]
 
+[[package]]
+name = "cf-rustracing"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93f85c3824e4191621dec0551e3cef3d511f329da9a8990bf3e450a85651d97e"
+dependencies = [
+ "backtrace",
+ "rand 0.8.6",
+ "tokio",
+ "trackable",
+]
+
+[[package]]
+name = "cf-rustracing-jaeger"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6a5f80d44c257c3300a7f45ada676c211e64bbbac591bbec19344a8f61fbcab"
+dependencies = [
+ "cf-rustracing",
+ "hostname",
+ "local-ip-address",
+ "percent-encoding",
+ "rand 0.9.4",
+ "thrift_codec",
+ "tokio",
+ "trackable",
+]
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
@@ -642,9 +852,9 @@ dependencies = [
 
 [[package]]
 name = "chrono"
-version = "0.4.44"
+version = "0.4.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c673075a2e0e5f4a1dde27ce9dee1ea4558c7ffe648f576438a20ca1d2acc4b0"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
 dependencies = [
  "iana-time-zone",
  "js-sys",
@@ -664,6 +874,46 @@ dependencies = [
  "inout",
 ]
 
+[[package]]
+name = "clap"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
 [[package]]
 name = "clipboard-win"
 version = "5.4.1"
@@ -673,6 +923,15 @@ dependencies = [
  "error-code",
 ]
 
+[[package]]
+name = "cmake"
+version = "0.1.58"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0f78a02292a74a88ac736019ab962ece0bc380e3f977bf72e376c5d78ff0678"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "codespan-reporting"
 version = "0.12.0"
@@ -682,6 +941,12 @@ dependencies = [
  "unicode-width",
 ]
 
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
 [[package]]
 name = "combine"
 version = "4.6.7"
@@ -883,24 +1148,24 @@ dependencies = [
 
 [[package]]
 name = "curl"
-version = "0.4.49"
+version = "0.4.50"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "79fc3b6dd0b87ba36e565715bf9a2ced221311db47bd18011676f24a6066edbc"
+checksum = "3a45ee8994e5307cb4c60cfc1c20bf7263ffb771ddc135c9f768a14bcbc15b09"
 dependencies = [
  "curl-sys",
  "libc",
  "openssl-probe",
  "openssl-sys",
  "schannel",
- "socket2 0.6.3",
- "windows-sys 0.59.0",
+ "socket2 0.6.4",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "curl-sys"
-version = "0.4.88+curl-8.20.0"
+version = "0.4.89+curl-8.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "644816de6547255eff4e491a1dda1c19b7237f00b62a61e6e64859ce4f2906d0"
+checksum = "6d680779285438f2d0927485973ab45b212ea990bddb80de8a55a1e3c1d9ba22"
 dependencies = [
  "cc",
  "libc",
@@ -917,14 +1182,56 @@ version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f27ae1dd37df86211c42e150270f82743308803d90a6f6e6651cd730d5e1732f"
 
+[[package]]
+name = "daemonize"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab8bfdaacb3c887a54d41bdf48d3af8873b3f5566469f8ba21b92057509f116e"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "daggy"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70def8d72740e44d9f676d8dab2c933a236663d86dd24319b57a2bed4d694774"
+dependencies = [
+ "petgraph 0.7.1",
+]
+
+[[package]]
+name = "darling"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc7f46116c46ff9ab3eb1597a45688b6715c6e628b5c133e288e709a29bcb4ee"
+dependencies = [
+ "darling_core 0.20.11",
+ "darling_macro 0.20.11",
+]
+
 [[package]]
 name = "darling"
 version = "0.23.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "25ae13da2f202d56bd7f91c25fba009e7717a1e4a1cc98a76d844b65ae912e9d"
 dependencies = [
- "darling_core",
- "darling_macro",
+ "darling_core 0.23.0",
+ "darling_macro 0.23.0",
+]
+
+[[package]]
+name = "darling_core"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d00b9596d185e565c2207a0b01f8bd1a135483d02d9b7b0a54b11da8d53412e"
+dependencies = [
+ "fnv",
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -937,7 +1244,18 @@ dependencies = [
  "proc-macro2",
  "quote",
  "strsim",
- "syn",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc34b93ccb385b40dc71c6fceac4b2ad23662c7eeb248cf10d529b7e055b6ead"
+dependencies = [
+ "darling_core 0.20.11",
+ "quote",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -946,16 +1264,16 @@ version = "0.23.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d"
 dependencies = [
- "darling_core",
+ "darling_core 0.23.0",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
 name = "data-encoding"
-version = "2.10.0"
+version = "2.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d7a1e2f27636f116493b8b860f5546edb47c8d8f8ea73e1d2a20be88e28d1fea"
+checksum = "a4ae5f15dda3c708c0ade84bfee31ccab44a3da4f88015ed22f63732abe300c8"
 
 [[package]]
 name = "decorum"
@@ -967,16 +1285,40 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "der-parser"
+version = "9.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cd0a5c643689626bec213c4d8bd4d96acc8ffdb4ad4bb6bc16abf27d5f4b553"
+dependencies = [
+ "asn1-rs",
+ "displaydoc",
+ "nom",
+ "num-bigint",
+ "num-traits",
+ "rusticata-macros",
+]
+
 [[package]]
 name = "deranged"
 version = "0.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 dependencies = [
- "powerfmt",
  "serde_core",
 ]
 
+[[package]]
+name = "derivative"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcc3dd5e9e9c0b295d6e1e4d811fb6f157d5ffd784b8d202fc62eac8035a770b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "derive_arbitrary"
 version = "1.4.2"
@@ -985,7 +1327,38 @@ checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "derive_builder"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "507dfb09ea8b7fa618fcf76e953f4f5e192547945816d5358edffe39f6f94947"
+dependencies = [
+ "derive_builder_macro",
+]
+
+[[package]]
+name = "derive_builder_core"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d5bcf7b024d6835cfb3d473887cd966994907effbe9227e8c8219824d06c4e8"
+dependencies = [
+ "darling 0.20.11",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "derive_builder_macro"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab63b0e2bf4d5928aff72e83a7dace85d7bba5fe12dcc3c5a572d78caffd3f3c"
+dependencies = [
+ "derive_builder_core",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -998,7 +1371,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "rustc_version",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1024,19 +1397,19 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "objc2 0.6.4",
 ]
 
 [[package]]
 name = "displaydoc"
-version = "0.2.5"
+version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97369cbbc041bc366949bc74d34658d6cda5621039731c6310521892a3a20ae0"
+checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1075,6 +1448,12 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d8b14ccef22fc6f5a8f4d7d768562a182c04ce9a3b3157b91390b52ddfdf1a76"
 
+[[package]]
+name = "dunce"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
+
 [[package]]
 name = "dyn-clone"
 version = "1.0.20"
@@ -1133,7 +1512,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6a9b567d356674e9a5121ed3fedfb0a7c31e059fe71f6972b691bcd0bfc284e3"
 dependencies = [
  "ahash",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "emath",
  "epaint",
  "log",
@@ -1194,7 +1573,7 @@ dependencies = [
  "egui",
  "glow",
  "log",
- "memoffset",
+ "memoffset 0.9.1",
  "profiling",
  "wasm-bindgen",
  "web-sys",
@@ -1203,9 +1582,9 @@ dependencies = [
 
 [[package]]
 name = "either"
-version = "1.15.0"
+version = "1.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
 
 [[package]]
 name = "emath"
@@ -1240,7 +1619,7 @@ dependencies = [
  "heck 0.5.0",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1260,7 +1639,7 @@ checksum = "f282cfdfe92516eb26c2af8589c274c7c17681f5ecc03c18255fe741c6aa64eb"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1360,6 +1739,12 @@ version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ce7134b9999ecaf8bcd65542e436736ef32ddca1b3e06094cb6ec5755203b80"
 
+[[package]]
+name = "fixedbitset"
+version = "0.5.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d674e81391d1e1ab681a28d99df07927c6d4aa5b027d7da16ba32d1d21ecd99"
+
 [[package]]
 name = "flate2"
 version = "1.1.9"
@@ -1367,6 +1752,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
 dependencies = [
  "crc32fast",
+ "libz-ng-sys",
  "miniz_oxide",
 ]
 
@@ -1415,7 +1801,7 @@ checksum = "1a5c6c585bc94aaf2c7b51dd4c2ba22680844aba4c687be581871a6f518c5742"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1439,6 +1825,12 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "fs_extra"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
+
 [[package]]
 name = "futures"
 version = "0.3.32"
@@ -1495,7 +1887,7 @@ checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -1587,6 +1979,23 @@ dependencies = [
  "wasip3",
 ]
 
+[[package]]
+name = "getset"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cf442baaabe4213ce7d1239afc26c039180b6456da2cededa316ae2c8a77a77"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "gimli"
+version = "0.32.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"
+
 [[package]]
 name = "gl_generator"
 version = "0.14.0"
@@ -1622,7 +2031,7 @@ version = "0.32.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "12124de845cacfebedff80e877bb37b5b75c34c5a4c89e47e1cdd67fb6041325"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "cfg_aliases",
  "cgl",
  "dispatch2",
@@ -1701,6 +2110,25 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "h2"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cb093c84e8bd9b188d4c4a8cb6579fc016968d14c99882163cd3ff402a4f155"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http 1.4.2",
+ "indexmap 2.14.0",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
 [[package]]
 name = "half"
 version = "2.7.1"
@@ -1734,6 +2162,7 @@ version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
 dependencies = [
+ "allocator-api2",
  "equivalent",
  "foldhash 0.2.0",
  "rayon",
@@ -1743,9 +2172,14 @@ dependencies = [
 
 [[package]]
 name = "hashbrown"
-version = "0.17.0"
+version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+dependencies = [
+ "allocator-api2",
+ "equivalent",
+ "foldhash 0.2.0",
+]
 
 [[package]]
 name = "heck"
@@ -1795,6 +2229,17 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "hostname"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "617aaa3557aef3810a6369d0a99fac8a080891b68bd9f9812a1eeda0c0730cbd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "windows-link",
+]
+
 [[package]]
 name = "http"
 version = "0.2.12"
@@ -1808,9 +2253,9 @@ dependencies = [
 
 [[package]]
 name = "http"
-version = "1.4.0"
+version = "1.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3ba2a386d7f85a81f119ad7498ebe444d2e22c2af0b86b069416ace48b3311a"
+checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
 dependencies = [
  "bytes",
  "itoa",
@@ -1834,7 +2279,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
 dependencies = [
  "bytes",
- "http 1.4.0",
+ "http 1.4.2",
 ]
 
 [[package]]
@@ -1845,7 +2290,7 @@ checksum = "b021d93e26becf5dc7e1b75b1bed1fd93124b374ceb73f43d4d4eafec896a64a"
 dependencies = [
  "bytes",
  "futures-core",
- "http 1.4.0",
+ "http 1.4.2",
  "http-body 1.0.1",
  "pin-project-lite",
 ]
@@ -1878,7 +2323,7 @@ dependencies = [
  "futures-channel",
  "futures-core",
  "futures-util",
- "h2",
+ "h2 0.3.27",
  "http 0.2.12",
  "http-body 0.4.6",
  "httparse",
@@ -1894,15 +2339,15 @@ dependencies = [
 
 [[package]]
 name = "hyper"
-version = "1.9.0"
+version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6299f016b246a94207e63da54dbe807655bf9e00044f73ded42c3ac5305fbcca"
+checksum = "55281c53a1894c864990125767da440a4e630446785086f52523b20033b74498"
 dependencies = [
  "atomic-waker",
  "bytes",
  "futures-channel",
  "futures-core",
- "http 1.4.0",
+ "http 1.4.2",
  "http-body 1.0.1",
  "httparse",
  "httpdate",
@@ -1919,14 +2364,14 @@ version = "0.27.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
 dependencies = [
- "http 1.4.0",
- "hyper 1.9.0",
+ "http 1.4.2",
+ "hyper 1.10.1",
  "hyper-util",
  "rustls",
  "tokio",
  "tokio-rustls",
  "tower-service",
- "webpki-roots 1.0.7",
+ "webpki-roots 1.0.8",
 ]
 
 [[package]]
@@ -1952,14 +2397,14 @@ dependencies = [
  "bytes",
  "futures-channel",
  "futures-util",
- "http 1.4.0",
+ "http 1.4.2",
  "http-body 1.0.1",
- "hyper 1.9.0",
+ "hyper 1.10.1",
  "ipnet",
  "libc",
  "percent-encoding",
  "pin-project-lite",
- "socket2 0.6.3",
+ "socket2 0.6.4",
  "tokio",
  "tower-service",
  "tracing",
@@ -2096,9 +2541,9 @@ dependencies = [
 
 [[package]]
 name = "idna_adapter"
-version = "1.2.1"
+version = "1.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3acae9609540aa318d1bc588455225fb2085b9ed0c4f6bd0d9d5bcd86f1a0344"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
 dependencies = [
  "icu_normalizer",
  "icu_properties",
@@ -2149,7 +2594,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.17.0",
+ "hashbrown 0.17.1",
  "serde",
  "serde_core",
 ]
@@ -2166,15 +2611,16 @@ dependencies = [
 
 [[package]]
 name = "insta"
-version = "1.47.2"
+version = "1.48.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b4a6248eb93a4401ed2f37dfe8ea592d3cf05b7cf4f8efa867b6895af7e094e"
+checksum = "86f0f8fee8c926415c58d6ae43a08523a26faccb2323f5e6b644fe7dd4ef6b82"
 dependencies = [
  "console",
  "once_cell",
  "regex",
  "serde",
  "similar",
+ "strip-ansi-escapes",
  "tempfile",
  "toml_edit",
  "toml_writer",
@@ -2187,14 +2633,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
 [[package]]
-name = "iri-string"
-version = "0.7.12"
+name = "is_terminal_polyfill"
+version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "25e659a4bb38e810ebc252e53b5814ff908a8c58c2a9ce2fae1bbec24cbf4e20"
-dependencies = [
- "memchr",
- "serde",
-]
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 
 [[package]]
 name = "itertools"
@@ -2205,6 +2647,15 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
@@ -2238,7 +2689,7 @@ dependencies = [
  "quote",
  "rustc_version",
  "simd_cesu8",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -2266,7 +2717,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264"
 dependencies = [
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -2281,13 +2732,12 @@ dependencies = [
 
 [[package]]
 name = "js-sys"
-version = "0.3.95"
+version = "0.3.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2964e92d1d9dc3364cae4d718d93f227e3abb088e747d92e0395bfdedf1c12ca"
+checksum = "03d04c30968dffe80775bd4d7fb676131cd04a1fb46d2686dbffbaec2d9dfd31"
 dependencies = [
  "cfg-if",
  "futures-util",
- "once_cell",
  "wasm-bindgen",
 ]
 
@@ -2323,9 +2773,9 @@ checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc"
 
 [[package]]
 name = "langchainrust"
-version = "0.2.18"
+version = "0.2.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e783bd3734eb269382df16f3018d3b5e31827c6f8a2bdf7d4bf3ddb7b9bb6039"
+checksum = "ac5ddb421c9c0311ee154af906747ba1fb5c3db83d7d71dcb38f40b557eb28e4"
 dependencies = [
  "async-trait",
  "bincode",
@@ -2368,9 +2818,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.185"
+version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "libloading"
@@ -2394,7 +2844,7 @@ version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f02ab6bace2054fb888a3c16f990117b579d14a3088e472d63c6011fa185c9d3"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "libc",
  "plain",
  "redox_syscall 0.8.1",
@@ -2410,6 +2860,16 @@ dependencies = [
  "glob",
 ]
 
+[[package]]
+name = "libz-ng-sys"
+version = "1.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "879917b256f6317769b9f374b435805a8697013098aacce5a38ac106cd6a9469"
+dependencies = [
+ "cmake",
+ "libc",
+]
+
 [[package]]
 name = "libz-sys"
 version = "1.1.29"
@@ -2446,6 +2906,17 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
 
+[[package]]
+name = "local-ip-address"
+version = "0.6.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa08fb2b1ec3ea84575e94b489d06d4ce0cbf052d12acd515838f50e3c3d63e3"
+dependencies = [
+ "libc",
+ "neli",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "lock_api"
 version = "0.4.14"
@@ -2457,9 +2928,9 @@ dependencies = [
 
 [[package]]
 name = "log"
-version = "0.4.29"
+version = "0.4.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+checksum = "953f07c43838f8e6f9758cab68bf5bed85465e7587ebe0b823f1bcd81978ad3a"
 
 [[package]]
 name = "lopdf"
@@ -2479,6 +2950,15 @@ dependencies = [
  "weezl",
 ]
 
+[[package]]
+name = "lru"
+version = "0.16.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f66e8d5d03f609abc3a39e6f08e4164ebf1447a732906d39eb9b99b7919ef39"
+dependencies = [
+ "hashbrown 0.16.1",
+]
+
 [[package]]
 name = "lru-slab"
 version = "0.1.2"
@@ -2512,9 +2992,9 @@ dependencies = [
 
 [[package]]
 name = "memchr"
-version = "2.8.0"
+version = "2.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
 
 [[package]]
 name = "memmap2"
@@ -2525,6 +3005,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "memoffset"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5aa361d4faea93603064a027415f07bd8e1d5c88c9fbf68bf56a285428fd79ce"
+dependencies = [
+ "autocfg",
+]
+
 [[package]]
 name = "memoffset"
 version = "0.9.1"
@@ -2568,9 +3057,9 @@ dependencies = [
 
 [[package]]
 name = "mio"
-version = "1.2.0"
+version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1"
+checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
 dependencies = [
  "libc",
  "wasi",
@@ -2822,7 +3311,7 @@ checksum = "066cf25f0e8b11ee0df221219010f213ad429855f57c494f995590c861a9a7d8"
 dependencies = [
  "arrayvec",
  "bit-set",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "cfg-if",
  "cfg_aliases",
  "codespan-reporting",
@@ -2862,7 +3351,7 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "jni-sys 0.3.1",
  "log",
  "ndk-sys",
@@ -2886,6 +3375,53 @@ dependencies = [
  "jni-sys 0.3.1",
 ]
 
+[[package]]
+name = "neli"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22f9786d56d972959e1408b6a93be6af13b9c1392036c5c1fafa08a1b0c6ee87"
+dependencies = [
+ "bitflags 2.13.0",
+ "byteorder",
+ "derive_builder",
+ "getset",
+ "libc",
+ "log",
+ "neli-proc-macros",
+ "parking_lot",
+]
+
+[[package]]
+name = "neli-proc-macros"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05d8d08c6e98f20a62417478ebf7be8e1425ec9acecc6f63e22da633f6b71609"
+dependencies = [
+ "either",
+ "proc-macro2",
+ "quote",
+ "serde",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "nix"
+version = "0.24.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa52e972a9a719cecb6864fb88568781eb706bac2cd1d4f04a648542dbf78069"
+dependencies = [
+ "bitflags 1.3.2",
+ "cfg-if",
+ "libc",
+ "memoffset 0.6.5",
+]
+
+[[package]]
+name = "no_debug"
+version = "3.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f23a60c850e1144fc1dd9435152e0cfdc7dd18725350b4243584118013a52a4"
+
 [[package]]
 name = "nohash-hasher"
 version = "0.2.0"
@@ -2923,9 +3459,9 @@ dependencies = [
 
 [[package]]
 name = "num-conv"
-version = "0.2.1"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c6673768db2d862beb9b39a78fdcb1a69439615d5794a1be50caa9bc92c81967"
+checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 
 [[package]]
 name = "num-integer"
@@ -2965,7 +3501,7 @@ dependencies = [
  "proc-macro-crate",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -2999,7 +3535,7 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e4e89ad9e3d7d297152b17d39ed92cd50ca8063a89a9fa569046d41568891eff"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "libc",
  "objc2 0.5.2",
@@ -3015,7 +3551,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "objc2 0.6.4",
  "objc2-core-foundation",
  "objc2-core-graphics",
@@ -3028,7 +3564,7 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "74dd3b56391c7a0596a295029734d3c1c5e7e510a4cb30245f8221ccea96b009"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "objc2 0.5.2",
  "objc2-core-location",
@@ -3052,7 +3588,7 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "617fbf49e071c178c0b24c080767db52958f716d9eabdf0890523aeae54773ef"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "objc2 0.5.2",
  "objc2-foundation 0.2.2",
@@ -3064,7 +3600,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "dispatch2",
  "objc2 0.6.4",
 ]
@@ -3075,7 +3611,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "dispatch2",
  "objc2 0.6.4",
  "objc2-core-foundation",
@@ -3118,7 +3654,7 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ee638a5da3799329310ad4cfa62fbf045d5f56e3ef5ba4149e7452dcf89d5a8"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "dispatch",
  "libc",
@@ -3131,7 +3667,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "objc2 0.6.4",
  "objc2-core-foundation",
 ]
@@ -3142,7 +3678,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "objc2 0.6.4",
  "objc2-core-foundation",
 ]
@@ -3165,7 +3701,7 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dd0cba1276f6023976a406a14ffa85e1fdd19df6b0f737b063b95f6c8c7aadd6"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "objc2 0.5.2",
  "objc2-foundation 0.2.2",
@@ -3177,7 +3713,7 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e42bee7bff906b14b167da2bac5efe6b6a07e6f7c0a21a7308d40c960242dc7a"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "objc2 0.5.2",
  "objc2-foundation 0.2.2",
@@ -3200,7 +3736,7 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8bb46798b20cd6b91cbd113524c490f1686f4c4e8f49502431415f3512e2b6f"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "objc2 0.5.2",
  "objc2-cloud-kit",
@@ -3232,13 +3768,31 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "76cfcbf642358e8689af64cee815d139339f3ed8ad05103ed5eaf73db8d84cb3"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "objc2 0.5.2",
  "objc2-core-location",
  "objc2-foundation 0.2.2",
 ]
 
+[[package]]
+name = "object"
+version = "0.37.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "oid-registry"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a8d8034d9489cdaf79228eb9f6a3b8d7bb32ba00d6645ebd48eef4077ceb5bd9"
+dependencies = [
+ "asn1-rs",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -3246,16 +3800,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
-name = "openssl"
-version = "0.10.78"
+name = "once_cell_polyfill"
+version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f38c4372413cdaaf3cc79dd92d29d7d9f5ab09b51b10dded508fb90bb70b9222"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "openssl"
+version = "0.10.81"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77823a27f0babb03091cb9ed9ef80af3b39dbc82f97e8fa530374b7dafd87a45"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "cfg-if",
  "foreign-types 0.3.2",
  "libc",
- "once_cell",
  "openssl-macros",
  "openssl-sys",
 ]
@@ -3268,7 +3827,7 @@ checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -3279,9 +3838,9 @@ checksum = "d05e27ee213611ffe7d6348b942e8f942b37114c00cc03cec254295a4a17852e"
 
 [[package]]
 name = "openssl-sys"
-version = "0.9.114"
+version = "0.9.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "13ce1245cd07fcc4cfdb438f7507b0c7e4f3849a69fd84d52374c66d83741bb6"
+checksum = "b47e7e6bb2c38cd930d25a23b40fa52e068c10e85f3e03a7f5ba5aaca5713695"
 dependencies = [
  "cc",
  "libc",
@@ -3324,7 +3883,7 @@ checksum = "d7a6d09a73194e6b66df7c8f1b680f156d916a1a942abf2de06823dd02b7855d"
 dependencies = [
  "async-trait",
  "bytes",
- "http 1.4.0",
+ "http 1.4.2",
  "opentelemetry",
  "reqwest 0.12.28",
 ]
@@ -3335,7 +3894,7 @@ version = "0.31.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1f69cd6acbb9af919df949cd1ec9e5e7fdc2ef15d234b6b795aaa525cc02f71f"
 dependencies = [
- "http 1.4.0",
+ "http 1.4.2",
  "opentelemetry",
  "opentelemetry-http",
  "opentelemetry-proto",
@@ -3383,6 +3942,30 @@ dependencies = [
  "libredox",
 ]
 
+[[package]]
+name = "ouroboros"
+version = "0.18.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0f050db9c44b97a94723127e6be766ac5c340c48f2c4bb3ffa11713744be59"
+dependencies = [
+ "aliasable",
+ "ouroboros_macro",
+ "static_assertions",
+]
+
+[[package]]
+name = "ouroboros_macro"
+version = "0.18.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c7028bdd3d43083f6d8d4d5187680d0d3560d54df4cc9d752005268b41e64d0"
+dependencies = [
+ "heck 0.4.1",
+ "proc-macro2",
+ "proc-macro2-diagnostics",
+ "quote",
+ "syn 2.0.118",
+]
+
 [[package]]
 name = "owned_ttf_parser"
 version = "0.25.1"
@@ -3469,7 +4052,17 @@ version = "0.6.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4c5cc86750666a3ed20bdaf5ca2a0344f9c67674cae0515bec2da16fbaa47db"
 dependencies = [
- "fixedbitset",
+ "fixedbitset 0.4.2",
+ "indexmap 2.14.0",
+]
+
+[[package]]
+name = "petgraph"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3672b37090dbd86368a4145bc067582552b29c27377cad4e0a306c97f9bd7772"
+dependencies = [
+ "fixedbitset 0.5.7",
  "indexmap 2.14.0",
 ]
 
@@ -3490,7 +4083,7 @@ checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -3499,6 +4092,286 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
+[[package]]
+name = "pingora"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54a75f2ff8e122aa80ab202dc865294fe59cd856c2a5dab2d3df6e122c93b941"
+dependencies = [
+ "pingora-cache",
+ "pingora-core",
+ "pingora-http",
+ "pingora-load-balancing",
+ "pingora-proxy",
+ "pingora-timeout",
+]
+
+[[package]]
+name = "pingora-cache"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "527735ac204efb9fa3884bfd9224d016c5735fabe1d394ebed145b40e7545b99"
+dependencies = [
+ "ahash",
+ "async-trait",
+ "blake2",
+ "bstr",
+ "bytes",
+ "cf-rustracing",
+ "cf-rustracing-jaeger",
+ "hex",
+ "http 1.4.2",
+ "httparse",
+ "httpdate",
+ "indexmap 1.9.3",
+ "log",
+ "lru",
+ "once_cell",
+ "parking_lot",
+ "pingora-core",
+ "pingora-error",
+ "pingora-header-serde",
+ "pingora-http",
+ "pingora-lru",
+ "pingora-timeout",
+ "rand 0.8.6",
+ "regex",
+ "rmp",
+ "rmp-serde",
+ "serde",
+ "strum 0.26.3",
+ "tokio",
+]
+
+[[package]]
+name = "pingora-core"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a7ffe2f5acf9f94fd255cfd1438866bc9124f8f0c7d42562bd3f853df2094b7"
+dependencies = [
+ "ahash",
+ "async-trait",
+ "brotli",
+ "bstr",
+ "bytes",
+ "chrono",
+ "clap",
+ "daemonize",
+ "daggy",
+ "derivative",
+ "flate2",
+ "futures",
+ "h2 0.4.15",
+ "http 1.4.2",
+ "httparse",
+ "httpdate",
+ "libc",
+ "log",
+ "nix",
+ "once_cell",
+ "openssl-probe",
+ "ouroboros",
+ "parking_lot",
+ "percent-encoding",
+ "pingora-error",
+ "pingora-http",
+ "pingora-pool",
+ "pingora-runtime",
+ "pingora-rustls",
+ "pingora-timeout",
+ "prometheus 0.13.4",
+ "rand 0.8.6",
+ "regex",
+ "serde",
+ "serde_yaml",
+ "sfv",
+ "socket2 0.6.4",
+ "strum 0.26.3",
+ "strum_macros 0.26.4",
+ "tokio",
+ "tokio-stream",
+ "tokio-test",
+ "unicase",
+ "windows-sys 0.59.0",
+ "x509-parser",
+ "zstd",
+]
+
+[[package]]
+name = "pingora-error"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b23f7bc013de67e44ed902a82843f6157460b89d11da882bcc6f09f8ae380af1"
+
+[[package]]
+name = "pingora-gateway"
+version = "0.1.0"
+dependencies = [
+ "async-trait",
+ "bytes",
+ "httpdate",
+ "mime_guess",
+ "pingora",
+ "pingora-http",
+ "pingora-proxy",
+ "serde",
+ "serde_json",
+ "shared-logging",
+ "tokio",
+ "tracing",
+ "uuid",
+]
+
+[[package]]
+name = "pingora-header-serde"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "828c0e53e74160cbfe8e67dd3a811eb6a253c36acbaf7a39a01d9aacfb9ac139"
+dependencies = [
+ "bytes",
+ "http 1.4.2",
+ "httparse",
+ "pingora-error",
+ "pingora-http",
+ "thread_local",
+ "zstd",
+ "zstd-safe",
+]
+
+[[package]]
+name = "pingora-http"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d553d310a15ec88107b9388a02885f798efc57764d8e9bdaaf32a76722927a10"
+dependencies = [
+ "bytes",
+ "http 1.4.2",
+ "pingora-error",
+]
+
+[[package]]
+name = "pingora-ketama"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e2a2e43a14f1d291fba7905542c7c1d1f89528f470b3cd48b6806e702ea772f"
+dependencies = [
+ "crc32fast",
+]
+
+[[package]]
+name = "pingora-load-balancing"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "361b69af0234d2e4d10234e2efd106bb3b8147c575d52f45604a46aaf26def7a"
+dependencies = [
+ "arc-swap",
+ "async-trait",
+ "derivative",
+ "fnv",
+ "futures",
+ "http 1.4.2",
+ "log",
+ "pingora-core",
+ "pingora-error",
+ "pingora-http",
+ "pingora-ketama",
+ "pingora-runtime",
+ "rand 0.8.6",
+ "tokio",
+]
+
+[[package]]
+name = "pingora-lru"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6705a26ad89d241a989a5395641931ba37076f5ab5fbd19ee92402414a43af32"
+dependencies = [
+ "arrayvec",
+ "hashbrown 0.17.1",
+ "parking_lot",
+ "rand 0.8.6",
+]
+
+[[package]]
+name = "pingora-pool"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "feb1237893b15a9cf6b371bee8d7e2e1c10742e4be6eb00ed38cfe87fd1363f8"
+dependencies = [
+ "crossbeam-queue",
+ "log",
+ "lru",
+ "parking_lot",
+ "pingora-timeout",
+ "thread_local",
+ "tokio",
+]
+
+[[package]]
+name = "pingora-proxy"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a92ee756ecf6ecb6419864da651cad6cecd933b6d420a26877031efa16bef57"
+dependencies = [
+ "async-trait",
+ "bytes",
+ "clap",
+ "futures",
+ "h2 0.4.15",
+ "http 1.4.2",
+ "log",
+ "once_cell",
+ "pingora-cache",
+ "pingora-core",
+ "pingora-error",
+ "pingora-http",
+ "rand 0.8.6",
+ "regex",
+ "tokio",
+]
+
+[[package]]
+name = "pingora-runtime"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41815a13691a3e7d9ad0e34767d4140284132e31b95a4481f5e73ab6f407f834"
+dependencies = [
+ "once_cell",
+ "rand 0.8.6",
+ "thread_local",
+ "tokio",
+]
+
+[[package]]
+name = "pingora-rustls"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2c12f20ac2eb8d708763aba7ce3c6a21bfed113b07cee79906225da5a500d28"
+dependencies = [
+ "log",
+ "no_debug",
+ "pingora-error",
+ "ring",
+ "rustls",
+ "rustls-native-certs",
+ "rustls-pemfile 2.2.0",
+ "rustls-pki-types",
+ "tokio-rustls",
+]
+
+[[package]]
+name = "pingora-timeout"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e3e321452eaa461e0b6c5aaa35b7e42527ee89df33710279f37fae7f066b68e"
+dependencies = [
+ "once_cell",
+ "parking_lot",
+ "pin-project-lite",
+ "thread_local",
+ "tokio",
+]
+
 [[package]]
 name = "pkg-config"
 version = "0.3.33"
@@ -3650,7 +4523,7 @@ version = "0.18.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "crc32fast",
  "fdeflate",
  "flate2",
@@ -3729,7 +4602,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
 dependencies = [
  "proc-macro2",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -3750,12 +4623,40 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "proc-macro2-diagnostics"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af066a9c399a26e020ada66a034357a868728e72cd426f3adcd35f80d88d88c8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+ "version_check",
+ "yansi",
+]
+
 [[package]]
 name = "profiling"
 version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d595e54a326bc53c1c197b32d295e14b169e3cfeaa8dc82b529f947fba6bcf5"
 
+[[package]]
+name = "prometheus"
+version = "0.13.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d33c28a30771f7f96db69893f78b857f7450d7e0237e9c8fc6427a81bae7ed1"
+dependencies = [
+ "cfg-if",
+ "fnv",
+ "lazy_static",
+ "memchr",
+ "parking_lot",
+ "protobuf 2.28.0",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "prometheus"
 version = "0.14.0"
@@ -3767,15 +4668,15 @@ dependencies = [
  "lazy_static",
  "memchr",
  "parking_lot",
- "protobuf",
+ "protobuf 3.7.2",
  "thiserror 2.0.18",
 ]
 
 [[package]]
 name = "prost"
-version = "0.14.3"
+version = "0.14.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d2ea70524a2f82d518bce41317d0fae74151505651af45faf1ffbd6fd33f0568"
+checksum = "528ac67416ff8646872a3c02cad9cc4ee5dc9f9540c9b10771855c95cb2e5ae1"
 dependencies = [
  "bytes",
  "prost-derive",
@@ -3783,17 +4684,23 @@ dependencies = [
 
 [[package]]
 name = "prost-derive"
-version = "0.14.3"
+version = "0.14.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "27c6023962132f4b30eb4c172c91ce92d933da334c59c23cddee82358ddafb0b"
+checksum = "b570b25f7617e43d59005d0990ccb79e950a423952cea19671b7a876da390adf"
 dependencies = [
  "anyhow",
- "itertools",
+ "itertools 0.14.0",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
+[[package]]
+name = "protobuf"
+version = "2.28.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "106dd99e98437432fed6519dedecfade6a06a73bb7b2a1e019fdd2bee5778d94"
+
 [[package]]
 name = "protobuf"
 version = "3.7.2"
@@ -3848,7 +4755,7 @@ dependencies = [
  "quinn-udp",
  "rustc-hash 2.1.2",
  "rustls",
- "socket2 0.6.3",
+ "socket2 0.6.4",
  "thiserror 2.0.18",
  "tokio",
  "tracing",
@@ -3885,9 +4792,9 @@ dependencies = [
  "cfg_aliases",
  "libc",
  "once_cell",
- "socket2 0.6.3",
+ "socket2 0.6.4",
  "tracing",
- "windows-sys 0.59.0",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -4017,7 +4924,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
 ]
 
 [[package]]
@@ -4026,7 +4933,7 @@ version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5b44b894f2a6e36457d665d1e08c3866add6ed5e70050c1b4ba8a8ddedb02ce7"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
 ]
 
 [[package]]
@@ -4046,14 +4953,14 @@ checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
 name = "regex"
-version = "1.12.3"
+version = "1.12.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276"
+checksum = "f1292b7759ae1cb9ec195452d1390a074f0cd8541ab7a5a8c31cd6db45d4a6ba"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -4074,9 +4981,9 @@ dependencies = [
 
 [[package]]
 name = "regex-syntax"
-version = "0.8.10"
+version = "0.8.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "renderdoc-sys"
@@ -4095,7 +5002,7 @@ dependencies = [
  "encoding_rs",
  "futures-core",
  "futures-util",
- "h2",
+ "h2 0.3.27",
  "http 0.2.12",
  "http-body 0.4.6",
  "hyper 0.14.32",
@@ -4109,7 +5016,7 @@ dependencies = [
  "once_cell",
  "percent-encoding",
  "pin-project-lite",
- "rustls-pemfile",
+ "rustls-pemfile 1.0.4",
  "serde",
  "serde_json",
  "serde_urlencoded",
@@ -4138,10 +5045,10 @@ dependencies = [
  "futures-channel",
  "futures-core",
  "futures-util",
- "http 1.4.0",
+ "http 1.4.2",
  "http-body 1.0.1",
  "http-body-util",
- "hyper 1.9.0",
+ "hyper 1.10.1",
  "hyper-rustls",
  "hyper-util",
  "js-sys",
@@ -4167,7 +5074,7 @@ dependencies = [
  "wasm-bindgen-futures",
  "wasm-streams",
  "web-sys",
- "webpki-roots 1.0.7",
+ "webpki-roots 1.0.8",
 ]
 
 [[package]]
@@ -4184,6 +5091,41 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rmp"
+version = "0.8.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ba8be72d372b2c9b35542551678538b562e7cf86c3315773cae48dfbfe7790c"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "rmp-serde"
+version = "1.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f81bee8c8ef9b577d1681a70ebbc962c232461e397b22c208c43c04b67a155"
+dependencies = [
+ "rmp",
+ "serde",
+]
+
+[[package]]
+name = "rust_decimal"
+version = "1.42.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be2a24f50780bc85f09cc6ac299bdf1424302742d77221106859c9d8b102126a"
+dependencies = [
+ "arrayvec",
+ "num-traits",
+]
+
+[[package]]
+name = "rustc-demangle"
+version = "0.1.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b50b8869d9fc858ce7266cce0194bd74df58b9d0e3f6df3a9fc8eb470d95c09d"
+
 [[package]]
 name = "rustc-hash"
 version = "1.1.0"
@@ -4205,13 +5147,22 @@ dependencies = [
  "semver",
 ]
 
+[[package]]
+name = "rusticata-macros"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "faf0c4a6ece9950b9abdb62b1cfcf2a68b3b67a10ba445b3bb85be2a293d0632"
+dependencies = [
+ "nom",
+]
+
 [[package]]
 name = "rustix"
 version = "0.38.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "errno",
  "libc",
  "linux-raw-sys 0.4.15",
@@ -4224,7 +5175,7 @@ version = "1.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "errno",
  "libc",
  "linux-raw-sys 0.12.1",
@@ -4233,10 +5184,12 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.38"
+version = "0.23.40"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "69f9466fb2c14ea04357e91413efb882e2a6d4a406e625449bc0a5d360d53a21"
+checksum = "ef86cd5876211988985292b91c96a8f2d298df24e75989a43a3c73f2d4d8168b"
 dependencies = [
+ "aws-lc-rs",
+ "log",
  "once_cell",
  "ring",
  "rustls-pki-types",
@@ -4245,6 +5198,19 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "rustls-native-certs"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5bfb394eeed242e909609f56089eecfe5fda225042e8b171791b9c95f5931e5"
+dependencies = [
+ "openssl-probe",
+ "rustls-pemfile 2.2.0",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+
 [[package]]
 name = "rustls-pemfile"
 version = "1.0.4"
@@ -4255,10 +5221,19 @@ dependencies = [
 ]
 
 [[package]]
-name = "rustls-pki-types"
-version = "1.14.0"
+name = "rustls-pemfile"
+version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "be040f8b0a225e40375822a563fa9524378b9d63112f53e19ffff34df5d33fdd"
+checksum = "dce314e5fee3f39953d46bb63bb8a46d40c2f8fb7cc5a3b6cab2bde9721d6e50"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30a7197ae7eb376e574fe940d068c30fe0462554a3ddbe4eca7838e049c937a9"
 dependencies = [
  "web-time",
  "zeroize",
@@ -4266,10 +5241,11 @@ dependencies = [
 
 [[package]]
 name = "rustls-webpki"
-version = "0.103.12"
+version = "0.103.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8279bb85272c9f10811ae6a6c547ff594d6a7f3c6c6b02ee9726d1d0dcfcdd06"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
 dependencies = [
+ "aws-lc-rs",
  "ring",
  "rustls-pki-types",
  "untrusted",
@@ -4350,7 +5326,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "serde_derive_internals",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -4377,7 +5353,7 @@ version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "897b2245f0b511c87893af39b033e5ca9cce68824c4d7e7630b5a1d339658d02"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "core-foundation 0.9.4",
  "core-foundation-sys",
  "libc",
@@ -4427,7 +5403,7 @@ checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -4438,14 +5414,14 @@ checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.149"
+version = "1.0.150"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
 dependencies = [
  "itoa",
  "memchr",
@@ -4488,11 +5464,12 @@ dependencies = [
 
 [[package]]
 name = "serde_with"
-version = "3.18.0"
+version = "3.21.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd5414fad8e6907dbdd5bc441a50ae8d6e26151a03b1de04d89a5576de61d01f"
+checksum = "76a5c54c7310e7b8b9577c286d7e399ddd876c3e12b3ed917a8aabc4b96e9e8c"
 dependencies = [
  "base64 0.22.1",
+ "bs58",
  "chrono",
  "hex",
  "indexmap 1.9.3",
@@ -4507,14 +5484,27 @@ dependencies = [
 
 [[package]]
 name = "serde_with_macros"
-version = "3.18.0"
+version = "3.21.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d3db8978e608f1fe7357e211969fd9abdcae80bac1ba7a3369bb7eb6b404eb65"
+checksum = "84d57bc0c8b9a17920c178daa6bb924850d54a9c97ab45194bb8c17ad66bb660"
 dependencies = [
- "darling",
+ "darling 0.23.0",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap 2.14.0",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
 ]
 
 [[package]]
@@ -4524,6 +5514,17 @@ dependencies = [
  "eframe",
 ]
 
+[[package]]
+name = "sfv"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3fa1f336066b758b7c9df34ed049c0e693a426afe2b27ff7d5b14f410ab1a132"
+dependencies = [
+ "base64 0.22.1",
+ "indexmap 2.14.0",
+ "rust_decimal",
+]
+
 [[package]]
 name = "sha1"
 version = "0.10.6"
@@ -4596,9 +5597,9 @@ dependencies = [
 
 [[package]]
 name = "shlex"
-version = "1.3.0"
+version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "signal-hook-registry"
@@ -4667,9 +5668,9 @@ dependencies = [
 
 [[package]]
 name = "smallvec"
-version = "1.15.1"
+version = "1.15.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
 
 [[package]]
 name = "smithay-client-toolkit"
@@ -4677,7 +5678,7 @@ version = "0.19.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3457dea1f0eb631b4034d61d4d8c32074caa6cd1ab2d59f2327bd8461e2c0016"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "calloop 0.13.0",
  "calloop-wayland-source 0.3.0",
  "cursor-icon",
@@ -4702,7 +5703,7 @@ version = "0.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0512da38f5e2b31201a93524adb8d3136276fa4fe4aafab4e1f727a82b534cc0"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "calloop 0.14.4",
  "calloop-wayland-source 0.4.1",
  "cursor-icon",
@@ -4755,9 +5756,9 @@ dependencies = [
 
 [[package]]
 name = "socket2"
-version = "0.6.3"
+version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e"
+checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
 dependencies = [
  "libc",
  "windows-sys 0.61.2",
@@ -4840,7 +5841,7 @@ dependencies = [
  "bytes",
  "derive_more",
  "getrandom 0.2.17",
- "http 1.4.0",
+ "http 1.4.2",
  "log",
  "rand 0.8.6",
  "scoped-tls",
@@ -4863,7 +5864,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "spacetimedb-primitives",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -4893,7 +5894,7 @@ dependencies = [
  "spacetimedb-lib",
  "spacetimedb-primitives",
  "spacetimedb-sats",
- "strum",
+ "strum 0.25.0",
  "thiserror 1.0.69",
 ]
 
@@ -4919,7 +5920,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "523a8d4a746bb4403fe3e5241e3a72204fc1358e3b118b4f827de7673b6aabcb"
 dependencies = [
  "anyhow",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "blake3",
  "bytes",
  "chrono",
@@ -4927,7 +5928,7 @@ dependencies = [
  "enum-as-inner",
  "enum-map",
  "hex",
- "itertools",
+ "itertools 0.12.1",
  "log",
  "serde",
  "spacetimedb-bindings-macro",
@@ -4954,9 +5955,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "226d91f133dcb792dd04ec3870828c4c1d7815a33646e8226894087f1680f8a9"
 dependencies = [
  "arrayvec",
- "itertools",
+ "itertools 0.12.1",
  "paste",
- "prometheus",
+ "prometheus 0.14.0",
 ]
 
 [[package]]
@@ -4965,10 +5966,10 @@ version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f625481d6715f9b0aba612599be6c4ab1028ab99425d23d75a268a49628a43f8"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "either",
  "enum-as-inner",
- "itertools",
+ "itertools 0.12.1",
  "nohash-hasher",
  "spacetimedb-memory-usage",
 ]
@@ -4990,7 +5991,7 @@ checksum = "449ff63e22853eeaf903563f3cfaf8557ba0c84d0a62abcc388ac429670d321c"
 dependencies = [
  "anyhow",
  "arrayvec",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "bytemuck",
  "bytes",
  "bytestring",
@@ -5000,7 +6001,7 @@ dependencies = [
  "enum-as-inner",
  "ethnum",
  "hex",
- "itertools",
+ "itertools 0.12.1",
  "lean_string",
  "rand 0.9.4",
  "second-stack",
@@ -5028,10 +6029,10 @@ dependencies = [
  "enum-map",
  "indexmap 2.14.0",
  "insta",
- "itertools",
+ "itertools 0.12.1",
  "lazy_static",
  "lean_string",
- "petgraph",
+ "petgraph 0.6.5",
  "serde_json",
  "smallvec",
  "spacetimedb-data-structures",
@@ -5060,11 +6061,11 @@ dependencies = [
  "futures",
  "futures-channel",
  "home",
- "http 1.4.0",
+ "http 1.4.2",
  "log",
  "native-tls",
  "once_cell",
- "prometheus",
+ "prometheus 0.14.0",
  "rand 0.9.4",
  "spacetimedb-client-api-messages",
  "spacetimedb-data-structures",
@@ -5111,6 +6112,15 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
 
+[[package]]
+name = "strip-ansi-escapes"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a8f8038e7e7969abb3f1b7c2a811225e9296da208539e0f79c5251d6cac0025"
+dependencies = [
+ "vte",
+]
+
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -5123,7 +6133,16 @@ version = "0.25.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "290d54ea6f91c969195bdbcd7442c8c2a2ba87da8bf60a7ee86a235d4bc1e125"
 dependencies = [
- "strum_macros",
+ "strum_macros 0.25.3",
+]
+
+[[package]]
+name = "strum"
+version = "0.26.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
+dependencies = [
+ "strum_macros 0.26.4",
 ]
 
 [[package]]
@@ -5136,7 +6155,20 @@ dependencies = [
  "proc-macro2",
  "quote",
  "rustversion",
- "syn",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "strum_macros"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c6bee85a5a24955dc440386795aa378cd9cf82acd5f764469152d2270e581be"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "rustversion",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5147,9 +6179,20 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
 
 [[package]]
 name = "syn"
-version = "2.0.117"
+version = "1.0.109"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -5179,7 +6222,7 @@ checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5255,7 +6298,7 @@ checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5266,7 +6309,7 @@ checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5278,6 +6321,16 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "thrift_codec"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83d957f535b242b91aa9f47bde08080f9a6fef276477e55b0079979d002759d5"
+dependencies = [
+ "byteorder",
+ "trackable",
+]
+
 [[package]]
 name = "tiff"
 version = "0.11.3"
@@ -5294,12 +6347,11 @@ dependencies = [
 
 [[package]]
 name = "time"
-version = "0.3.47"
+version = "0.3.49"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "743bd48c283afc0388f9b8827b976905fb217ad9e647fae3a379a9283c4def2c"
+checksum = "711a53c2d47bbd818258c498c8dbfe186a2526c631495cfe7e078567f86b8469"
 dependencies = [
  "deranged",
- "itoa",
  "num-conv",
  "powerfmt",
  "serde_core",
@@ -5309,15 +6361,15 @@ dependencies = [
 
 [[package]]
 name = "time-core"
-version = "0.1.8"
+version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7694e1cfe791f8d31026952abf09c69ca6f6fa4e1a1229e18988f06a04a12dca"
+checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
 
 [[package]]
 name = "time-macros"
-version = "0.2.27"
+version = "0.2.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e70e4c5a0e0a8a4823ad65dfe1a6930e4f4d756dcd9dd7939022b5e8c501215"
+checksum = "71c652a3727a9cbb9a02f707f530b618ce00d0ccd762009c8c23bd191df3c17d"
 dependencies = [
  "num-conv",
  "time-core",
@@ -5350,9 +6402,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.52.1"
+version = "1.52.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b67dee974fe86fd92cc45b7a95fdd2f99a36a6d7b0d431a231178d3d670bbcc6"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
 dependencies = [
  "bytes",
  "libc",
@@ -5360,7 +6412,7 @@ dependencies = [
  "parking_lot",
  "pin-project-lite",
  "signal-hook-registry",
- "socket2 0.6.3",
+ "socket2 0.6.4",
  "tokio-macros",
  "windows-sys 0.61.2",
 ]
@@ -5373,7 +6425,7 @@ checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5407,6 +6459,17 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-test"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f6d24790a10a7af737693a3e8f1d03faef7e6ca0cc99aae5066f533766de545"
+dependencies = [
+ "futures-core",
+ "tokio",
+ "tokio-stream",
+]
+
 [[package]]
 name = "tokio-tungstenite"
 version = "0.27.0"
@@ -5461,9 +6524,9 @@ dependencies = [
 
 [[package]]
 name = "toml_edit"
-version = "0.25.11+spec-1.1.0"
+version = "0.25.12+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b59c4d22ed448339746c59b905d24568fcbb3ab65a500494f7b8c3e97739f2b"
+checksum = "d2153edc6955a6c354fad8f5efd38b6a8769bdccf9fe50f8e1329f81b0baa5d7"
 dependencies = [
  "indexmap 2.14.0",
  "serde_core",
@@ -5498,7 +6561,7 @@ dependencies = [
  "async-trait",
  "base64 0.22.1",
  "bytes",
- "http 1.4.0",
+ "http 1.4.2",
  "http-body 1.0.1",
  "http-body-util",
  "percent-encoding",
@@ -5539,21 +6602,21 @@ dependencies = [
 
 [[package]]
 name = "tower-http"
-version = "0.6.8"
+version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "bytes",
  "futures-util",
- "http 1.4.0",
+ "http 1.4.2",
  "http-body 1.0.1",
- "iri-string",
  "pin-project-lite",
  "tower",
  "tower-layer",
  "tower-service",
  "tracing",
+ "url",
 ]
 
 [[package]]
@@ -5588,7 +6651,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -5646,6 +6709,25 @@ dependencies = [
  "tracing-log",
 ]
 
+[[package]]
+name = "trackable"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b15bd114abb99ef8cee977e517c8f37aee63f184f2d08e3e6ceca092373369ae"
+dependencies = [
+ "trackable_derive",
+]
+
+[[package]]
+name = "trackable_derive"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebeb235c5847e2f82cfe0f07eb971d1e5f6804b18dac2ae16349cc604380f82f"
+dependencies = [
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "try-lock"
 version = "0.2.5"
@@ -5666,7 +6748,7 @@ checksum = "eadc29d668c91fcc564941132e17b28a7ceb2f3ebf0b9dae3e03fd7a6748eb0d"
 dependencies = [
  "bytes",
  "data-encoding",
- "http 1.4.0",
+ "http 1.4.2",
  "httparse",
  "log",
  "native-tls",
@@ -5687,7 +6769,7 @@ checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8"
 dependencies = [
  "bytes",
  "data-encoding",
- "http 1.4.0",
+ "http 1.4.2",
  "httparse",
  "log",
  "rand 0.9.4",
@@ -5715,9 +6797,9 @@ dependencies = [
 
 [[package]]
 name = "typenum"
-version = "1.20.0"
+version = "1.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "40ce102ab67701b8526c123c1bab5cbe42d7040ccfd0f64af1a385808d2f43de"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
 
 [[package]]
 name = "unicase"
@@ -5742,9 +6824,9 @@ dependencies = [
 
 [[package]]
 name = "unicode-segmentation"
-version = "1.13.2"
+version = "1.13.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9629274872b2bfaf8d66f5f15725007f635594914870f65218920345aa11aa8c"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
 
 [[package]]
 name = "unicode-width"
@@ -5758,6 +6840,12 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
 [[package]]
 name = "untrusted"
 version = "0.9.0"
@@ -5795,10 +6883,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
 [[package]]
-name = "uuid"
-version = "1.23.1"
+name = "utf8parse"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "uuid"
+version = "1.23.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "144d6b123cef80b301b8f72a9e2ca4370ddec21950d0a103dd22c437006d2db7"
 dependencies = [
  "getrandom 0.4.2",
  "js-sys",
@@ -5824,6 +6918,15 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
+[[package]]
+name = "vte"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "231fdcd7ef3037e8330d8e17e61011a2c244126acc0a982f4040ac3f9f0bc077"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "walkdir"
 version = "2.5.0"
@@ -5851,9 +6954,9 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 
 [[package]]
 name = "wasip2"
-version = "1.0.3+wasi-0.2.9"
+version = "1.0.4+wasi-0.2.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "20064672db26d7cdc89c7798c48a0fdfac8213434a1186e5ef29fd560ae223d6"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
 dependencies = [
  "wit-bindgen 0.57.1",
 ]
@@ -5869,9 +6972,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.118"
+version = "0.2.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0bf938a0bacb0469e83c1e148908bd7d5a6010354cf4fb73279b7447422e3a89"
+checksum = "8ddb3f79143bced6de84270411622a2699cee572fc0875aeaf1e7867cf9fca1a"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -5882,9 +6985,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.68"
+version = "0.4.75"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f371d383f2fb139252e0bfac3b81b265689bf45b6874af544ffa4c975ac1ebf8"
+checksum = "503b14d284f2c8dac03b819967e155ea753f573586193b2b2c95990cb5d69280"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -5892,9 +6995,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.118"
+version = "0.2.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eeff24f84126c0ec2db7a449f0c2ec963c6a49efe0698c4242929da037ca28ed"
+checksum = "4e21a184b13fb19e157296e2c46056aec9092264fab83e4ba59e68c61b323c3d"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -5902,22 +7005,22 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.118"
+version = "0.2.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9d08065faf983b2b80a79fd87d8254c409281cf7de75fc4b773019824196c904"
+checksum = "fecefd9c35bd935a20fc3fc344b5f29138961e4f47fb03297d88f2587afb5ebd"
 dependencies = [
  "bumpalo",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
  "wasm-bindgen-shared",
 ]
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.118"
+version = "0.2.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5fd04d9e306f1907bd13c6361b5c6bfc7b3b3c095ed3f8a9246390f8dbdee129"
+checksum = "23939e44bb9a5d7576fa2b563dc2e136628f1224e88a8deed09e04858b77871f"
 dependencies = [
  "unicode-ident",
 ]
@@ -5963,7 +7066,7 @@ version = "0.244.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "hashbrown 0.15.5",
  "indexmap 2.14.0",
  "semver",
@@ -5989,7 +7092,7 @@ version = "0.31.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "645c7c96bb74690c3189b5c9cb4ca1627062bb23693a4fad9d8c3de958260144"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "rustix 1.1.4",
  "wayland-backend",
  "wayland-scanner",
@@ -6001,7 +7104,7 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "625c5029dbd43d25e6aa9615e88b829a5cad13b2819c4ae129fdbb7c31ab4c7e"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "cursor-icon",
  "wayland-backend",
 ]
@@ -6023,7 +7126,7 @@ version = "0.32.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "563a85523cade2429938e790815fd7319062103b9f4a2dc806e9b53b95982d8f"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "wayland-backend",
  "wayland-client",
  "wayland-scanner",
@@ -6035,7 +7138,7 @@ version = "20250721.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "40a1f863128dcaaec790d7b4b396cc9b9a7a079e878e18c47e6c2d2c5a8dcbb1"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "wayland-backend",
  "wayland-client",
  "wayland-protocols",
@@ -6048,7 +7151,7 @@ version = "0.3.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e9567599ef23e09b8dad6e429e5738d4509dfc46b3b21f32841a304d16b29c8"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "wayland-backend",
  "wayland-client",
  "wayland-protocols",
@@ -6061,7 +7164,7 @@ version = "0.3.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2b6d8cf1eb2c1c31ed1f5643c88a6e53538129d4af80030c8cabd1f9fa884d91"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "wayland-backend",
  "wayland-client",
  "wayland-protocols",
@@ -6074,7 +7177,7 @@ version = "0.3.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eb04e52f7836d7c7976c78ca0250d61e33873c34156a2a1fc9474828ec268234"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "wayland-backend",
  "wayland-client",
  "wayland-protocols",
@@ -6106,9 +7209,9 @@ dependencies = [
 
 [[package]]
 name = "web-sys"
-version = "0.3.95"
+version = "0.3.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f2dfbb17949fa2088e5d39408c48368947b86f7834484e87b73de55bc14d97d"
+checksum = "a6430a72df5eb332242960fe84b3002a241163998241eb596d4f739b9757061d"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -6156,14 +7259,14 @@ version = "0.26.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
 dependencies = [
- "webpki-roots 1.0.7",
+ "webpki-roots 1.0.8",
 ]
 
 [[package]]
 name = "webpki-roots"
-version = "1.0.7"
+version = "1.0.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52f5ee44c96cf55f1b349600768e3ece3a8f26010c05265ab73f945bb1a2eb9d"
+checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf"
 dependencies = [
  "rustls-pki-types",
 ]
@@ -6181,7 +7284,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bfe68bac7cde125de7a731c3400723cadaaf1703795ad3f4805f187459cd7a77"
 dependencies = [
  "arrayvec",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "cfg-if",
  "cfg_aliases",
  "document-features",
@@ -6206,7 +7309,7 @@ dependencies = [
  "arrayvec",
  "bit-set",
  "bit-vec",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "bytemuck",
  "cfg_aliases",
  "document-features",
@@ -6242,7 +7345,7 @@ version = "27.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5b21cb61c57ee198bc4aff71aeadff4cbb80b927beb912506af9c780d64313ce"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "cfg-if",
  "cfg_aliases",
  "libloading",
@@ -6262,7 +7365,7 @@ version = "27.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "afdcf84c395990db737f2dd91628706cb31e86d72e53482320d368e52b5da5eb"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "bytemuck",
  "js-sys",
  "log",
@@ -6300,7 +7403,7 @@ checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -6311,7 +7414,7 @@ checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -6365,6 +7468,15 @@ dependencies = [
  "windows-targets 0.52.6",
 ]
 
+[[package]]
+name = "windows-sys"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
+dependencies = [
+ "windows-targets 0.53.5",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.61.2"
@@ -6398,13 +7510,30 @@ dependencies = [
  "windows_aarch64_gnullvm 0.52.6",
  "windows_aarch64_msvc 0.52.6",
  "windows_i686_gnu 0.52.6",
- "windows_i686_gnullvm",
+ "windows_i686_gnullvm 0.52.6",
  "windows_i686_msvc 0.52.6",
  "windows_x86_64_gnu 0.52.6",
  "windows_x86_64_gnullvm 0.52.6",
  "windows_x86_64_msvc 0.52.6",
 ]
 
+[[package]]
+name = "windows-targets"
+version = "0.53.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
+dependencies = [
+ "windows-link",
+ "windows_aarch64_gnullvm 0.53.1",
+ "windows_aarch64_msvc 0.53.1",
+ "windows_i686_gnu 0.53.1",
+ "windows_i686_gnullvm 0.53.1",
+ "windows_i686_msvc 0.53.1",
+ "windows_x86_64_gnu 0.53.1",
+ "windows_x86_64_gnullvm 0.53.1",
+ "windows_x86_64_msvc 0.53.1",
+]
+
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.48.5"
@@ -6417,6 +7546,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
 
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
+
 [[package]]
 name = "windows_aarch64_msvc"
 version = "0.48.5"
@@ -6429,6 +7564,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
 
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
+
 [[package]]
 name = "windows_i686_gnu"
 version = "0.48.5"
@@ -6441,12 +7582,24 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
 
+[[package]]
+name = "windows_i686_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
+
 [[package]]
 name = "windows_i686_gnullvm"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
 
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
+
 [[package]]
 name = "windows_i686_msvc"
 version = "0.48.5"
@@ -6459,6 +7612,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
 
+[[package]]
+name = "windows_i686_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
+
 [[package]]
 name = "windows_x86_64_gnu"
 version = "0.48.5"
@@ -6471,6 +7630,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
 
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
+
 [[package]]
 name = "windows_x86_64_gnullvm"
 version = "0.48.5"
@@ -6483,6 +7648,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
 
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
+
 [[package]]
 name = "windows_x86_64_msvc"
 version = "0.48.5"
@@ -6495,6 +7666,12 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
+
 [[package]]
 name = "winit"
 version = "0.30.13"
@@ -6504,7 +7681,7 @@ dependencies = [
  "ahash",
  "android-activity",
  "atomic-waker",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "block2",
  "bytemuck",
  "calloop 0.13.0",
@@ -6548,9 +7725,9 @@ dependencies = [
 
 [[package]]
 name = "winnow"
-version = "1.0.1"
+version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09dac053f1cd375980747450bfc7250c264eaae0583872e845c0c7cd578872b5"
+checksum = "0592e1c9d151f854e6fd382574c3a0855250e1d9b2f99d9281c6e6391af352f1"
 dependencies = [
  "memchr",
 ]
@@ -6601,7 +7778,7 @@ dependencies = [
  "heck 0.5.0",
  "indexmap 2.14.0",
  "prettyplease",
- "syn",
+ "syn 2.0.118",
  "wasm-metadata",
  "wit-bindgen-core",
  "wit-component",
@@ -6617,7 +7794,7 @@ dependencies = [
  "prettyplease",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
  "wit-bindgen-core",
  "wit-bindgen-rust",
 ]
@@ -6629,7 +7806,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
  "anyhow",
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "indexmap 2.14.0",
  "log",
  "serde",
@@ -6697,6 +7874,23 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
 
+[[package]]
+name = "x509-parser"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcbc162f30700d6f3f82a24bf7cc62ffe7caea42c0b2cba8bf7f3ae50cf51f69"
+dependencies = [
+ "asn1-rs",
+ "data-encoding",
+ "der-parser",
+ "lazy_static",
+ "nom",
+ "oid-registry",
+ "rusticata-macros",
+ "thiserror 1.0.69",
+ "time",
+]
+
 [[package]]
 name = "xcursor"
 version = "0.3.10"
@@ -6709,7 +7903,7 @@ version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d039de8032a9a8856a6be89cea3e5d12fdd82306ab7c94d74e6deab2460651c5"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.0",
  "dlib",
  "log",
  "once_cell",
@@ -6729,10 +7923,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3ae8337f8a065cfc972643663ea4279e04e7256de865aa66fe25cec5fb912d3f"
 
 [[package]]
-name = "yoke"
-version = "0.8.2"
+name = "yansi"
+version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "abe8c5fda708d9ca3df187cae8bfb9ceda00dd96231bed36e445a1a48e66f9ca"
+checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
 dependencies = [
  "stable_deref_trait",
  "yoke-derive",
@@ -6747,35 +7947,35 @@ checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
  "synstructure",
 ]
 
 [[package]]
 name = "zerocopy"
-version = "0.8.48"
+version = "0.8.52"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eed437bf9d6692032087e337407a86f04cd8d6a16a37199ed57949d415bd68e9"
+checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.48"
+version = "0.8.52"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "70e3cd084b1788766f53af483dd21f93881ff30d7320490ec3ef7526d203bad4"
+checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
 name = "zerofrom"
-version = "0.1.7"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "69faa1f2a1ea75661980b013019ed6687ed0e83d069bc1114e2cc74c6c04c4df"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
 dependencies = [
  "zerofrom-derive",
 ]
@@ -6788,15 +7988,15 @@ checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
  "synstructure",
 ]
 
 [[package]]
 name = "zeroize"
-version = "1.8.2"
+version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
 
 [[package]]
 name = "zerotrie"
@@ -6828,7 +8028,7 @@ checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.118",
 ]
 
 [[package]]
@@ -6866,6 +8066,34 @@ dependencies = [
  "simd-adler32",
 ]
 
+[[package]]
+name = "zstd"
+version = "0.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e91ee311a569c327171651566e07972200e76fcfe2242a4fa446149a3881c08a"
+dependencies = [
+ "zstd-safe",
+]
+
+[[package]]
+name = "zstd-safe"
+version = "7.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f49c4d5f0abb602a93fb8736af2a4f4dd9512e36f7f570d66e65ff867ed3b9d"
+dependencies = [
+ "zstd-sys",
+]
+
+[[package]]
+name = "zstd-sys"
+version = "2.0.16+zstd.1.5.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e19ebc2adc8f83e43039e79776e3fda8ca919132d68a1fed6a5faca2683748"
+dependencies = [
+ "cc",
+ "pkg-config",
+]
+
 [[package]]
 name = "zune-core"
 version = "0.5.1"
diff --git a/server-rs/Cargo.toml b/server-rs/Cargo.toml
index 2a6229c39..a7c331ee5 100644
--- a/server-rs/Cargo.toml
+++ b/server-rs/Cargo.toml
@@ -40,6 +40,7 @@ members = [
     "crates/platform-wechat",
     "crates/platform-speech",
     "crates/platform-agent",
+    "crates/pingora-gateway",
     "crates/server-manager-panel",
     "crates/shared-contracts",
     "crates/shared-kernel",
@@ -88,6 +89,7 @@ platform-llm = { path = "crates/platform-llm", default-features = false }
 platform-oss = { path = "crates/platform-oss", default-features = false }
 platform-speech = { path = "crates/platform-speech", default-features = false }
 platform-wechat = { path = "crates/platform-wechat", default-features = false }
+pingora-gateway = { path = "crates/pingora-gateway", default-features = false }
 shared-contracts = { path = "crates/shared-contracts", default-features = false }
 shared-kernel = { path = "crates/shared-kernel", default-features = false }
 shared-logging = { path = "crates/shared-logging", default-features = false }
@@ -107,11 +109,16 @@ flate2 = "1"
 futures-util = "0.3"
 hmac = "0.12"
 http-body-util = "0.1"
+httpdate = "1"
 hex = "0.4"
 image = { version = "0.25", default-features = false }
 jsonwebtoken = "9"
 langchainrust = "0.2.18"
 log = "0.4"
+mime_guess = "2.0.5"
+pingora = { version = "0.8.1", default-features = false, features = ["proxy", "rustls"] }
+pingora-http = { version = "0.8.1", default-features = false }
+pingora-proxy = { version = "0.8.1", default-features = false }
 rand_core = "0.6"
 reqwest = { version = "0.12", default-features = false }
 ring = "0.17"
diff --git a/server-rs/crates/api-server/src/creative_agent.rs b/server-rs/crates/api-server/src/creative_agent.rs
index 65dc28126..f83344861 100644
--- a/server-rs/crates/api-server/src/creative_agent.rs
+++ b/server-rs/crates/api-server/src/creative_agent.rs
@@ -1431,4 +1431,62 @@ mod tests {
         assert_eq!(next["workTitle"], json!("轻松家庭拼图"));
         assert_eq!(next["levels"][0]["pictureDescription"], json!("旧图面"));
     }
+
+    #[test]
+    fn draft_edit_writeback_uses_stable_puzzle_profile_from_target_session() {
+        let target_session_id = "puzzle-session-b1cf819ea2d944c4a7e34ca668f8a97c";
+        let profile_id = build_puzzle_result_profile_id(target_session_id);
+        let draft = json!({
+            "workTitle": "雨夜猫街",
+            "workDescription": "在灯牌下寻找猫的拼图",
+            "summary": "雨夜猫街拼图",
+            "themeTags": ["猫", "雨夜"],
+            "coverImageSrc": "/generated-puzzle-assets/cat.png",
+            "coverAssetId": "asset-cat",
+            "levels": [{
+                "levelId": "puzzle-level-1",
+                "levelName": "灯牌下的猫",
+                "pictureDescription": "一只猫在雨夜灯牌下回头",
+                "pictureReference": null,
+                "selectedCandidateId": "candidate-1",
+                "coverImageSrc": "/generated-puzzle-assets/cat.png",
+                "coverAssetId": "asset-cat",
+                "generationStatus": "ready",
+                "candidates": []
+            }]
+        });
+
+        let input = build_puzzle_work_update_from_draft(profile_id, "user-1".to_string(), &draft)
+            .expect("writeback payload should build");
+
+        assert_eq!(
+            input.profile_id,
+            "puzzle-profile-b1cf819ea2d944c4a7e34ca668f8a97c"
+        );
+        assert_eq!(input.owner_user_id, "user-1");
+        assert_eq!(input.work_title, "雨夜猫街");
+        assert_eq!(input.work_description, "在灯牌下寻找猫的拼图");
+        assert_eq!(input.level_name, "灯牌下的猫");
+        assert_eq!(input.summary, "雨夜猫街拼图");
+        assert_eq!(input.theme_tags, vec!["猫".to_string(), "雨夜".to_string()]);
+        assert_eq!(
+            input.cover_image_src.as_deref(),
+            Some("/generated-puzzle-assets/cat.png")
+        );
+        assert_eq!(input.cover_asset_id.as_deref(), Some("asset-cat"));
+
+        let levels: Vec<Value> = serde_json::from_str(
+            input
+                .levels_json
+                .as_deref()
+                .expect("levels should be serialized"),
+        )
+        .expect("levels json should parse");
+        assert_eq!(levels[0]["level_id"], json!("puzzle-level-1"));
+        assert_eq!(levels[0]["level_name"], json!("灯牌下的猫"));
+        assert_eq!(
+            levels[0]["picture_description"],
+            json!("一只猫在雨夜灯牌下回头")
+        );
+    }
 }
diff --git a/server-rs/crates/api-server/src/external_generation_worker.rs b/server-rs/crates/api-server/src/external_generation_worker.rs
index ec90016af..fe110c2ed 100644
--- a/server-rs/crates/api-server/src/external_generation_worker.rs
+++ b/server-rs/crates/api-server/src/external_generation_worker.rs
@@ -744,6 +744,7 @@ mod tests {
             started_at: Some("2026-06-03T00:00:00Z".to_string()),
             completed_at: None,
             updated_at: "2026-06-03T00:00:00Z".to_string(),
+            updated_at_micros: 1_748_908_800_000_000,
             lease_token: lease_token.map(ToOwned::to_owned),
         }
     }
diff --git a/server-rs/crates/api-server/src/main.rs b/server-rs/crates/api-server/src/main.rs
index 38e0f23b9..90af7ba2f 100644
--- a/server-rs/crates/api-server/src/main.rs
+++ b/server-rs/crates/api-server/src/main.rs
@@ -116,7 +116,7 @@ use tracing::{error, info, warn};
 
 use crate::{
     app::{build_router, build_spacetime_unavailable_router},
-    config::AppConfig,
+    config::{AppConfig, ProcessRole},
     external_generation_worker::run_external_generation_worker,
     external_generation_worker_controller::run_external_generation_worker_controller,
     state::{AppState, AppStateInitError},
@@ -181,13 +181,11 @@ async fn run_server(config: AppConfig) -> Result<(), io::Error> {
 
 async fn run_worker_only(config: AppConfig) -> Result<(), io::Error> {
     let process_role = config.process_role;
-    let state = restore_app_state_for_startup(config)
-        .await
-        .map_err(|error| {
-            io::Error::other(format!(
-                "初始化 external generation worker 状态失败：{error}"
-            ))
-        })?;
+    let state = build_non_http_app_state_for_startup(config).map_err(|error| {
+        io::Error::other(format!(
+            "初始化 external generation worker 状态失败：{error}"
+        ))
+    })?;
     spawn_app_state_background_workers(&state);
     info!(
         process_role = process_role.as_str(),
@@ -205,6 +203,22 @@ async fn run_worker_only(config: AppConfig) -> Result<(), io::Error> {
     }
 }
 
+fn build_non_http_app_state_for_startup(
+    config: AppConfig,
+) -> Result<AppState, state::AppStateInitError> {
+    let process_role = config.process_role;
+    debug_assert!(!should_restore_auth_store_for_startup(process_role));
+    info!(
+        process_role = process_role.as_str(),
+        "非 HTTP 进程跳过 SpacetimeDB 认证快照恢复"
+    );
+    AppState::new_with_empty_auth_store(config)
+}
+
+fn should_restore_auth_store_for_startup(process_role: ProcessRole) -> bool {
+    process_role.runs_http()
+}
+
 async fn run_http_role(config: AppConfig) -> Result<(), io::Error> {
     let bind_address = config.bind_socket_addr();
     let listen_backlog = config.listen_backlog;
@@ -520,8 +534,9 @@ fn is_valid_env_key(key: &str) -> bool {
 mod tests {
     use super::{
         AUTH_STORE_STARTUP_RETRY_INTERVAL, is_valid_env_key, protected_env_keys_from,
-        strip_env_value,
+        should_restore_auth_store_for_startup, strip_env_value,
     };
+    use crate::config::ProcessRole;
 
     #[test]
     fn strip_env_value_removes_wrapping_quotes() {
@@ -567,4 +582,16 @@ mod tests {
     fn startup_dependency_retry_interval_is_short_enough_for_service_recovery() {
         assert_eq!(AUTH_STORE_STARTUP_RETRY_INTERVAL.as_secs(), 5);
     }
+
+    #[test]
+    fn auth_store_startup_restore_is_limited_to_http_roles() {
+        assert!(should_restore_auth_store_for_startup(ProcessRole::Api));
+        assert!(should_restore_auth_store_for_startup(ProcessRole::All));
+        assert!(!should_restore_auth_store_for_startup(
+            ProcessRole::ExternalGenerationWorker
+        ));
+        assert!(!should_restore_auth_store_for_startup(
+            ProcessRole::ExternalGenerationController
+        ));
+    }
 }
diff --git a/server-rs/crates/api-server/src/puzzle.rs b/server-rs/crates/api-server/src/puzzle.rs
index cc9d0237e..e7f5ca4b1 100644
--- a/server-rs/crates/api-server/src/puzzle.rs
+++ b/server-rs/crates/api-server/src/puzzle.rs
@@ -25,6 +25,7 @@ use platform_oss::{OssHeadObjectRequest, OssObjectAccess, OssPutObjectRequest};
 use serde_json::{Value, json};
 use shared_contracts::{
     creation_audio::CreationAudioAsset,
+    external_generation::{ExternalGenerationJobStatus, ExternalGenerationJobStatusRecord},
     puzzle_agent::{
         CreatePuzzleAgentSessionRequest, ExecutePuzzleAgentActionRequest,
         PuzzleAgentActionResponse, PuzzleAgentMessageResponse, PuzzleAgentOperationResponse,
@@ -52,7 +53,7 @@ use shared_contracts::{
 };
 use shared_kernel::{build_prefixed_uuid_id, format_timestamp_micros};
 use spacetime_client::{
-    ExternalGenerationJobEnqueueRecordInput, PuzzleAgentMessageRecord,
+    ExternalGenerationJobEnqueueRecordInput, ExternalGenerationJobRecord, PuzzleAgentMessageRecord,
     PuzzleAgentMessageSubmitRecordInput, PuzzleAgentSessionCreateRecordInput,
     PuzzleAgentSessionRecord, PuzzleAgentSuggestedActionRecord, PuzzleAnchorItemRecord,
     PuzzleAnchorPackRecord, PuzzleAudioAssetRecord, PuzzleBackgroundCompileTaskClaimRecordInput,
@@ -238,6 +239,32 @@ fn mark_puzzle_initial_generation_started_snapshot(
     session
 }
 
+fn map_puzzle_queue_job_status(
+    job: &ExternalGenerationJobRecord,
+    fallback_progress: u32,
+) -> ExternalGenerationJobStatusRecord {
+    let (status, phase_detail, default_progress) = match job.status.as_str() {
+        "completed" => (ExternalGenerationJobStatus::Completed, "生成已完成。", 100),
+        "running" => (ExternalGenerationJobStatus::Running, "正在生成。", 35),
+        "failed" => (ExternalGenerationJobStatus::Failed, "生成失败。", 0),
+        _ => (ExternalGenerationJobStatus::Queued, "排队中。", 8),
+    };
+
+    ExternalGenerationJobStatusRecord {
+        operation_id: job.job_id.clone(),
+        status,
+        phase_label: job.request_label.clone(),
+        phase_detail: phase_detail.to_string(),
+        progress: fallback_progress
+            .max(default_progress)
+            .min(100)
+            .try_into()
+            .unwrap_or(100),
+        error: job.last_error_message.clone(),
+        updated_at_micros: job.updated_at_micros,
+    }
+}
+
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub(crate) struct ExternalGenerationWriteLeaseGuard {
     pub(crate) job_id: Option<String>,
diff --git a/server-rs/crates/api-server/src/puzzle/handlers.rs b/server-rs/crates/api-server/src/puzzle/handlers.rs
index e5e24ddad..721dc729a 100644
--- a/server-rs/crates/api-server/src/puzzle/handlers.rs
+++ b/server-rs/crates/api-server/src/puzzle/handlers.rs
@@ -718,6 +718,7 @@ pub async fn execute_puzzle_agent_action(
                                 phase_detail: "首关草稿生成已在后台处理中。".to_string(),
                                 progress: session.progress_percent.max(10),
                                 error: None,
+                                queue_state: None,
                             },
                             session: map_puzzle_agent_session_response(session),
                         },
@@ -774,6 +775,7 @@ pub async fn execute_puzzle_agent_action(
                             },
                             progress: 100,
                             error: None,
+                            queue_state: None,
                         },
                         session: map_puzzle_agent_session_response(session),
                     },
@@ -861,7 +863,7 @@ pub async fn execute_puzzle_agent_action(
                 Some(&request_context),
                 PuzzleAgentActionResponse {
                     operation: PuzzleAgentOperationResponse {
-                        operation_id: job.job_id,
+                        operation_id: job.job_id.clone(),
                         operation_type: "compile_puzzle_draft".to_string(),
                         status: status.to_string(),
                         phase_label: "首关拼图草稿".to_string(),
@@ -871,7 +873,8 @@ pub async fn execute_puzzle_agent_action(
                             "首关草稿编译已进入后台队列。".to_string()
                         },
                         progress,
-                        error: job.last_error_message,
+                        error: job.last_error_message.clone(),
+                        queue_state: Some(map_puzzle_queue_job_status(&job, progress)),
                     },
                     session: map_puzzle_agent_session_response(session),
                 },
@@ -1005,6 +1008,7 @@ pub async fn execute_puzzle_agent_action(
                             phase_detail: "关卡图片生成已完成。".to_string(),
                             progress: 100,
                             error: None,
+                            queue_state: None,
                         },
                         session: map_puzzle_agent_session_response(session),
                     },
@@ -1071,13 +1075,14 @@ pub async fn execute_puzzle_agent_action(
                 Some(&request_context),
                 PuzzleAgentActionResponse {
                     operation: PuzzleAgentOperationResponse {
-                        operation_id: job.job_id,
+                        operation_id: job.job_id.clone(),
                         operation_type: "generate_puzzle_images".to_string(),
                         status: status.to_string(),
                         phase_label: "拼图图片生成".to_string(),
                         phase_detail: "关卡图片生成已进入后台队列。".to_string(),
                         progress,
-                        error: job.last_error_message,
+                        error: job.last_error_message.clone(),
+                        queue_state: Some(map_puzzle_queue_job_status(&job, progress)),
                     },
                     session: map_puzzle_agent_session_response(session),
                 },
@@ -1145,6 +1150,7 @@ pub async fn execute_puzzle_agent_action(
                             phase_detail: "拼图 UI 背景图生成已完成。".to_string(),
                             progress: 100,
                             error: None,
+                            queue_state: None,
                         },
                         session: map_puzzle_agent_session_response(session),
                     },
@@ -1211,13 +1217,14 @@ pub async fn execute_puzzle_agent_action(
                 Some(&request_context),
                 PuzzleAgentActionResponse {
                     operation: PuzzleAgentOperationResponse {
-                        operation_id: job.job_id,
+                        operation_id: job.job_id.clone(),
                         operation_type: "generate_puzzle_ui_background".to_string(),
                         status: status.to_string(),
                         phase_label: "UI 背景图生成".to_string(),
                         phase_detail: "拼图 UI 背景图生成已进入后台队列。".to_string(),
                         progress,
-                        error: job.last_error_message,
+                        error: job.last_error_message.clone(),
+                        queue_state: Some(map_puzzle_queue_job_status(&job, progress)),
                     },
                     session: map_puzzle_agent_session_response(session),
                 },
@@ -1390,6 +1397,7 @@ pub async fn execute_puzzle_agent_action(
                         phase_detail: "拼图作品已发布到广场。".to_string(),
                         progress: 100,
                         error: None,
+                        queue_state: None,
                     },
                     session: map_puzzle_agent_session_response(session),
                 },
@@ -1416,6 +1424,7 @@ pub async fn execute_puzzle_agent_action(
                 phase_detail: phase_detail.to_string(),
                 progress: 100,
                 error: None,
+                queue_state: None,
             },
             session: map_puzzle_agent_session_response(session),
         },
diff --git a/server-rs/crates/pingora-gateway/Cargo.toml b/server-rs/crates/pingora-gateway/Cargo.toml
new file mode 100644
index 000000000..1c159c717
--- /dev/null
+++ b/server-rs/crates/pingora-gateway/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "pingora-gateway"
+edition.workspace = true
+version.workspace = true
+license.workspace = true
+
+[dependencies]
+async-trait = { workspace = true }
+bytes = { workspace = true }
+httpdate = { workspace = true }
+mime_guess = { workspace = true }
+pingora = { workspace = true }
+pingora-http = { workspace = true }
+pingora-proxy = { workspace = true }
+shared-logging = { workspace = true }
+tokio = { workspace = true, features = ["fs", "io-util"] }
+tracing = { workspace = true }
+uuid = { workspace = true, features = ["v4"] }
+
+[dev-dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
diff --git a/server-rs/crates/pingora-gateway/src/main.rs b/server-rs/crates/pingora-gateway/src/main.rs
new file mode 100644
index 000000000..4978a84c4
--- /dev/null
+++ b/server-rs/crates/pingora-gateway/src/main.rs
@@ -0,0 +1,3950 @@
+use std::{
+    collections::HashMap,
+    env,
+    fs::OpenOptions,
+    io,
+    io::SeekFrom,
+    io::Write,
+    net::SocketAddr,
+    path::{Path, PathBuf},
+    sync::{Arc, Mutex},
+    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
+};
+
+use async_trait::async_trait;
+use bytes::Bytes;
+use httpdate::{fmt_http_date, parse_http_date};
+use pingora::{
+    ConnectTimedout, ConnectionClosed, Error, ErrorSource, HTTPStatus, ReadError, ReadTimedout,
+    Result as PingoraResult, WriteError, WriteTimedout,
+    listeners::tls::TlsSettings,
+    modules::http::{HttpModule, HttpModuleBuilder, HttpModules, Module},
+    prelude::HttpPeer,
+    protocols::http::compression::ResponseCompressionCtx,
+    server::{Server, configuration::Opt},
+};
+use pingora_http::{Method, RequestHeader, ResponseHeader};
+use pingora_proxy::{FailToProxy, ProxyHttp, Session, http_proxy_service};
+use shared_logging::{OtelConfig, init_tracing};
+use tokio::io::{AsyncReadExt, AsyncSeekExt};
+use tracing::{error, info, warn};
+use uuid::Uuid;
+
+const DEFAULT_LISTEN_ADDR: &str = "127.0.0.1:18081";
+const DEFAULT_API_UPSTREAM: &str = "127.0.0.1:8082";
+const DEFAULT_SPACETIME_UPSTREAM: &str = "127.0.0.1:3101";
+const DEFAULT_WEB_ROOT: &str = "/srv/genarrative/web";
+const DEFAULT_ACME_ROOT: &str = "/var/www/html";
+const DEFAULT_MAINTENANCE_FILE: &str = "/var/lib/genarrative/maintenance/enabled";
+const DEFAULT_MAX_API_BODY_BYTES: u64 = 64 * 1024 * 1024;
+const DEFAULT_GZIP_LEVEL: u32 = 5;
+const DEFAULT_GZIP_MIN_LENGTH_BYTES: u64 = 1024;
+const DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS: u64 = 3_000;
+const DEFAULT_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS: u64 = 60;
+const DEFAULT_UPSTREAM_API_READ_TIMEOUT_SECONDS: u64 = 3_600;
+const DEFAULT_UPSTREAM_LONG_READ_TIMEOUT_SECONDS: u64 = 3_600;
+const DEFAULT_UPSTREAM_WRITE_TIMEOUT_SECONDS: u64 = 3_600;
+const DEFAULT_HTML_CACHE_CONTROL: &str = "no-cache";
+const DEFAULT_ASSET_CACHE_CONTROL: &str = "public, max-age=31536000, immutable";
+const DEFAULT_STATIC_CACHE_CONTROL: &str = "no-cache";
+const DEFAULT_INSTANCE_COUNT: u32 = 1;
+const DEFAULT_LOG_FILTER: &str = "info,pingora=info,pingora_gateway=info";
+const SHADOW_PROBE_PATH: &str = "/__genarrative_pingora/healthz";
+const SHADOW_PROBE_HEADER: &str = "x-genarrative-pingora-probe";
+const PAYLOAD_TOO_LARGE_CONTEXT: &str = "genarrative_payload_too_large";
+const PROTECTION_STATE_TTL: Duration = Duration::from_secs(600);
+const PROTECTION_CLEANUP_INTERVAL: Duration = Duration::from_secs(60);
+
+#[derive(Clone, Debug)]
+struct GatewayConfig {
+    listen_addr: String,
+    tls_listen_addr: Option<String>,
+    tls_cert_file: Option<PathBuf>,
+    tls_key_file: Option<PathBuf>,
+    http_redirect_listen_addr: Option<String>,
+    http_redirect_target_scheme: String,
+    api_upstream: SocketAddr,
+    spacetime_upstream: SocketAddr,
+    gitea_hosts: Vec<String>,
+    gitea_upstream: Option<SocketAddr>,
+    web_root: PathBuf,
+    acme_root: PathBuf,
+    maintenance_file: PathBuf,
+    forwarded_proto: String,
+    max_api_body_bytes: u64,
+    gzip_enabled: bool,
+    gzip_level: u32,
+    gzip_min_length_bytes: u64,
+    compression: CompressionConfig,
+    static_cache: StaticCacheConfig,
+    upstream_timeouts: UpstreamTimeoutConfig,
+    shadow_probe_token: Option<String>,
+    trust_x_forwarded_for: bool,
+    instance_count: u32,
+    shared_protection_confirmed: bool,
+    protection: ProtectionConfig,
+    log_filter: String,
+    access_log_file: Option<PathBuf>,
+    otel_enabled: bool,
+}
+
+impl GatewayConfig {
+    fn from_env() -> io::Result<Self> {
+        let config = Self {
+            listen_addr: read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_LISTEN",
+                DEFAULT_LISTEN_ADDR,
+            ),
+            tls_listen_addr: read_optional_env("GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN"),
+            tls_cert_file: read_optional_env("GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE")
+                .map(PathBuf::from),
+            tls_key_file: read_optional_env("GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE")
+                .map(PathBuf::from),
+            http_redirect_listen_addr: read_optional_env(
+                "GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN",
+            ),
+            http_redirect_target_scheme: read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_TARGET_SCHEME",
+                "https",
+            ),
+            api_upstream: read_socket_addr_env(
+                "GENARRATIVE_PINGORA_GATEWAY_API_UPSTREAM",
+                DEFAULT_API_UPSTREAM,
+            )?,
+            spacetime_upstream: read_socket_addr_env(
+                "GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM",
+                DEFAULT_SPACETIME_UPSTREAM,
+            )?,
+            gitea_hosts: read_host_list_env("GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS")?,
+            gitea_upstream: read_optional_socket_addr_env(
+                "GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM",
+            )?,
+            web_root: PathBuf::from(read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT",
+                DEFAULT_WEB_ROOT,
+            )),
+            acme_root: PathBuf::from(read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT",
+                DEFAULT_ACME_ROOT,
+            )),
+            maintenance_file: PathBuf::from(read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE",
+                DEFAULT_MAINTENANCE_FILE,
+            )),
+            forwarded_proto: read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO",
+                "http",
+            ),
+            max_api_body_bytes: read_u64_env(
+                "GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES",
+                DEFAULT_MAX_API_BODY_BYTES,
+            )?,
+            gzip_enabled: read_bool_env("GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED", true),
+            gzip_level: read_u32_env("GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL", DEFAULT_GZIP_LEVEL)?,
+            gzip_min_length_bytes: read_u64_env(
+                "GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES",
+                DEFAULT_GZIP_MIN_LENGTH_BYTES,
+            )?,
+            compression: CompressionConfig::from_env()?,
+            static_cache: StaticCacheConfig::from_env(),
+            upstream_timeouts: UpstreamTimeoutConfig::from_env()?,
+            shadow_probe_token: read_optional_env("GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN"),
+            trust_x_forwarded_for: read_bool_env(
+                "GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR",
+                false,
+            ),
+            instance_count: read_u32_env(
+                "GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT",
+                DEFAULT_INSTANCE_COUNT,
+            )?,
+            shared_protection_confirmed: read_bool_env(
+                "GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED",
+                false,
+            ),
+            protection: ProtectionConfig::from_env()?,
+            log_filter: read_env_or_default("GENARRATIVE_PINGORA_GATEWAY_LOG", DEFAULT_LOG_FILTER),
+            access_log_file: read_optional_env("GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE")
+                .map(PathBuf::from),
+            otel_enabled: read_bool_env("GENARRATIVE_PINGORA_GATEWAY_OTEL_ENABLED", false),
+        };
+        config.validate()?;
+        Ok(config)
+    }
+
+    fn validate(&self) -> io::Result<()> {
+        let listen_addr =
+            parse_socket_addr_config("GENARRATIVE_PINGORA_GATEWAY_LISTEN", &self.listen_addr)?;
+
+        if listen_addr == self.api_upstream || listen_addr == self.spacetime_upstream {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_LISTEN 不能与上游地址相同",
+            ));
+        }
+        self.validate_gitea_config(listen_addr, None, None)?;
+
+        let tls_listen_addr = if let Some(tls_listen_addr) = &self.tls_listen_addr {
+            let tls_listen_addr = parse_socket_addr_config(
+                "GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN",
+                tls_listen_addr,
+            )?;
+            validate_distinct_listen_addr(
+                "GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN",
+                tls_listen_addr,
+                listen_addr,
+                self.api_upstream,
+                self.spacetime_upstream,
+                self.gitea_upstream,
+            )?;
+            self.validate_gitea_config(listen_addr, Some(tls_listen_addr), None)?;
+            validate_tls_file_config(&self.tls_cert_file, &self.tls_key_file)?;
+            Some(tls_listen_addr)
+        } else if self.tls_cert_file.is_some() || self.tls_key_file.is_some() {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "配置 TLS_CERT_FILE / TLS_KEY_FILE 时必须同时设置 GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN",
+            ));
+        } else {
+            None
+        };
+
+        if let Some(http_redirect_listen_addr) = &self.http_redirect_listen_addr {
+            let Some(tls_listen_addr) = tls_listen_addr else {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "配置 GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN 时必须同时设置 TLS_LISTEN / TLS_CERT_FILE / TLS_KEY_FILE",
+                ));
+            };
+            let http_redirect_listen_addr = parse_socket_addr_config(
+                "GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN",
+                http_redirect_listen_addr,
+            )?;
+            validate_distinct_listen_addr(
+                "GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN",
+                http_redirect_listen_addr,
+                listen_addr,
+                self.api_upstream,
+                self.spacetime_upstream,
+                self.gitea_upstream,
+            )?;
+            if http_redirect_listen_addr == tls_listen_addr {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN 不能与 TLS_LISTEN 相同",
+                ));
+            }
+            self.validate_gitea_config(
+                listen_addr,
+                Some(tls_listen_addr),
+                Some(http_redirect_listen_addr),
+            )?;
+            validate_redirect_target_scheme(&self.http_redirect_target_scheme)?;
+        }
+
+        if self.max_api_body_bytes == 0 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES 必须大于 0",
+            ));
+        }
+
+        if self.gzip_level > 9 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL 必须在 0..=9 之间",
+            ));
+        }
+        if self.gzip_min_length_bytes == 0 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES 必须大于 0",
+            ));
+        }
+        self.compression.validate()?;
+        self.static_cache.validate()?;
+        self.upstream_timeouts.validate()?;
+
+        if let Some(token) = self.shadow_probe_token.as_deref() {
+            validate_shadow_probe_token(token)?;
+        }
+
+        if self.trust_x_forwarded_for
+            && !read_bool_env(
+                "GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED",
+                false,
+            )
+        {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "启用 GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true 前必须同时设置 GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true，确认前置代理会清洗 X-Forwarded-For",
+            ));
+        }
+
+        if let Some(access_log_file) = &self.access_log_file {
+            validate_access_log_file(access_log_file)?;
+        }
+
+        self.protection.validate()?;
+        validate_instance_protection_boundary(
+            self.instance_count,
+            self.protection.enabled,
+            self.shared_protection_confirmed,
+        )?;
+        Ok(())
+    }
+
+    fn validate_gitea_config(
+        &self,
+        listen_addr: SocketAddr,
+        tls_listen_addr: Option<SocketAddr>,
+        http_redirect_listen_addr: Option<SocketAddr>,
+    ) -> io::Result<()> {
+        for host in &self.gitea_hosts {
+            validate_configured_gateway_host("GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS", host)?;
+        }
+
+        match (self.gitea_hosts.is_empty(), self.gitea_upstream) {
+            (true, Some(_)) => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "配置 GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM 时必须同时设置 GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS",
+                ));
+            }
+            (false, None) => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "配置 GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS 时必须同时设置 GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM",
+                ));
+            }
+            _ => {}
+        }
+
+        let Some(gitea_upstream) = self.gitea_upstream else {
+            return Ok(());
+        };
+        if gitea_upstream == self.api_upstream || gitea_upstream == self.spacetime_upstream {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM 不能与 API 或 SpacetimeDB 上游地址相同",
+            ));
+        }
+        if gitea_upstream == listen_addr
+            || Some(gitea_upstream) == tls_listen_addr
+            || Some(gitea_upstream) == http_redirect_listen_addr
+        {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM 不能与 Pingora 监听地址相同",
+            ));
+        }
+        Ok(())
+    }
+
+    fn matches_gitea_host(&self, host: Option<&str>) -> bool {
+        let Some(host) = host.and_then(normalize_gateway_host) else {
+            return false;
+        };
+        self.gitea_hosts.iter().any(|candidate| candidate == &host)
+    }
+}
+
+#[derive(Clone, Debug)]
+struct CompressionConfig {
+    gzip: bool,
+    raw_algorithms: String,
+}
+
+impl CompressionConfig {
+    fn from_env() -> io::Result<Self> {
+        let raw_algorithms =
+            read_env_or_default("GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS", "gzip");
+        Self::parse(raw_algorithms)
+    }
+
+    fn parse(raw_algorithms: String) -> io::Result<Self> {
+        let mut gzip = false;
+
+        for algorithm in raw_algorithms
+            .split(',')
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        {
+            match algorithm.to_ascii_lowercase().as_str() {
+                "gzip" => gzip = true,
+                _ => {
+                    return Err(io::Error::new(
+                        io::ErrorKind::InvalidInput,
+                        format!(
+                            "GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS 当前只支持 gzip，收到 {algorithm:?}"
+                        ),
+                    ));
+                }
+            }
+        }
+
+        Ok(Self {
+            gzip,
+            raw_algorithms,
+        })
+    }
+
+    fn validate(&self) -> io::Result<()> {
+        if !self.gzip && !self.raw_algorithms.trim().is_empty() {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS 未启用任何受支持算法",
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug)]
+struct UpstreamTimeoutConfig {
+    connect_timeout_ms: u64,
+    default_read_timeout_seconds: u64,
+    api_read_timeout_seconds: u64,
+    long_read_timeout_seconds: u64,
+    write_timeout_seconds: u64,
+}
+
+impl UpstreamTimeoutConfig {
+    fn from_env() -> io::Result<Self> {
+        Ok(Self {
+            connect_timeout_ms: read_u64_env(
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_CONNECT_TIMEOUT_MS",
+                DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS,
+            )?,
+            default_read_timeout_seconds: read_u64_env(
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS",
+                DEFAULT_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS,
+            )?,
+            api_read_timeout_seconds: read_u64_env(
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS",
+                DEFAULT_UPSTREAM_API_READ_TIMEOUT_SECONDS,
+            )?,
+            long_read_timeout_seconds: read_u64_env(
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_LONG_READ_TIMEOUT_SECONDS",
+                DEFAULT_UPSTREAM_LONG_READ_TIMEOUT_SECONDS,
+            )?,
+            write_timeout_seconds: read_u64_env(
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_WRITE_TIMEOUT_SECONDS",
+                DEFAULT_UPSTREAM_WRITE_TIMEOUT_SECONDS,
+            )?,
+        })
+    }
+
+    fn validate(&self) -> io::Result<()> {
+        for (name, value) in [
+            (
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_CONNECT_TIMEOUT_MS",
+                self.connect_timeout_ms,
+            ),
+            (
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS",
+                self.default_read_timeout_seconds,
+            ),
+            (
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS",
+                self.api_read_timeout_seconds,
+            ),
+            (
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_LONG_READ_TIMEOUT_SECONDS",
+                self.long_read_timeout_seconds,
+            ),
+            (
+                "GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_WRITE_TIMEOUT_SECONDS",
+                self.write_timeout_seconds,
+            ),
+        ] {
+            if value == 0 {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    format!("{name} 必须大于 0"),
+                ));
+            }
+        }
+
+        Ok(())
+    }
+
+    fn read_timeout_for_route(&self, _route: &RouteDecision, path: &str) -> Duration {
+        let seconds = if is_long_upstream_route(path) {
+            self.long_read_timeout_seconds
+        } else if is_generic_api_proxy_path(path) {
+            self.api_read_timeout_seconds
+        } else {
+            self.default_read_timeout_seconds
+        };
+        Duration::from_secs(seconds)
+    }
+
+    fn connect_timeout(&self) -> Duration {
+        Duration::from_millis(self.connect_timeout_ms)
+    }
+
+    fn write_timeout(&self) -> Duration {
+        Duration::from_secs(self.write_timeout_seconds)
+    }
+}
+
+#[derive(Clone, Debug)]
+struct StaticCacheConfig {
+    html_cache_control: String,
+    asset_cache_control: String,
+    static_cache_control: String,
+}
+
+impl StaticCacheConfig {
+    fn from_env() -> Self {
+        Self {
+            html_cache_control: read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL",
+                DEFAULT_HTML_CACHE_CONTROL,
+            ),
+            asset_cache_control: read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL",
+                DEFAULT_ASSET_CACHE_CONTROL,
+            ),
+            static_cache_control: read_env_or_default(
+                "GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL",
+                DEFAULT_STATIC_CACHE_CONTROL,
+            ),
+        }
+    }
+
+    fn validate(&self) -> io::Result<()> {
+        for (name, value) in [
+            (
+                "GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL",
+                self.html_cache_control.as_str(),
+            ),
+            (
+                "GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL",
+                self.asset_cache_control.as_str(),
+            ),
+            (
+                "GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL",
+                self.static_cache_control.as_str(),
+            ),
+        ] {
+            if value.contains('\n') || value.contains('\r') || value.contains('\0') {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    format!("{name} 不能包含换行或 NUL 字符"),
+                ));
+            }
+        }
+
+        Ok(())
+    }
+}
+
+#[derive(Clone)]
+struct GenarrativeGateway {
+    config: Arc<GatewayConfig>,
+    protection: Arc<GatewayProtection>,
+    mode: GatewayMode,
+}
+
+#[derive(Debug)]
+struct RequestContext {
+    request_id: String,
+    route: RouteDecision,
+    request_body_bytes_seen: u64,
+    protection_class: Option<ProtectionClass>,
+    protection_client: String,
+    protection_key: Option<ProtectionKey>,
+    started_at: Instant,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum GatewayMode {
+    Proxy,
+    HttpRedirect,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum CompressionAlgorithm {
+    Gzip,
+}
+
+impl CompressionAlgorithm {
+    fn header_value(self) -> &'static str {
+        match self {
+            Self::Gzip => "gzip",
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+struct CompressionRequestConfig {
+    enabled: bool,
+    gzip: bool,
+    min_length_bytes: u64,
+    gzip_level: u32,
+}
+
+struct GatewayResponseCompressionBuilder {
+    config: CompressionRequestConfig,
+}
+
+struct GatewayResponseCompression {
+    config: CompressionRequestConfig,
+    inner: ResponseCompressionCtx,
+}
+
+impl HttpModuleBuilder for GatewayResponseCompressionBuilder {
+    fn init(&self) -> Module {
+        Box::new(GatewayResponseCompression {
+            config: self.config,
+            inner: ResponseCompressionCtx::new(self.config.gzip_level, false, false),
+        })
+    }
+
+    fn order(&self) -> i16 {
+        i16::MIN / 2
+    }
+}
+
+#[async_trait]
+impl HttpModule for GatewayResponseCompression {
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+
+    fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
+        self
+    }
+
+    async fn request_header_filter(&mut self, req: &mut RequestHeader) -> PingoraResult<()> {
+        normalize_accept_encoding_for_gateway_compression(req, self.config)?;
+        self.inner.request_filter(req);
+        Ok(())
+    }
+
+    async fn response_header_filter(
+        &mut self,
+        resp: &mut ResponseHeader,
+        _end_of_stream: bool,
+    ) -> PingoraResult<()> {
+        if !should_allow_gateway_compression_for_response(resp, self.config.min_length_bytes) {
+            self.inner.adjust_level(0);
+        }
+        self.inner.response_header_filter(resp, _end_of_stream);
+        Ok(())
+    }
+
+    fn response_body_filter(
+        &mut self,
+        body: &mut Option<Bytes>,
+        end_of_stream: bool,
+    ) -> PingoraResult<()> {
+        if !self.inner.is_enabled() {
+            return Ok(());
+        }
+        if let Some(compressed) = self
+            .inner
+            .response_body_filter(body.as_ref(), end_of_stream)
+        {
+            *body = Some(compressed);
+        }
+        Ok(())
+    }
+
+    fn response_done_filter(&mut self) -> PingoraResult<Option<Bytes>> {
+        if !self.inner.is_enabled() {
+            return Ok(None);
+        }
+        Ok(self.inner.response_body_filter(None, true))
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ProxyTarget {
+    Api,
+    Spacetime,
+    Gitea,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+enum ProtectionClass {
+    AdminApi,
+    GalleryList,
+    GalleryDetail,
+    Api,
+    Spacetime,
+}
+
+impl ProtectionClass {
+    fn as_str(self) -> &'static str {
+        match self {
+            ProtectionClass::AdminApi => "admin_api",
+            ProtectionClass::GalleryList => "gallery_list",
+            ProtectionClass::GalleryDetail => "gallery_detail",
+            ProtectionClass::Api => "api",
+            ProtectionClass::Spacetime => "spacetime",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum RejectReason {
+    Concurrent,
+    Rate,
+}
+
+impl RejectReason {
+    fn code(self) -> &'static str {
+        match self {
+            RejectReason::Concurrent => "GATEWAY_CONCURRENCY_LIMITED",
+            RejectReason::Rate => "GATEWAY_RATE_LIMITED",
+        }
+    }
+
+    fn message(self) -> &'static str {
+        match self {
+            RejectReason::Concurrent => "服务繁忙，请稍后重试",
+            RejectReason::Rate => "请求过于频繁，请稍后重试",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug)]
+struct ProtectionClassConfig {
+    max_concurrent: u32,
+    rate_per_second: u32,
+    burst: u32,
+}
+
+#[derive(Clone, Debug)]
+struct ProtectionConfig {
+    enabled: bool,
+    admin_api: ProtectionClassConfig,
+    gallery_list: ProtectionClassConfig,
+    gallery_detail: ProtectionClassConfig,
+    api: ProtectionClassConfig,
+    spacetime: ProtectionClassConfig,
+}
+
+impl ProtectionConfig {
+    fn from_env() -> io::Result<Self> {
+        Ok(Self {
+            enabled: read_bool_env("GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED", true),
+            admin_api: ProtectionClassConfig::from_env(
+                "GENARRATIVE_PINGORA_GATEWAY_ADMIN_API",
+                64,
+                30,
+                16,
+            )?,
+            gallery_list: ProtectionClassConfig::from_env(
+                "GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST",
+                320,
+                5000,
+                4096,
+            )?,
+            gallery_detail: ProtectionClassConfig::from_env(
+                "GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL",
+                32,
+                300,
+                32,
+            )?,
+            api: ProtectionClassConfig::from_env("GENARRATIVE_PINGORA_GATEWAY_API", 64, 300, 64)?,
+            spacetime: ProtectionClassConfig::from_env(
+                "GENARRATIVE_PINGORA_GATEWAY_SPACETIME",
+                256,
+                1000,
+                256,
+            )?,
+        })
+    }
+
+    fn class_config(&self, class: ProtectionClass) -> ProtectionClassConfig {
+        match class {
+            ProtectionClass::AdminApi => self.admin_api,
+            ProtectionClass::GalleryList => self.gallery_list,
+            ProtectionClass::GalleryDetail => self.gallery_detail,
+            ProtectionClass::Api => self.api,
+            ProtectionClass::Spacetime => self.spacetime,
+        }
+    }
+
+    fn validate(&self) -> io::Result<()> {
+        for (name, config) in [
+            ("admin_api", self.admin_api),
+            ("gallery_list", self.gallery_list),
+            ("gallery_detail", self.gallery_detail),
+            ("api", self.api),
+            ("spacetime", self.spacetime),
+        ] {
+            config.validate(name)?;
+        }
+        Ok(())
+    }
+}
+
+impl ProtectionClassConfig {
+    fn from_env(
+        prefix: &str,
+        max_concurrent: u32,
+        rate_per_second: u32,
+        burst: u32,
+    ) -> io::Result<Self> {
+        Ok(Self {
+            max_concurrent: read_u32_env(&format!("{prefix}_MAX_CONCURRENT"), max_concurrent)?,
+            rate_per_second: read_u32_env(&format!("{prefix}_RATE_PER_SECOND"), rate_per_second)?,
+            burst: read_u32_env(&format!("{prefix}_BURST"), burst)?,
+        })
+    }
+
+    fn is_disabled(&self) -> bool {
+        self.max_concurrent == 0 && self.rate_per_second == 0
+    }
+
+    fn bucket_capacity(&self) -> u32 {
+        self.rate_per_second.saturating_add(self.burst).max(1)
+    }
+
+    fn validate(&self, name: &str) -> io::Result<()> {
+        if self.burst > 0 && self.rate_per_second == 0 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                format!(
+                    "{name} 配置了 burst 但 RATE_PER_SECOND=0；若要关闭 RPS，请同时把 BURST 设为 0"
+                ),
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum StaticRoot {
+    Web,
+    Acme,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum StaticMode {
+    Exact,
+    SpaFallback,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+enum LocalResponse {
+    RedirectPermanent { location: &'static str },
+    HttpToHttpsRedirect,
+    ShadowProbe,
+    Static { root: StaticRoot, mode: StaticMode },
+    NotFound,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+enum RouteDecision {
+    Proxy {
+        target: ProxyTarget,
+        body_limit: Option<u64>,
+    },
+    Local(LocalResponse),
+}
+
+impl RouteDecision {
+    fn applies_maintenance_gate(&self) -> bool {
+        matches!(
+            self,
+            RouteDecision::Proxy {
+                target: ProxyTarget::Api | ProxyTarget::Spacetime,
+                ..
+            } | RouteDecision::Local(LocalResponse::Static {
+                root: StaticRoot::Web,
+                ..
+            })
+        )
+    }
+
+    fn is_api_like(&self) -> bool {
+        matches!(
+            self,
+            RouteDecision::Proxy {
+                target: ProxyTarget::Api,
+                ..
+            }
+        )
+    }
+
+    fn proxy_target(&self) -> Option<ProxyTarget> {
+        match self {
+            RouteDecision::Proxy { target, .. } => Some(*target),
+            RouteDecision::Local(_) => None,
+        }
+    }
+
+    fn body_limit(&self) -> Option<u64> {
+        match self {
+            RouteDecision::Proxy { body_limit, .. } => *body_limit,
+            RouteDecision::Local(_) => None,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+struct ProtectionKey {
+    class: ProtectionClass,
+    client: String,
+}
+
+#[derive(Debug)]
+struct ClientProtectionState {
+    in_flight: u32,
+    tokens: f64,
+    last_refill: Instant,
+    last_seen: Instant,
+}
+
+#[derive(Debug)]
+struct ProtectionState {
+    clients: HashMap<ProtectionKey, ClientProtectionState>,
+    last_cleanup: Instant,
+}
+
+struct GatewayProtection {
+    config: ProtectionConfig,
+    state: Mutex<ProtectionState>,
+}
+
+impl GatewayProtection {
+    fn new(config: ProtectionConfig) -> Self {
+        Self {
+            config,
+            state: Mutex::new(ProtectionState {
+                clients: HashMap::new(),
+                last_cleanup: Instant::now(),
+            }),
+        }
+    }
+
+    fn try_acquire(
+        self: &Arc<Self>,
+        class: ProtectionClass,
+        client: String,
+    ) -> Result<Option<ProtectionKey>, RejectReason> {
+        if !self.config.enabled {
+            return Ok(None);
+        }
+
+        let class_config = self.config.class_config(class);
+        if class_config.is_disabled() {
+            return Ok(None);
+        }
+
+        let now = Instant::now();
+        let key = ProtectionKey { class, client };
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        cleanup_protection_state(&mut state, now);
+
+        let entry = state
+            .clients
+            .entry(key.clone())
+            .or_insert_with(|| ClientProtectionState {
+                in_flight: 0,
+                tokens: class_config.bucket_capacity() as f64,
+                last_refill: now,
+                last_seen: now,
+            });
+        refill_tokens(entry, class_config, now);
+        entry.last_seen = now;
+
+        if class_config.max_concurrent > 0 && entry.in_flight >= class_config.max_concurrent {
+            return Err(RejectReason::Concurrent);
+        }
+
+        if class_config.rate_per_second > 0 && entry.tokens < 1.0 {
+            return Err(RejectReason::Rate);
+        }
+
+        if class_config.rate_per_second > 0 {
+            entry.tokens -= 1.0;
+        }
+        entry.in_flight = entry.in_flight.saturating_add(1);
+
+        Ok(Some(key))
+    }
+
+    fn release(&self, key: &ProtectionKey) {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        if let Some(entry) = state.clients.get_mut(key) {
+            entry.in_flight = entry.in_flight.saturating_sub(1);
+            entry.last_seen = Instant::now();
+        }
+    }
+}
+
+fn refill_tokens(
+    entry: &mut ClientProtectionState,
+    class_config: ProtectionClassConfig,
+    now: Instant,
+) {
+    if class_config.rate_per_second == 0 {
+        entry.last_refill = now;
+        return;
+    }
+
+    let elapsed = now.saturating_duration_since(entry.last_refill);
+    let refill = elapsed.as_secs_f64() * class_config.rate_per_second as f64;
+    if refill > 0.0 {
+        entry.tokens = (entry.tokens + refill).min(class_config.bucket_capacity() as f64);
+        entry.last_refill = now;
+    }
+}
+
+fn cleanup_protection_state(state: &mut ProtectionState, now: Instant) {
+    if now.saturating_duration_since(state.last_cleanup) < PROTECTION_CLEANUP_INTERVAL {
+        return;
+    }
+
+    state.clients.retain(|_, entry| {
+        entry.in_flight > 0
+            || now.saturating_duration_since(entry.last_seen) <= PROTECTION_STATE_TTL
+    });
+    state.last_cleanup = now;
+}
+
+fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    let config = Arc::new(GatewayConfig::from_env()?);
+    init_tracing(
+        &config.log_filter,
+        OtelConfig {
+            enabled: config.otel_enabled,
+        },
+    )?;
+
+    info!(
+        listen = %config.listen_addr,
+        tls_listen = ?config.tls_listen_addr,
+        http_redirect_listen = ?config.http_redirect_listen_addr,
+        api_upstream = %config.api_upstream,
+        spacetime_upstream = %config.spacetime_upstream,
+        gitea_hosts = ?config.gitea_hosts,
+        gitea_upstream = ?config.gitea_upstream,
+        web_root = %config.web_root.display(),
+        "Pingora shadow gateway 启动"
+    );
+
+    let opt = Opt::parse_args();
+    let mut server = Server::new(Some(opt))?;
+    server.bootstrap();
+
+    let protection = Arc::new(GatewayProtection::new(config.protection.clone()));
+    let gateway = GenarrativeGateway {
+        config: config.clone(),
+        protection: protection.clone(),
+        mode: GatewayMode::Proxy,
+    };
+    let listen_addr = gateway.config.listen_addr.clone();
+    let mut proxy = http_proxy_service(&server.configuration, gateway);
+    proxy.add_tcp(&listen_addr);
+    if let Some(tls_listen_addr) = config.tls_listen_addr.as_deref() {
+        let cert_path = config
+            .tls_cert_file
+            .as_deref()
+            .expect("TLS cert file validated")
+            .to_string_lossy()
+            .into_owned();
+        let key_path = config
+            .tls_key_file
+            .as_deref()
+            .expect("TLS key file validated")
+            .to_string_lossy()
+            .into_owned();
+        let mut tls_settings = TlsSettings::intermediate(&cert_path, &key_path)?;
+        tls_settings.enable_h2();
+        proxy.add_tls_with_settings(tls_listen_addr, None, tls_settings);
+    }
+    server.add_service(proxy);
+
+    if let Some(http_redirect_listen_addr) = config.http_redirect_listen_addr.clone() {
+        let redirect_gateway = GenarrativeGateway {
+            config,
+            protection,
+            mode: GatewayMode::HttpRedirect,
+        };
+        let mut redirect_service = http_proxy_service(&server.configuration, redirect_gateway);
+        redirect_service.add_tcp(&http_redirect_listen_addr);
+        server.add_service(redirect_service);
+    }
+
+    server.run_forever();
+}
+
+#[async_trait]
+impl ProxyHttp for GenarrativeGateway {
+    type CTX = RequestContext;
+
+    fn init_downstream_modules(&self, modules: &mut HttpModules) {
+        let gzip_level = if self.config.gzip_enabled {
+            self.config.gzip_level
+        } else {
+            0
+        };
+        modules.add_module(Box::new(GatewayResponseCompressionBuilder {
+            config: CompressionRequestConfig {
+                enabled: gzip_level > 0,
+                gzip: self.config.compression.gzip,
+                min_length_bytes: self.config.gzip_min_length_bytes,
+                gzip_level,
+            },
+        }));
+    }
+
+    fn new_ctx(&self) -> Self::CTX {
+        RequestContext {
+            request_id: Uuid::new_v4().to_string(),
+            route: RouteDecision::Local(LocalResponse::NotFound),
+            request_body_bytes_seen: 0,
+            protection_class: None,
+            protection_client: String::new(),
+            protection_key: None,
+            started_at: Instant::now(),
+        }
+    }
+
+    async fn request_filter(
+        &self,
+        session: &mut Session,
+        ctx: &mut Self::CTX,
+    ) -> PingoraResult<bool>
+    where
+        Self::CTX: Send + Sync,
+    {
+        let path = session.req_header().uri.path();
+        let host = host_or_authority(session);
+        ctx.route = self.classify_request(host.as_deref(), path);
+        apply_configured_body_limit(&mut ctx.route, self.config.max_api_body_bytes);
+        ctx.request_id = resolve_request_id(session);
+
+        if self.is_maintenance_enabled() && ctx.route.applies_maintenance_gate() {
+            respond_maintenance(session, ctx.route.is_api_like(), &self.config.web_root).await?;
+            return Ok(true);
+        }
+
+        if let RouteDecision::Proxy { body_limit, .. } = ctx.route
+            && let Some(limit) = body_limit
+            && let Some(content_length) = content_length(session)
+            && content_length > limit
+        {
+            respond_json(session, 413, payload_too_large_body()).await?;
+            return Ok(true);
+        }
+
+        if let Some(protection_class) = protection_class_for_route(&ctx.route, path) {
+            let protection_client =
+                protection_client_id(session, self.config.trust_x_forwarded_for);
+            match self
+                .protection
+                .try_acquire(protection_class, protection_client.clone())
+            {
+                Ok(key) => {
+                    ctx.protection_class = Some(protection_class);
+                    ctx.protection_client = protection_client;
+                    ctx.protection_key = key;
+                }
+                Err(reason) => {
+                    ctx.protection_class = Some(protection_class);
+                    ctx.protection_client = protection_client;
+                    respond_too_many_requests(session, reason).await?;
+                    return Ok(true);
+                }
+            }
+        }
+
+        match &ctx.route {
+            RouteDecision::Proxy { .. } => Ok(false),
+            RouteDecision::Local(LocalResponse::RedirectPermanent { location }) => {
+                respond_redirect(session, location).await?;
+                Ok(true)
+            }
+            RouteDecision::Local(LocalResponse::HttpToHttpsRedirect) => {
+                respond_http_to_https_redirect(
+                    session,
+                    self.config.http_redirect_target_scheme.as_str(),
+                )
+                .await?;
+                Ok(true)
+            }
+            RouteDecision::Local(LocalResponse::ShadowProbe) => {
+                if !self.is_shadow_probe_authorized(session) {
+                    respond_not_found(session).await?;
+                    return Ok(true);
+                }
+
+                respond_shadow_probe(session, self.is_maintenance_enabled()).await?;
+                Ok(true)
+            }
+            RouteDecision::Local(LocalResponse::Static { root, mode }) => {
+                let root_path = match root {
+                    StaticRoot::Web => &self.config.web_root,
+                    StaticRoot::Acme => &self.config.acme_root,
+                };
+                serve_static(session, root_path, *root, *mode, &self.config.static_cache).await?;
+                Ok(true)
+            }
+            RouteDecision::Local(LocalResponse::NotFound) => {
+                respond_not_found(session).await?;
+                Ok(true)
+            }
+        }
+    }
+
+    async fn request_body_filter(
+        &self,
+        session: &mut Session,
+        body: &mut Option<Bytes>,
+        _end_of_stream: bool,
+        ctx: &mut Self::CTX,
+    ) -> PingoraResult<()>
+    where
+        Self::CTX: Send + Sync,
+    {
+        let Some(limit) = ctx.route.body_limit() else {
+            return Ok(());
+        };
+
+        if let Some(body) = body.as_ref() {
+            ctx.request_body_bytes_seen = ctx
+                .request_body_bytes_seen
+                .saturating_add(body.len() as u64);
+        }
+
+        if ctx.request_body_bytes_seen > limit {
+            respond_json(session, 413, payload_too_large_body()).await?;
+            return Error::e_explain(HTTPStatus(413), PAYLOAD_TOO_LARGE_CONTEXT);
+        }
+
+        Ok(())
+    }
+
+    async fn upstream_peer(
+        &self,
+        _session: &mut Session,
+        ctx: &mut Self::CTX,
+    ) -> PingoraResult<Box<HttpPeer>> {
+        let upstream = match ctx.route.proxy_target().unwrap_or(ProxyTarget::Api) {
+            ProxyTarget::Api => self.config.api_upstream,
+            ProxyTarget::Spacetime => self.config.spacetime_upstream,
+            ProxyTarget::Gitea => self
+                .config
+                .gitea_upstream
+                .expect("Gitea route requires configured upstream"),
+        };
+
+        let mut peer = HttpPeer::new(upstream, false, String::new());
+        peer.options.connection_timeout = Some(self.config.upstream_timeouts.connect_timeout());
+        peer.options.read_timeout = Some(
+            self.config
+                .upstream_timeouts
+                .read_timeout_for_route(&ctx.route, _session.req_header().uri.path()),
+        );
+        peer.options.write_timeout = Some(self.config.upstream_timeouts.write_timeout());
+
+        Ok(Box::new(peer))
+    }
+
+    async fn upstream_request_filter(
+        &self,
+        session: &mut Session,
+        upstream_request: &mut pingora_http::RequestHeader,
+        ctx: &mut Self::CTX,
+    ) -> PingoraResult<()>
+    where
+        Self::CTX: Send + Sync,
+    {
+        upstream_request.insert_header("X-Request-Id", ctx.request_id.as_str())?;
+        upstream_request
+            .insert_header("X-Forwarded-Proto", self.config.forwarded_proto.as_str())?;
+
+        if let Some(host) = host_or_authority(session) {
+            upstream_request.insert_header("Host", host.clone())?;
+            upstream_request.insert_header("X-Forwarded-Host", host)?;
+        }
+
+        if let Some(client_ip) = client_ip(session) {
+            upstream_request.insert_header("X-Real-IP", client_ip.as_str())?;
+            let forwarded_for = append_forwarded_for(session, &client_ip);
+            upstream_request.insert_header("X-Forwarded-For", forwarded_for.as_str())?;
+        }
+
+        // 中文注释：SpacetimeDB 订阅走 WebSocket Upgrade；普通 API 连接头保持干净，贴近当前 Nginx 模板。
+        if ctx.route.proxy_target() == Some(ProxyTarget::Spacetime) && is_upgrade_request(session) {
+            upstream_request.insert_header("Connection", "Upgrade")?;
+        } else {
+            upstream_request.remove_header("connection");
+        }
+
+        Ok(())
+    }
+
+    async fn response_filter(
+        &self,
+        _session: &mut Session,
+        upstream_response: &mut ResponseHeader,
+        ctx: &mut Self::CTX,
+    ) -> PingoraResult<()>
+    where
+        Self::CTX: Send + Sync,
+    {
+        upstream_response.insert_header("X-Genarrative-Gateway", "pingora-shadow")?;
+        if should_disable_accel_buffering(&ctx.route) {
+            upstream_response.insert_header("X-Accel-Buffering", "no")?;
+        }
+        Ok(())
+    }
+
+    async fn logging(
+        &self,
+        session: &mut Session,
+        error: Option<&pingora::Error>,
+        ctx: &mut Self::CTX,
+    ) where
+        Self::CTX: Send + Sync,
+    {
+        let status = session
+            .response_written()
+            .map_or(0, |response| response.status.as_u16());
+        let elapsed_ms = ctx.started_at.elapsed().as_millis();
+        let method = session.req_header().method.as_str();
+        let path = session.req_header().uri.path();
+        let uri = session.req_header().uri.to_string();
+        let host = header_value(session, "host").unwrap_or_default();
+        let client_ip = client_ip(session).unwrap_or_default();
+        let content_length = content_length(session);
+        let protection_class = ctx.protection_class.map(|class| class.as_str());
+        let protection_client = ctx.protection_client.as_str();
+        let proxy_target = ctx
+            .route
+            .proxy_target()
+            .map(|target| format!("{target:?}"))
+            .unwrap_or_else(|| "Local".to_string());
+        let upstream = match ctx.route.proxy_target() {
+            Some(ProxyTarget::Api) => self.config.api_upstream.to_string(),
+            Some(ProxyTarget::Spacetime) => self.config.spacetime_upstream.to_string(),
+            Some(ProxyTarget::Gitea) => self
+                .config
+                .gitea_upstream
+                .map(|upstream| upstream.to_string())
+                .unwrap_or_default(),
+            None => String::new(),
+        };
+        let route = format!("{:?}", ctx.route);
+        if let Some(key) = ctx.protection_key.take() {
+            self.protection.release(&key);
+        }
+
+        write_access_log(
+            self.config.access_log_file.as_deref(),
+            AccessLogRecord {
+                request_id: &ctx.request_id,
+                method,
+                path,
+                uri: &uri,
+                host: &host,
+                client_ip: &client_ip,
+                status,
+                route: &route,
+                proxy_target: &proxy_target,
+                upstream: &upstream,
+                content_length,
+                body_bytes_seen: ctx.request_body_bytes_seen,
+                protection_class,
+                protection_client,
+                elapsed_ms,
+                error: error.map(ToString::to_string),
+            },
+        );
+
+        if let Some(error) = error {
+            if is_payload_too_large_error(error) {
+                warn!(
+                    request_id = %ctx.request_id,
+                    method,
+                    path,
+                    uri = %uri,
+                    host = %host,
+                    client_ip = %client_ip,
+                    status,
+                    route = %route,
+                    proxy_target = %proxy_target,
+                    upstream = %upstream,
+                    content_length = ?content_length,
+                    body_bytes_seen = ctx.request_body_bytes_seen,
+                    protection_class = ?protection_class,
+                    protection_client,
+                    elapsed_ms,
+                    %error,
+                    "Pingora gateway request rejected"
+                );
+            } else {
+                error!(
+                    request_id = %ctx.request_id,
+                    method,
+                    path,
+                    uri = %uri,
+                    host = %host,
+                    client_ip = %client_ip,
+                    status,
+                    route = %route,
+                    proxy_target = %proxy_target,
+                    upstream = %upstream,
+                    content_length = ?content_length,
+                    body_bytes_seen = ctx.request_body_bytes_seen,
+                    protection_class = ?protection_class,
+                    protection_client,
+                    elapsed_ms,
+                    %error,
+                    "Pingora gateway request failed"
+                );
+            }
+        } else {
+            info!(
+                request_id = %ctx.request_id,
+                method,
+                path,
+                uri = %uri,
+                host = %host,
+                client_ip = %client_ip,
+                status,
+                route = %route,
+                proxy_target = %proxy_target,
+                upstream = %upstream,
+                content_length = ?content_length,
+                body_bytes_seen = ctx.request_body_bytes_seen,
+                protection_class = ?protection_class,
+                protection_client,
+                elapsed_ms,
+                "Pingora gateway request completed"
+            );
+        }
+    }
+
+    fn suppress_error_log(
+        &self,
+        _session: &Session,
+        _ctx: &Self::CTX,
+        error: &pingora::Error,
+    ) -> bool {
+        is_payload_too_large_error(error)
+    }
+
+    async fn fail_to_proxy(
+        &self,
+        session: &mut Session,
+        error: &pingora::Error,
+        ctx: &mut Self::CTX,
+    ) -> FailToProxy
+    where
+        Self::CTX: Send + Sync,
+    {
+        if is_payload_too_large_error(error) {
+            if session.response_written().is_none() {
+                respond_json(session, 413, payload_too_large_body())
+                    .await
+                    .unwrap_or_else(|error| {
+                        warn!(%error, "请求体超限响应写入失败");
+                    });
+            }
+
+            return FailToProxy {
+                error_code: 413,
+                can_reuse_downstream: false,
+            };
+        }
+
+        let status = match error.etype() {
+            ConnectTimedout | ReadTimedout | WriteTimedout => 504,
+            HTTPStatus(code) => *code,
+            _ => match error.esource() {
+                ErrorSource::Upstream => 502,
+                ErrorSource::Downstream => match error.etype() {
+                    WriteError | ReadError | ConnectionClosed => 0,
+                    _ => 400,
+                },
+                ErrorSource::Internal | ErrorSource::Unset => 500,
+            },
+        };
+        if status > 0 {
+            let response_result = if ctx.route.proxy_target().is_some() {
+                respond_gateway_proxy_error(session, status).await
+            } else {
+                session.respond_error(status).await
+            };
+            response_result.unwrap_or_else(|error| {
+                warn!(%error, "Pingora 错误响应写入失败");
+            });
+        }
+
+        FailToProxy {
+            error_code: status,
+            can_reuse_downstream: false,
+        }
+    }
+}
+
+struct AccessLogRecord<'a> {
+    request_id: &'a str,
+    method: &'a str,
+    path: &'a str,
+    uri: &'a str,
+    host: &'a str,
+    client_ip: &'a str,
+    status: u16,
+    route: &'a str,
+    proxy_target: &'a str,
+    upstream: &'a str,
+    content_length: Option<u64>,
+    body_bytes_seen: u64,
+    protection_class: Option<&'static str>,
+    protection_client: &'a str,
+    elapsed_ms: u128,
+    error: Option<String>,
+}
+
+fn write_access_log(path: Option<&Path>, record: AccessLogRecord<'_>) {
+    let Some(path) = path else {
+        return;
+    };
+
+    if let Some(parent) = path.parent()
+        && let Err(error) = std::fs::create_dir_all(parent)
+    {
+        warn!(
+            file = %path.display(),
+            %error,
+            "Pingora access log 目录创建失败"
+        );
+        return;
+    }
+
+    let line = format_access_log_line(&record);
+    match OpenOptions::new().create(true).append(true).open(path) {
+        Ok(mut file) => {
+            if let Err(error) = file.write_all(line.as_bytes()) {
+                warn!(
+                    file = %path.display(),
+                    %error,
+                    "Pingora access log 写入失败"
+                );
+            }
+        }
+        Err(error) => {
+            warn!(
+                file = %path.display(),
+                %error,
+                "Pingora access log 打开失败"
+            );
+        }
+    }
+}
+
+fn format_access_log_line(record: &AccessLogRecord<'_>) -> String {
+    format!(
+        concat!(
+            "request_id={}\tmethod={}\tpath={}\turi={}\thost={}\tclient_ip={}\tstatus={}\t",
+            "route={}\tproxy_target={}\tupstream={}\tcontent_length={}\tbody_bytes_seen={}\t",
+            "protection_class={}\tprotection_client={}\telapsed_ms={}\terror={}\n"
+        ),
+        escape_access_log_value(record.request_id),
+        escape_access_log_value(record.method),
+        escape_access_log_value(record.path),
+        escape_access_log_value(record.uri),
+        escape_access_log_value(record.host),
+        escape_access_log_value(record.client_ip),
+        record.status,
+        escape_access_log_value(record.route),
+        escape_access_log_value(record.proxy_target),
+        escape_access_log_value(record.upstream),
+        record
+            .content_length
+            .map(|value| value.to_string())
+            .unwrap_or_else(|| "-".to_string()),
+        record.body_bytes_seen,
+        record.protection_class.unwrap_or("-"),
+        escape_access_log_value(record.protection_client),
+        record.elapsed_ms,
+        record
+            .error
+            .as_deref()
+            .map(escape_access_log_value)
+            .unwrap_or_else(|| "-".to_string())
+    )
+}
+
+fn escape_access_log_value(value: &str) -> String {
+    value
+        .replace('\\', "\\\\")
+        .replace('\t', "\\t")
+        .replace('\n', "\\n")
+        .replace('\r', "\\r")
+}
+
+fn should_disable_accel_buffering(route: &RouteDecision) -> bool {
+    matches!(
+        route.proxy_target(),
+        Some(ProxyTarget::Api | ProxyTarget::Gitea)
+    )
+}
+
+fn is_long_upstream_route(path: &str) -> bool {
+    is_spacetime_subscribe_path(path) || is_gallery_list_path(path) || is_gallery_detail_path(path)
+}
+
+fn is_generic_api_proxy_path(path: &str) -> bool {
+    path == "/api" || path.starts_with("/api/")
+}
+
+fn protection_class_for_route(route: &RouteDecision, path: &str) -> Option<ProtectionClass> {
+    match route {
+        RouteDecision::Proxy {
+            target: ProxyTarget::Api,
+            ..
+        } if path.starts_with("/admin/api/") => Some(ProtectionClass::AdminApi),
+        RouteDecision::Proxy {
+            target: ProxyTarget::Api,
+            ..
+        } if is_gallery_list_path(path) => Some(ProtectionClass::GalleryList),
+        RouteDecision::Proxy {
+            target: ProxyTarget::Api,
+            ..
+        } if is_gallery_detail_path(path) => Some(ProtectionClass::GalleryDetail),
+        RouteDecision::Proxy {
+            target: ProxyTarget::Api,
+            ..
+        } => Some(ProtectionClass::Api),
+        RouteDecision::Proxy {
+            target: ProxyTarget::Spacetime,
+            ..
+        } => Some(ProtectionClass::Spacetime),
+        RouteDecision::Proxy {
+            target: ProxyTarget::Gitea,
+            ..
+        } => None,
+        RouteDecision::Local(_) => None,
+    }
+}
+
+fn validate_shadow_probe_token(token: &str) -> io::Result<()> {
+    if token == "__GENARRATIVE_PINGORA_PROBE_TOKEN__"
+        || token.eq_ignore_ascii_case("changeme")
+        || token.len() < 16
+    {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN 必须使用 16 字符以上的非占位 token",
+        ));
+    }
+    Ok(())
+}
+
+fn validate_access_log_file(path: &Path) -> io::Result<()> {
+    if path.as_os_str().is_empty() {
+        return Ok(());
+    }
+
+    if path.exists() && path.is_dir() {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            format!(
+                "GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE 不能指向目录：{}",
+                path.display()
+            ),
+        ));
+    }
+
+    Ok(())
+}
+
+fn validate_instance_protection_boundary(
+    instance_count: u32,
+    protection_enabled: bool,
+    shared_protection_confirmed: bool,
+) -> io::Result<()> {
+    if instance_count == 0 {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT 必须大于 0",
+        ));
+    }
+
+    if protection_enabled && instance_count > 1 && !shared_protection_confirmed {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "Pingora 接流保护当前默认是进程内状态；GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1 时必须设置 GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true，或关闭网关保护并由前置层承担",
+        ));
+    }
+
+    Ok(())
+}
+
+fn parse_socket_addr_config(key: &str, value: &str) -> io::Result<SocketAddr> {
+    value.parse().map_err(|error| {
+        io::Error::new(
+            io::ErrorKind::InvalidInput,
+            format!("{key} 不是有效 socket 地址 {value:?}：{error}"),
+        )
+    })
+}
+
+fn validate_distinct_listen_addr(
+    key: &str,
+    listen_addr: SocketAddr,
+    primary_listen_addr: SocketAddr,
+    api_upstream: SocketAddr,
+    spacetime_upstream: SocketAddr,
+    gitea_upstream: Option<SocketAddr>,
+) -> io::Result<()> {
+    if listen_addr == primary_listen_addr {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            format!("{key} 不能与 GENARRATIVE_PINGORA_GATEWAY_LISTEN 相同"),
+        ));
+    }
+
+    if listen_addr == api_upstream
+        || listen_addr == spacetime_upstream
+        || Some(listen_addr) == gitea_upstream
+    {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            format!("{key} 不能与上游地址相同"),
+        ));
+    }
+
+    Ok(())
+}
+
+fn validate_tls_file_config(
+    cert_file: &Option<PathBuf>,
+    key_file: &Option<PathBuf>,
+) -> io::Result<()> {
+    let cert_file = cert_file.as_ref().ok_or_else(|| {
+        io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "配置 GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN 时必须设置 GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE",
+        )
+    })?;
+    let key_file = key_file.as_ref().ok_or_else(|| {
+        io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "配置 GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN 时必须设置 GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE",
+        )
+    })?;
+
+    validate_existing_file(
+        "GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE",
+        cert_file.as_path(),
+    )?;
+    validate_existing_file(
+        "GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE",
+        key_file.as_path(),
+    )?;
+    Ok(())
+}
+
+fn validate_existing_file(key: &str, path: &Path) -> io::Result<()> {
+    let metadata = std::fs::metadata(path).map_err(|error| {
+        io::Error::new(
+            io::ErrorKind::InvalidInput,
+            format!("{key} 无法读取 {}：{error}", path.display()),
+        )
+    })?;
+    if !metadata.is_file() {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            format!("{key} 必须指向文件：{}", path.display()),
+        ));
+    }
+    Ok(())
+}
+
+fn validate_redirect_target_scheme(scheme: &str) -> io::Result<()> {
+    if scheme == "https" {
+        return Ok(());
+    }
+
+    Err(io::Error::new(
+        io::ErrorKind::InvalidInput,
+        "GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_TARGET_SCHEME 当前只允许 https",
+    ))
+}
+
+impl GenarrativeGateway {
+    fn is_maintenance_enabled(&self) -> bool {
+        self.config.maintenance_file.exists()
+    }
+
+    fn is_shadow_probe_authorized(&self, session: &Session) -> bool {
+        let Some(expected) = self.config.shadow_probe_token.as_deref() else {
+            return false;
+        };
+
+        session
+            .req_header()
+            .headers
+            .get(SHADOW_PROBE_HEADER)
+            .and_then(|value| value.to_str().ok())
+            .is_some_and(|actual| actual == expected)
+    }
+
+    fn classify_request(&self, host: Option<&str>, path: &str) -> RouteDecision {
+        match self.mode {
+            GatewayMode::Proxy if self.config.matches_gitea_host(host) => RouteDecision::Proxy {
+                target: ProxyTarget::Gitea,
+                body_limit: None,
+            },
+            GatewayMode::Proxy => classify_path(path),
+            GatewayMode::HttpRedirect => classify_http_redirect_path(path),
+        }
+    }
+}
+
+fn classify_path(path: &str) -> RouteDecision {
+    if path == SHADOW_PROBE_PATH {
+        return RouteDecision::Local(LocalResponse::ShadowProbe);
+    }
+
+    if path == "/admin" {
+        return RouteDecision::Local(LocalResponse::RedirectPermanent {
+            location: "/admin/",
+        });
+    }
+
+    if path.starts_with("/.well-known/acme-challenge/") {
+        return RouteDecision::Local(LocalResponse::Static {
+            root: StaticRoot::Acme,
+            mode: StaticMode::Exact,
+        });
+    }
+
+    if path.starts_with("/admin/api/") {
+        return RouteDecision::Proxy {
+            target: ProxyTarget::Api,
+            body_limit: None,
+        };
+    }
+
+    if is_gallery_list_path(path) {
+        return RouteDecision::Proxy {
+            target: ProxyTarget::Api,
+            body_limit: None,
+        };
+    }
+
+    if is_gallery_detail_path(path) {
+        return RouteDecision::Proxy {
+            target: ProxyTarget::Api,
+            body_limit: None,
+        };
+    }
+
+    if path == "/api" || path.starts_with("/api/") {
+        return RouteDecision::Proxy {
+            target: ProxyTarget::Api,
+            body_limit: Some(DEFAULT_MAX_API_BODY_BYTES),
+        };
+    }
+
+    // 中文注释：公网只转发前端 SDK 必需的 SpacetimeDB subscribe / identity 路由，其它 /v1 继续关闭。
+    if is_spacetime_subscribe_path(path) || path.starts_with("/v1/identity") {
+        return RouteDecision::Proxy {
+            target: ProxyTarget::Spacetime,
+            body_limit: None,
+        };
+    }
+
+    if path.starts_with("/v1/")
+        || path.starts_with("/generated-")
+        || path.starts_with("/healthz")
+        || path.starts_with("/readyz")
+    {
+        return RouteDecision::Local(LocalResponse::NotFound);
+    }
+
+    if path.starts_with("/admin/assets/") || path.starts_with("/assets/") {
+        return RouteDecision::Local(LocalResponse::Static {
+            root: StaticRoot::Web,
+            mode: StaticMode::Exact,
+        });
+    }
+
+    if path.starts_with("/admin/") {
+        return RouteDecision::Local(LocalResponse::Static {
+            root: StaticRoot::Web,
+            mode: StaticMode::SpaFallback,
+        });
+    }
+
+    RouteDecision::Local(LocalResponse::Static {
+        root: StaticRoot::Web,
+        mode: StaticMode::SpaFallback,
+    })
+}
+
+fn classify_http_redirect_path(path: &str) -> RouteDecision {
+    if path.starts_with("/.well-known/acme-challenge/") {
+        return RouteDecision::Local(LocalResponse::Static {
+            root: StaticRoot::Acme,
+            mode: StaticMode::Exact,
+        });
+    }
+
+    RouteDecision::Local(LocalResponse::HttpToHttpsRedirect)
+}
+
+fn apply_configured_body_limit(route: &mut RouteDecision, max_api_body_bytes: u64) {
+    if let RouteDecision::Proxy {
+        target: ProxyTarget::Api,
+        body_limit: Some(body_limit),
+    } = route
+    {
+        *body_limit = max_api_body_bytes;
+    }
+}
+
+fn payload_too_large_body() -> &'static str {
+    r#"{"ok":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"请求体过大"}}"#
+}
+
+fn gateway_proxy_error_body(status: u16) -> &'static str {
+    match status {
+        502 => {
+            r#"{"ok":false,"error":{"code":"GATEWAY_UPSTREAM_ERROR","message":"上游服务不可用"}}"#
+        }
+        504 => {
+            r#"{"ok":false,"error":{"code":"GATEWAY_UPSTREAM_TIMEOUT","message":"上游服务请求超时"}}"#
+        }
+        _ => r#"{"ok":false,"error":{"code":"GATEWAY_PROXY_ERROR","message":"网关代理失败"}}"#,
+    }
+}
+
+fn is_payload_too_large_error(error: &pingora::Error) -> bool {
+    matches!(error.etype(), HTTPStatus(413))
+        && error
+            .context
+            .as_ref()
+            .is_some_and(|context| context.as_str() == PAYLOAD_TOO_LARGE_CONTEXT)
+}
+
+fn is_gallery_list_path(path: &str) -> bool {
+    matches!(
+        path,
+        "/api/runtime/puzzle/gallery" | "/api/runtime/custom-world-gallery"
+    )
+}
+
+fn is_gallery_detail_path(path: &str) -> bool {
+    let parts: Vec<_> = path.trim_matches('/').split('/').collect();
+    matches!(
+        parts.as_slice(),
+        ["api", "runtime", "puzzle", "gallery", _]
+            | ["api", "runtime", "custom-world-gallery", _, _]
+    )
+}
+
+fn is_spacetime_subscribe_path(path: &str) -> bool {
+    let parts: Vec<_> = path.trim_matches('/').split('/').collect();
+    matches!(parts.as_slice(), ["v1", "database", _, "subscribe"])
+}
+
+struct StaticCandidate {
+    path: PathBuf,
+    cache_kind: StaticCacheKind,
+}
+
+struct StaticResponseMetadata {
+    len: u64,
+    etag: String,
+    last_modified: Option<SystemTime>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum StaticRangeDecision {
+    Full,
+    Partial { start: u64, end: u64 },
+    Unsatisfiable,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum StaticCacheKind {
+    Html,
+    FingerprintedAsset,
+    Other,
+}
+
+async fn serve_static(
+    session: &mut Session,
+    root: &Path,
+    root_kind: StaticRoot,
+    mode: StaticMode,
+    cache_config: &StaticCacheConfig,
+) -> PingoraResult<()> {
+    let path = session.req_header().uri.path();
+    let Some(candidate) = resolve_static_candidate(root, root_kind, path, mode).await else {
+        respond_not_found(session).await?;
+        return Ok(());
+    };
+    if !is_static_read_method(&session.req_header().method) {
+        respond_static_method_not_allowed(session).await?;
+        return Ok(());
+    }
+
+    let metadata = match static_response_metadata(&candidate.path).await {
+        Ok(metadata) => metadata,
+        Err(error) => {
+            warn!(
+                path = %path,
+                file = %candidate.path.display(),
+                %error,
+                "静态文件 metadata 读取失败"
+            );
+            respond_not_found(session).await?;
+            return Ok(());
+        }
+    };
+    let content_type = mime_guess::from_path(&candidate.path)
+        .first_or_octet_stream()
+        .essence_str()
+        .to_string();
+    let cache_control = cache_control_for_static_candidate(&candidate, cache_config);
+    let last_modified = metadata.last_modified.map(fmt_http_date);
+    let mut headers = vec![
+        ("Cache-Control".to_string(), cache_control.to_string()),
+        ("ETag".to_string(), metadata.etag.clone()),
+        ("Accept-Ranges".to_string(), "bytes".to_string()),
+    ];
+    if let Some(last_modified) = last_modified.as_deref() {
+        headers.push(("Last-Modified".to_string(), last_modified.to_string()));
+    }
+
+    if static_not_modified(session, &metadata) {
+        return respond_empty_with_headers(session, 304, Some(&content_type), &headers).await;
+    }
+
+    match static_range_decision(session, &metadata) {
+        StaticRangeDecision::Full => {}
+        StaticRangeDecision::Partial { start, end } => {
+            let range_len = end - start + 1;
+            let mut range_headers = headers.clone();
+            range_headers.push((
+                "Content-Range".to_string(),
+                format!("bytes {start}-{end}/{}", metadata.len),
+            ));
+            if session.req_header().method == Method::HEAD {
+                return respond_head_with_headers(
+                    session,
+                    206,
+                    Some(&content_type),
+                    &range_headers,
+                    range_len,
+                )
+                .await;
+            }
+
+            let body = match read_static_range(&candidate.path, start, range_len).await {
+                Ok(bytes) => bytes,
+                Err(error) => {
+                    warn!(
+                        path = %path,
+                        file = %candidate.path.display(),
+                        %error,
+                        "静态文件 Range 读取失败"
+                    );
+                    respond_not_found(session).await?;
+                    return Ok(());
+                }
+            };
+
+            return respond_bytes_with_headers(
+                session,
+                206,
+                Some(&content_type),
+                &range_headers,
+                body,
+            )
+            .await;
+        }
+        StaticRangeDecision::Unsatisfiable => {
+            let mut range_headers = headers.clone();
+            range_headers.push((
+                "Content-Range".to_string(),
+                format!("bytes */{}", metadata.len),
+            ));
+            return respond_head_with_headers(session, 416, Some(&content_type), &range_headers, 0)
+                .await;
+        }
+    }
+
+    if session.req_header().method == Method::HEAD {
+        return respond_head_with_headers(
+            session,
+            200,
+            Some(&content_type),
+            &headers,
+            metadata.len,
+        )
+        .await;
+    }
+
+    let body = match tokio::fs::read(&candidate.path).await {
+        Ok(bytes) => Bytes::from(bytes),
+        Err(error) => {
+            warn!(
+                path = %path,
+                file = %candidate.path.display(),
+                %error,
+                "静态文件读取失败"
+            );
+            respond_not_found(session).await?;
+            return Ok(());
+        }
+    };
+
+    respond_bytes_with_headers(session, 200, Some(&content_type), &headers, body).await
+}
+
+fn is_static_read_method(method: &Method) -> bool {
+    *method == Method::GET || *method == Method::HEAD
+}
+
+async fn read_static_range(path: &Path, start: u64, len: u64) -> io::Result<Bytes> {
+    let mut file = tokio::fs::File::open(path).await?;
+    file.seek(SeekFrom::Start(start)).await?;
+    let mut reader = file.take(len);
+    let capacity = usize::try_from(len)
+        .map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, "Range 长度超过平台上限"))?;
+    let mut body = Vec::with_capacity(capacity);
+    reader.read_to_end(&mut body).await?;
+    Ok(Bytes::from(body))
+}
+
+async fn static_response_metadata(path: &Path) -> io::Result<StaticResponseMetadata> {
+    let metadata = tokio::fs::metadata(path).await?;
+    let len = metadata.len();
+    let last_modified = metadata.modified().ok();
+    Ok(StaticResponseMetadata {
+        len,
+        etag: build_static_etag(len, last_modified),
+        last_modified,
+    })
+}
+
+fn build_static_etag(len: u64, last_modified: Option<SystemTime>) -> String {
+    let modified_secs = last_modified
+        .and_then(|modified| modified.duration_since(UNIX_EPOCH).ok())
+        .map_or(0, |duration| duration.as_secs());
+    format!("W/\"{len:x}-{modified_secs:x}\"")
+}
+
+fn static_not_modified(session: &Session, metadata: &StaticResponseMetadata) -> bool {
+    if session.req_header().method != Method::GET && session.req_header().method != Method::HEAD {
+        return false;
+    }
+
+    if let Some(if_none_match) = header_value(session, "if-none-match") {
+        return if_none_match_matches(&if_none_match, &metadata.etag);
+    }
+
+    let Some(last_modified) = metadata.last_modified else {
+        return false;
+    };
+    header_value(session, "if-modified-since")
+        .and_then(|value| parse_http_date(&value).ok())
+        .is_some_and(|since| truncate_system_time_to_seconds(last_modified) <= since)
+}
+
+fn static_range_decision(
+    session: &Session,
+    metadata: &StaticResponseMetadata,
+) -> StaticRangeDecision {
+    if session.req_header().method != Method::GET && session.req_header().method != Method::HEAD {
+        return StaticRangeDecision::Full;
+    }
+
+    let Some(range) = header_value(session, "range") else {
+        return StaticRangeDecision::Full;
+    };
+    if !static_if_range_matches(session, metadata) {
+        return StaticRangeDecision::Full;
+    }
+    parse_static_range(&range, metadata.len)
+}
+
+fn static_if_range_matches(session: &Session, metadata: &StaticResponseMetadata) -> bool {
+    let Some(if_range) = header_value(session, "if-range") else {
+        return true;
+    };
+    static_if_range_value_matches(&if_range, metadata)
+}
+
+fn static_if_range_value_matches(if_range: &str, metadata: &StaticResponseMetadata) -> bool {
+    if let Ok(if_range_date) = parse_http_date(&if_range) {
+        return metadata.last_modified.is_some_and(|last_modified| {
+            truncate_system_time_to_seconds(last_modified) <= if_range_date
+        });
+    }
+
+    strong_etag_opaque_value(&if_range)
+        .is_some_and(|candidate| strong_etag_opaque_value(&metadata.etag) == Some(candidate))
+}
+
+fn parse_static_range(range: &str, file_len: u64) -> StaticRangeDecision {
+    let range = range.trim();
+    let Some(unit) = range.get(..6) else {
+        return StaticRangeDecision::Full;
+    };
+    if !unit.eq_ignore_ascii_case("bytes=") {
+        return StaticRangeDecision::Full;
+    }
+    let spec = &range[6..];
+    if spec.contains(',') {
+        return StaticRangeDecision::Full;
+    }
+    if file_len == 0 {
+        return StaticRangeDecision::Unsatisfiable;
+    }
+
+    let Some((start, end)) = spec.split_once('-') else {
+        return StaticRangeDecision::Full;
+    };
+    let start = start.trim();
+    let end = end.trim();
+
+    if start.is_empty() {
+        let Ok(suffix_len) = end.parse::<u64>() else {
+            return StaticRangeDecision::Full;
+        };
+        if suffix_len == 0 {
+            return StaticRangeDecision::Unsatisfiable;
+        }
+        let start = file_len.saturating_sub(suffix_len);
+        return StaticRangeDecision::Partial {
+            start,
+            end: file_len - 1,
+        };
+    }
+
+    let Ok(start) = start.parse::<u64>() else {
+        return StaticRangeDecision::Full;
+    };
+    if start >= file_len {
+        return StaticRangeDecision::Unsatisfiable;
+    }
+    if end.is_empty() {
+        return StaticRangeDecision::Partial {
+            start,
+            end: file_len - 1,
+        };
+    }
+
+    let Ok(mut end) = end.parse::<u64>() else {
+        return StaticRangeDecision::Full;
+    };
+    if start > end {
+        return StaticRangeDecision::Unsatisfiable;
+    }
+    end = end.min(file_len - 1);
+    StaticRangeDecision::Partial { start, end }
+}
+
+fn if_none_match_matches(value: &str, etag: &str) -> bool {
+    let expected = weak_etag_opaque_value(etag);
+    value
+        .split(',')
+        .map(str::trim)
+        .any(|candidate| candidate == "*" || weak_etag_opaque_value(candidate) == expected)
+}
+
+fn weak_etag_opaque_value(value: &str) -> &str {
+    value.strip_prefix("W/").unwrap_or(value)
+}
+
+fn strong_etag_opaque_value(value: &str) -> Option<&str> {
+    if value.trim().starts_with("W/") {
+        return None;
+    }
+    Some(value.trim())
+}
+
+fn truncate_system_time_to_seconds(value: SystemTime) -> SystemTime {
+    value
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| UNIX_EPOCH + Duration::from_secs(duration.as_secs()))
+        .unwrap_or(UNIX_EPOCH)
+}
+
+async fn resolve_static_candidate(
+    root: &Path,
+    root_kind: StaticRoot,
+    path: &str,
+    mode: StaticMode,
+) -> Option<StaticCandidate> {
+    let candidate = sanitize_static_path(root, path)?;
+    if is_regular_file(&candidate).await {
+        return Some(StaticCandidate {
+            cache_kind: classify_static_cache_kind(root_kind, path, &candidate),
+            path: candidate,
+        });
+    }
+
+    if is_directory(&candidate).await {
+        let index = candidate.join("index.html");
+        if is_regular_file(&index).await {
+            return Some(StaticCandidate {
+                path: index,
+                cache_kind: StaticCacheKind::Html,
+            });
+        }
+    }
+
+    match mode {
+        StaticMode::Exact => None,
+        StaticMode::SpaFallback if path.starts_with("/admin/") => {
+            let fallback = root.join("admin").join("index.html");
+            is_regular_file(&fallback).await.then_some(StaticCandidate {
+                path: fallback,
+                cache_kind: StaticCacheKind::Html,
+            })
+        }
+        StaticMode::SpaFallback => {
+            let fallback = root.join("index.html");
+            is_regular_file(&fallback).await.then_some(StaticCandidate {
+                path: fallback,
+                cache_kind: StaticCacheKind::Html,
+            })
+        }
+    }
+}
+
+fn classify_static_cache_kind(
+    root_kind: StaticRoot,
+    request_path: &str,
+    file_path: &Path,
+) -> StaticCacheKind {
+    if is_html_path(file_path) {
+        return StaticCacheKind::Html;
+    }
+
+    if root_kind == StaticRoot::Web
+        && (request_path.starts_with("/assets/") || request_path.starts_with("/admin/assets/"))
+        && has_fingerprinted_file_name(file_path)
+    {
+        return StaticCacheKind::FingerprintedAsset;
+    }
+
+    StaticCacheKind::Other
+}
+
+fn cache_control_for_static_candidate<'a>(
+    candidate: &StaticCandidate,
+    config: &'a StaticCacheConfig,
+) -> &'a str {
+    match candidate.cache_kind {
+        StaticCacheKind::Html => config.html_cache_control.as_str(),
+        StaticCacheKind::FingerprintedAsset => config.asset_cache_control.as_str(),
+        StaticCacheKind::Other => config.static_cache_control.as_str(),
+    }
+}
+
+fn is_html_path(path: &Path) -> bool {
+    path.extension()
+        .and_then(|extension| extension.to_str())
+        .is_some_and(|extension| extension.eq_ignore_ascii_case("html"))
+}
+
+fn has_fingerprinted_file_name(path: &Path) -> bool {
+    let Some(file_stem) = path.file_stem().and_then(|value| value.to_str()) else {
+        return false;
+    };
+    file_stem
+        .rsplit_once('-')
+        .is_some_and(|(_, suffix)| is_asset_fingerprint(suffix))
+}
+
+fn is_asset_fingerprint(value: &str) -> bool {
+    value.len() >= 8 && value.bytes().all(|byte| byte.is_ascii_alphanumeric())
+}
+
+fn sanitize_static_path(root: &Path, path: &str) -> Option<PathBuf> {
+    let mut result = root.to_path_buf();
+    for raw_segment in path.trim_start_matches('/').split('/') {
+        if raw_segment.is_empty() {
+            continue;
+        }
+
+        let segment = decode_static_path_segment(raw_segment)?;
+        match segment.as_str() {
+            "." => continue,
+            ".." => return None,
+            _ => result.push(segment),
+        }
+    }
+    Some(result)
+}
+
+fn decode_static_path_segment(segment: &str) -> Option<String> {
+    let bytes = segment.as_bytes();
+    let mut decoded = Vec::with_capacity(bytes.len());
+    let mut index = 0;
+
+    while index < bytes.len() {
+        if bytes[index] == b'%' {
+            let high = *bytes.get(index + 1)?;
+            let low = *bytes.get(index + 2)?;
+            let value = decode_percent_hex(high)? << 4 | decode_percent_hex(low)?;
+            if value == b'/' || value == b'\\' || value == b'\0' {
+                return None;
+            }
+            decoded.push(value);
+            index += 3;
+        } else {
+            if bytes[index] == b'\\' || bytes[index] == b'\0' {
+                return None;
+            }
+            decoded.push(bytes[index]);
+            index += 1;
+        }
+    }
+
+    String::from_utf8(decoded).ok()
+}
+
+fn decode_percent_hex(byte: u8) -> Option<u8> {
+    match byte {
+        b'0'..=b'9' => Some(byte - b'0'),
+        b'a'..=b'f' => Some(byte - b'a' + 10),
+        b'A'..=b'F' => Some(byte - b'A' + 10),
+        _ => None,
+    }
+}
+
+async fn is_regular_file(path: &Path) -> bool {
+    tokio::fs::metadata(path)
+        .await
+        .map(|metadata| metadata.is_file())
+        .unwrap_or(false)
+}
+
+async fn is_directory(path: &Path) -> bool {
+    tokio::fs::metadata(path)
+        .await
+        .map(|metadata| metadata.is_dir())
+        .unwrap_or(false)
+}
+
+async fn respond_maintenance(
+    session: &mut Session,
+    api_like: bool,
+    web_root: &Path,
+) -> PingoraResult<()> {
+    if api_like {
+        return respond_json(
+            session,
+            503,
+            r#"{"ok":false,"error":{"code":"MAINTENANCE","message":"服务维护中"}}"#,
+        )
+        .await;
+    }
+
+    let maintenance_page = web_root.join("maintenance.html");
+    if is_regular_file(&maintenance_page).await {
+        let body = Bytes::from(tokio::fs::read(&maintenance_page).await.unwrap_or_default());
+        respond_bytes(session, 503, Some("text/html; charset=utf-8"), body).await
+    } else {
+        respond_bytes(
+            session,
+            503,
+            Some("text/plain; charset=utf-8"),
+            Bytes::from_static("服务维护中".as_bytes()),
+        )
+        .await
+    }
+}
+
+async fn respond_redirect(session: &mut Session, location: &str) -> PingoraResult<()> {
+    let mut header = ResponseHeader::build(301, Some(0))?;
+    header.insert_header("Location", location)?;
+    header.insert_header("Content-Length", "0")?;
+    session.write_response_header(Box::new(header), true).await
+}
+
+async fn respond_http_to_https_redirect(
+    session: &mut Session,
+    target_scheme: &str,
+) -> PingoraResult<()> {
+    let Some(host) = host_or_authority(session).filter(|value| is_valid_redirect_host(value))
+    else {
+        respond_json(
+            session,
+            400,
+            r#"{"ok":false,"error":{"code":"BAD_REQUEST","message":"无效请求"}}"#,
+        )
+        .await?;
+        return Ok(());
+    };
+    let location = format!(
+        "{target_scheme}://{host}{}",
+        session
+            .req_header()
+            .uri
+            .path_and_query()
+            .map_or("/", |value| value.as_str())
+    );
+    let mut header = ResponseHeader::build(301, Some(0))?;
+    header.insert_header("Location", location.as_str())?;
+    header.insert_header("Content-Length", "0")?;
+    header.insert_header("X-Genarrative-Gateway", "pingora-shadow")?;
+    session.write_response_header(Box::new(header), true).await
+}
+
+async fn respond_json(session: &mut Session, status: u16, body: &str) -> PingoraResult<()> {
+    respond_bytes(
+        session,
+        status,
+        Some("application/json; charset=utf-8"),
+        Bytes::copy_from_slice(body.as_bytes()),
+    )
+    .await
+}
+
+async fn respond_not_found(session: &mut Session) -> PingoraResult<()> {
+    respond_bytes(session, 404, None, Bytes::new()).await
+}
+
+async fn respond_static_method_not_allowed(session: &mut Session) -> PingoraResult<()> {
+    respond_head_with_headers(
+        session,
+        405,
+        None,
+        &[("Allow".to_string(), "GET, HEAD".to_string())],
+        0,
+    )
+    .await
+}
+
+async fn respond_gateway_proxy_error(session: &mut Session, status: u16) -> PingoraResult<()> {
+    respond_json(session, status, gateway_proxy_error_body(status)).await
+}
+
+async fn respond_too_many_requests(
+    session: &mut Session,
+    reason: RejectReason,
+) -> PingoraResult<()> {
+    let body = format!(
+        r#"{{"ok":false,"error":{{"code":"{}","message":"{}"}}}}"#,
+        reason.code(),
+        reason.message()
+    );
+    let is_head = session.req_header().method == Method::HEAD;
+    let mut header = ResponseHeader::build(429, Some(body.len()))?;
+    header.insert_header("Content-Length", body.len().to_string())?;
+    header.insert_header("Content-Type", "application/json; charset=utf-8")?;
+    header.insert_header("Retry-After", "1")?;
+    header.insert_header("X-Genarrative-Gateway", "pingora-shadow")?;
+    session
+        .write_response_header(Box::new(header), is_head)
+        .await?;
+    if !is_head {
+        session
+            .write_response_body(Some(Bytes::from(body)), true)
+            .await?;
+    }
+    Ok(())
+}
+
+async fn respond_shadow_probe(
+    session: &mut Session,
+    maintenance_enabled: bool,
+) -> PingoraResult<()> {
+    let maintenance = if maintenance_enabled { "true" } else { "false" };
+    let body = format!(r#"{{"ok":true,"gateway":"pingora-shadow","maintenance":{maintenance}}}"#);
+    respond_bytes(
+        session,
+        200,
+        Some("application/json; charset=utf-8"),
+        Bytes::from(body),
+    )
+    .await
+}
+
+async fn respond_bytes(
+    session: &mut Session,
+    status: u16,
+    content_type: Option<&str>,
+    body: Bytes,
+) -> PingoraResult<()> {
+    respond_bytes_with_headers(session, status, content_type, &[], body).await
+}
+
+async fn respond_bytes_with_headers(
+    session: &mut Session,
+    status: u16,
+    content_type: Option<&str>,
+    headers: &[(String, String)],
+    body: Bytes,
+) -> PingoraResult<()> {
+    let is_head = session.req_header().method == Method::HEAD;
+    let mut header = ResponseHeader::build(status, Some(body.len()))?;
+    header.insert_header("Content-Length", body.len().to_string())?;
+    if let Some(content_type) = content_type {
+        header.insert_header("Content-Type", content_type)?;
+    }
+    for (name, value) in headers {
+        if !value.is_empty() {
+            header.insert_header(name.clone(), value.as_str())?;
+        }
+    }
+    header.insert_header("X-Genarrative-Gateway", "pingora-shadow")?;
+    session
+        .write_response_header(Box::new(header), is_head || body.is_empty())
+        .await?;
+    if !is_head && !body.is_empty() {
+        session.write_response_body(Some(body), true).await?;
+    }
+    Ok(())
+}
+
+async fn respond_head_with_headers(
+    session: &mut Session,
+    status: u16,
+    content_type: Option<&str>,
+    headers: &[(String, String)],
+    content_length: u64,
+) -> PingoraResult<()> {
+    let mut header = ResponseHeader::build(status, Some(headers.len() + 3))?;
+    header.insert_header("Content-Length", content_length.to_string())?;
+    if let Some(content_type) = content_type {
+        header.insert_header("Content-Type", content_type)?;
+    }
+    for (name, value) in headers {
+        if !value.is_empty() {
+            header.insert_header(name.clone(), value.as_str())?;
+        }
+    }
+    header.insert_header("X-Genarrative-Gateway", "pingora-shadow")?;
+    session.write_response_header(Box::new(header), true).await
+}
+
+async fn respond_empty_with_headers(
+    session: &mut Session,
+    status: u16,
+    content_type: Option<&str>,
+    headers: &[(String, String)],
+) -> PingoraResult<()> {
+    let mut header = ResponseHeader::build(status, Some(headers.len() + 2))?;
+    if let Some(content_type) = content_type {
+        header.insert_header("Content-Type", content_type)?;
+    }
+    for (name, value) in headers {
+        if !value.is_empty() {
+            header.insert_header(name.clone(), value.as_str())?;
+        }
+    }
+    header.insert_header("X-Genarrative-Gateway", "pingora-shadow")?;
+    session.write_response_header(Box::new(header), true).await
+}
+
+fn resolve_request_id(session: &Session) -> String {
+    session
+        .req_header()
+        .headers
+        .get("x-request-id")
+        .and_then(|value| value.to_str().ok())
+        .filter(|value| !value.trim().is_empty())
+        .map(ToOwned::to_owned)
+        .unwrap_or_else(|| Uuid::new_v4().to_string())
+}
+
+fn content_length(session: &Session) -> Option<u64> {
+    header_value(session, "content-length")?.parse().ok()
+}
+
+fn header_value(session: &Session, name: &str) -> Option<String> {
+    session
+        .req_header()
+        .headers
+        .get(name)
+        .and_then(|value| value.to_str().ok())
+        .filter(|value| !value.trim().is_empty())
+        .map(ToOwned::to_owned)
+}
+
+fn host_or_authority(session: &Session) -> Option<String> {
+    header_value(session, "host").or_else(|| {
+        session
+            .req_header()
+            .uri
+            .authority()
+            .map(|authority| authority.as_str().to_string())
+    })
+}
+
+fn is_valid_redirect_host(host: &str) -> bool {
+    !host.is_empty()
+        && host.len() <= 255
+        && host.bytes().all(|byte| {
+            byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-' | b':' | b'[' | b']')
+        })
+}
+
+fn client_ip(session: &Session) -> Option<String> {
+    session
+        .as_downstream()
+        .client_addr()
+        .and_then(|addr| addr.as_inet())
+        .map(|addr| addr.ip().to_string())
+}
+
+fn append_forwarded_for(session: &Session, client_ip: &str) -> String {
+    session
+        .req_header()
+        .headers
+        .get("x-forwarded-for")
+        .and_then(|value| value.to_str().ok())
+        .filter(|value| !value.trim().is_empty())
+        .map(|existing| format!("{existing}, {client_ip}"))
+        .unwrap_or_else(|| client_ip.to_string())
+}
+
+fn protection_client_id(session: &Session, trust_x_forwarded_for: bool) -> String {
+    if trust_x_forwarded_for && let Some(forwarded_for) = first_forwarded_for(session) {
+        return forwarded_for;
+    }
+
+    client_ip(session).unwrap_or_else(|| "unknown".to_string())
+}
+
+fn first_forwarded_for(session: &Session) -> Option<String> {
+    session
+        .req_header()
+        .headers
+        .get("x-forwarded-for")
+        .and_then(|value| value.to_str().ok())
+        .and_then(|value| value.split(',').next())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToOwned::to_owned)
+}
+
+fn is_upgrade_request(session: &Session) -> bool {
+    session
+        .req_header()
+        .headers
+        .get("upgrade")
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(|value| value.eq_ignore_ascii_case("websocket"))
+}
+
+fn normalize_accept_encoding_for_gateway_compression(
+    req: &mut RequestHeader,
+    config: CompressionRequestConfig,
+) -> PingoraResult<()> {
+    let algorithm = if config.enabled {
+        req.headers
+            .get("accept-encoding")
+            .and_then(|value| value.to_str().ok())
+            .and_then(|value| select_compression_algorithm(value, config))
+    } else {
+        None
+    };
+
+    if let Some(algorithm) = algorithm {
+        req.insert_header("Accept-Encoding", algorithm.header_value())?;
+    } else {
+        req.remove_header("accept-encoding");
+    }
+
+    Ok(())
+}
+
+fn should_allow_gateway_compression_for_response(
+    resp: &ResponseHeader,
+    min_length_bytes: u64,
+) -> bool {
+    if resp.status.as_u16() != 200
+        || resp.headers.get("content-range").is_some()
+        || resp.headers.get("content-encoding").is_some()
+    {
+        return false;
+    }
+
+    resp.headers
+        .get("content-length")
+        .and_then(|value| value.to_str().ok())
+        .and_then(|value| value.parse::<u64>().ok())
+        .is_none_or(|content_length| content_length >= min_length_bytes)
+}
+
+fn select_compression_algorithm(
+    value: &str,
+    config: CompressionRequestConfig,
+) -> Option<CompressionAlgorithm> {
+    parse_accepted_encodings(value)
+        .into_iter()
+        .find_map(|coding| {
+            if coding.eq_ignore_ascii_case("gzip") && config.gzip {
+                Some(CompressionAlgorithm::Gzip)
+            } else {
+                None
+            }
+        })
+}
+
+fn parse_accepted_encodings(value: &str) -> Vec<String> {
+    value
+        .split(',')
+        .filter_map(|item| {
+            let mut parts = item.split(';');
+            let coding = parts.next()?.trim();
+            if coding.is_empty() {
+                return None;
+            }
+
+            let enabled = parts
+                .map(str::trim)
+                .filter_map(|param| param.split_once('='))
+                .filter(|(name, _)| name.trim().eq_ignore_ascii_case("q"))
+                .all(|(_, value)| value.trim() != "0" && value.trim() != "0.0");
+            if enabled {
+                Some(coding.to_string())
+            } else {
+                None
+            }
+        })
+        .collect()
+}
+
+fn read_env_or_default(key: &str, default_value: &str) -> String {
+    env::var(key)
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+        .unwrap_or_else(|| default_value.to_string())
+}
+
+fn read_optional_env(key: &str) -> Option<String> {
+    env::var(key)
+        .ok()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+fn read_bool_env(key: &str, default_value: bool) -> bool {
+    env::var(key)
+        .ok()
+        .and_then(|value| match value.trim().to_ascii_lowercase().as_str() {
+            "1" | "true" | "yes" | "on" => Some(true),
+            "0" | "false" | "no" | "off" => Some(false),
+            _ => None,
+        })
+        .unwrap_or(default_value)
+}
+
+fn read_u32_env(key: &str, default_value: u32) -> io::Result<u32> {
+    match env::var(key) {
+        Ok(value) if !value.trim().is_empty() => value.trim().parse().map_err(|error| {
+            io::Error::new(
+                io::ErrorKind::InvalidInput,
+                format!("{key} 不是有效整数：{error}"),
+            )
+        }),
+        _ => Ok(default_value),
+    }
+}
+
+fn read_u64_env(key: &str, default_value: u64) -> io::Result<u64> {
+    match env::var(key) {
+        Ok(value) if !value.trim().is_empty() => value.trim().parse().map_err(|error| {
+            io::Error::new(
+                io::ErrorKind::InvalidInput,
+                format!("{key} 不是有效整数：{error}"),
+            )
+        }),
+        _ => Ok(default_value),
+    }
+}
+
+fn read_socket_addr_env(key: &str, default_value: &str) -> io::Result<SocketAddr> {
+    let value = read_env_or_default(key, default_value);
+    value.parse().map_err(|error| {
+        io::Error::new(
+            io::ErrorKind::InvalidInput,
+            format!("{key} 不是有效 socket 地址 {value:?}：{error}"),
+        )
+    })
+}
+
+fn read_optional_socket_addr_env(key: &str) -> io::Result<Option<SocketAddr>> {
+    read_optional_env(key)
+        .map(|value| {
+            value.parse().map_err(|error| {
+                io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    format!("{key} 不是有效 socket 地址 {value:?}：{error}"),
+                )
+            })
+        })
+        .transpose()
+}
+
+fn read_host_list_env(key: &str) -> io::Result<Vec<String>> {
+    let Some(raw) = read_optional_env(key) else {
+        return Ok(Vec::new());
+    };
+    let mut result = Vec::new();
+    for value in raw
+        .split(',')
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
+        let host = normalize_gateway_host(value).ok_or_else(|| {
+            io::Error::new(
+                io::ErrorKind::InvalidInput,
+                format!("{key} 包含无效 Host：{value:?}"),
+            )
+        })?;
+        if !result.contains(&host) {
+            result.push(host);
+        }
+    }
+    Ok(result)
+}
+
+fn normalize_gateway_host(value: &str) -> Option<String> {
+    let value = value.trim();
+    if value.is_empty() || value.contains(['/', '\\', '\n', '\r', '\0']) {
+        return None;
+    }
+    if value.starts_with('[') {
+        return None;
+    }
+    let host = value
+        .rsplit_once(':')
+        .and_then(|(host, port)| {
+            (!port.is_empty() && port.bytes().all(|byte| byte.is_ascii_digit())).then_some(host)
+        })
+        .unwrap_or(value)
+        .trim_end_matches('.');
+    if host.is_empty() || host.len() > 253 {
+        return None;
+    }
+    if !host
+        .bytes()
+        .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-'))
+    {
+        return None;
+    }
+    Some(host.to_ascii_lowercase())
+}
+
+fn validate_configured_gateway_host(key: &str, host: &str) -> io::Result<()> {
+    if normalize_gateway_host(host).as_deref() == Some(host) {
+        return Ok(());
+    }
+
+    Err(io::Error::new(
+        io::ErrorKind::InvalidInput,
+        format!("{key} 包含无效 Host：{host:?}"),
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde::Deserialize;
+
+    const ROUTE_PARITY_MATRIX_JSON: &str =
+        include_str!("../../../../deploy/pingora/nginx-route-parity.matrix.json");
+
+    #[derive(Deserialize)]
+    struct RouteParityMatrix {
+        version: u32,
+        routes: Vec<RouteParityCase>,
+    }
+
+    #[derive(Deserialize)]
+    #[serde(rename_all = "camelCase")]
+    struct RouteParityCase {
+        id: String,
+        sample_path: String,
+        expect: RouteExpectation,
+    }
+
+    #[derive(Deserialize)]
+    #[serde(rename_all = "camelCase")]
+    struct RouteExpectation {
+        kind: String,
+        target: Option<String>,
+        body_limit: Option<BodyLimitExpectation>,
+        root: Option<String>,
+        mode: Option<String>,
+        location: Option<String>,
+        protection_class: Option<String>,
+    }
+
+    #[derive(Deserialize)]
+    #[serde(untagged)]
+    enum BodyLimitExpectation {
+        Named(String),
+        Bytes(u64),
+    }
+
+    fn assert_route_matches_expectation(case: &RouteParityCase, route: &RouteDecision) {
+        match (case.expect.kind.as_str(), route) {
+            ("proxy", RouteDecision::Proxy { target, body_limit }) => {
+                assert_eq!(
+                    Some(proxy_target_name(*target)),
+                    case.expect.target.as_deref(),
+                    "route parity proxy target mismatch: {} {}",
+                    case.id,
+                    case.sample_path
+                );
+                assert_eq!(
+                    *body_limit,
+                    expected_body_limit(case.expect.body_limit.as_ref()),
+                    "route parity body limit mismatch: {} {}",
+                    case.id,
+                    case.sample_path
+                );
+            }
+            ("static", RouteDecision::Local(LocalResponse::Static { root, mode })) => {
+                assert_eq!(
+                    Some(static_root_name(*root)),
+                    case.expect.root.as_deref(),
+                    "route parity static root mismatch: {} {}",
+                    case.id,
+                    case.sample_path
+                );
+                assert_eq!(
+                    Some(static_mode_name(*mode)),
+                    case.expect.mode.as_deref(),
+                    "route parity static mode mismatch: {} {}",
+                    case.id,
+                    case.sample_path
+                );
+            }
+            (
+                "redirect_permanent",
+                RouteDecision::Local(LocalResponse::RedirectPermanent { location }),
+            ) => {
+                assert_eq!(
+                    Some(*location),
+                    case.expect.location.as_deref(),
+                    "route parity redirect location mismatch: {} {}",
+                    case.id,
+                    case.sample_path
+                );
+            }
+            ("shadow_probe", RouteDecision::Local(LocalResponse::ShadowProbe)) => {}
+            ("not_found", RouteDecision::Local(LocalResponse::NotFound)) => {}
+            _ => panic!(
+                "route parity kind mismatch: {} {} expected {} got {:?}",
+                case.id, case.sample_path, case.expect.kind, route
+            ),
+        }
+    }
+
+    fn proxy_target_name(target: ProxyTarget) -> &'static str {
+        match target {
+            ProxyTarget::Api => "api",
+            ProxyTarget::Spacetime => "spacetime",
+            ProxyTarget::Gitea => "gitea",
+        }
+    }
+
+    fn static_root_name(root: StaticRoot) -> &'static str {
+        match root {
+            StaticRoot::Web => "web",
+            StaticRoot::Acme => "acme",
+        }
+    }
+
+    fn static_mode_name(mode: StaticMode) -> &'static str {
+        match mode {
+            StaticMode::Exact => "exact",
+            StaticMode::SpaFallback => "spa_fallback",
+        }
+    }
+
+    fn expected_body_limit(expectation: Option<&BodyLimitExpectation>) -> Option<u64> {
+        match expectation {
+            None => None,
+            Some(BodyLimitExpectation::Bytes(bytes)) => Some(*bytes),
+            Some(BodyLimitExpectation::Named(name)) if name == "default" => {
+                Some(DEFAULT_MAX_API_BODY_BYTES)
+            }
+            Some(BodyLimitExpectation::Named(name)) => {
+                panic!("unknown route parity body limit expectation: {name}")
+            }
+        }
+    }
+
+    fn test_gateway_config() -> GatewayConfig {
+        GatewayConfig {
+            listen_addr: "127.0.0.1:18081".to_string(),
+            tls_listen_addr: None,
+            tls_cert_file: None,
+            tls_key_file: None,
+            http_redirect_listen_addr: None,
+            http_redirect_target_scheme: "https".to_string(),
+            api_upstream: "127.0.0.1:8082".parse().unwrap(),
+            spacetime_upstream: "127.0.0.1:3101".parse().unwrap(),
+            gitea_hosts: Vec::new(),
+            gitea_upstream: None,
+            web_root: PathBuf::from("/srv/genarrative/web"),
+            acme_root: PathBuf::from("/var/www/html"),
+            maintenance_file: PathBuf::from("/var/lib/genarrative/maintenance/enabled"),
+            forwarded_proto: "http".to_string(),
+            max_api_body_bytes: DEFAULT_MAX_API_BODY_BYTES,
+            gzip_enabled: true,
+            gzip_level: DEFAULT_GZIP_LEVEL,
+            gzip_min_length_bytes: DEFAULT_GZIP_MIN_LENGTH_BYTES,
+            compression: CompressionConfig {
+                gzip: true,
+                raw_algorithms: "gzip".to_string(),
+            },
+            static_cache: StaticCacheConfig {
+                html_cache_control: DEFAULT_HTML_CACHE_CONTROL.to_string(),
+                asset_cache_control: DEFAULT_ASSET_CACHE_CONTROL.to_string(),
+                static_cache_control: DEFAULT_STATIC_CACHE_CONTROL.to_string(),
+            },
+            upstream_timeouts: UpstreamTimeoutConfig {
+                connect_timeout_ms: DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS,
+                default_read_timeout_seconds: DEFAULT_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS,
+                api_read_timeout_seconds: DEFAULT_UPSTREAM_API_READ_TIMEOUT_SECONDS,
+                long_read_timeout_seconds: DEFAULT_UPSTREAM_LONG_READ_TIMEOUT_SECONDS,
+                write_timeout_seconds: DEFAULT_UPSTREAM_WRITE_TIMEOUT_SECONDS,
+            },
+            shadow_probe_token: None,
+            trust_x_forwarded_for: false,
+            instance_count: DEFAULT_INSTANCE_COUNT,
+            shared_protection_confirmed: false,
+            protection: ProtectionConfig {
+                enabled: true,
+                admin_api: ProtectionClassConfig {
+                    max_concurrent: 64,
+                    rate_per_second: 30,
+                    burst: 16,
+                },
+                gallery_list: ProtectionClassConfig {
+                    max_concurrent: 320,
+                    rate_per_second: 5000,
+                    burst: 4096,
+                },
+                gallery_detail: ProtectionClassConfig {
+                    max_concurrent: 32,
+                    rate_per_second: 300,
+                    burst: 32,
+                },
+                api: ProtectionClassConfig {
+                    max_concurrent: 64,
+                    rate_per_second: 300,
+                    burst: 64,
+                },
+                spacetime: ProtectionClassConfig {
+                    max_concurrent: 256,
+                    rate_per_second: 1000,
+                    burst: 256,
+                },
+            },
+            log_filter: DEFAULT_LOG_FILTER.to_string(),
+            access_log_file: None,
+            otel_enabled: false,
+        }
+    }
+
+    #[test]
+    fn matches_nginx_route_parity_matrix() {
+        let matrix: RouteParityMatrix = serde_json::from_str(ROUTE_PARITY_MATRIX_JSON)
+            .expect("route parity matrix should be valid JSON");
+        assert_eq!(matrix.version, 1);
+
+        for case in matrix.routes {
+            let route = classify_path(&case.sample_path);
+            assert_route_matches_expectation(&case, &route);
+
+            let expected_protection_class = case.expect.protection_class.as_deref();
+            let actual_protection_class =
+                protection_class_for_route(&route, &case.sample_path).map(ProtectionClass::as_str);
+            assert_eq!(
+                actual_protection_class, expected_protection_class,
+                "route parity protection class mismatch: {} {}",
+                case.id, case.sample_path
+            );
+        }
+    }
+
+    #[test]
+    fn applies_configured_body_limit_to_generic_api_routes_only() {
+        let mut generic_api = classify_path("/api/creation-entry/config");
+        apply_configured_body_limit(&mut generic_api, 1024);
+        assert_eq!(generic_api.body_limit(), Some(1024));
+
+        let mut gallery = classify_path("/api/runtime/puzzle/gallery");
+        apply_configured_body_limit(&mut gallery, 1024);
+        assert_eq!(gallery.body_limit(), None);
+
+        let mut gitea = RouteDecision::Proxy {
+            target: ProxyTarget::Gitea,
+            body_limit: None,
+        };
+        apply_configured_body_limit(&mut gitea, 1024);
+        assert_eq!(gitea.body_limit(), None);
+    }
+
+    #[test]
+    fn routes_configured_gitea_hosts_to_gitea_upstream() {
+        let config = GatewayConfig {
+            gitea_hosts: vec!["git.genarrative.world".to_string()],
+            gitea_upstream: Some("127.0.0.1:3000".parse().unwrap()),
+            ..test_gateway_config()
+        };
+        let gateway = GenarrativeGateway {
+            config: Arc::new(config),
+            protection: Arc::new(GatewayProtection::new(test_gateway_config().protection)),
+            mode: GatewayMode::Proxy,
+        };
+
+        let route = RouteDecision::Proxy {
+            target: ProxyTarget::Gitea,
+            body_limit: None,
+        };
+        assert_eq!(
+            gateway.classify_request(Some("git.genarrative.world"), "/"),
+            route
+        );
+        assert_eq!(
+            gateway.classify_request(Some("git.genarrative.world:443"), "/api/v1/repos"),
+            route
+        );
+        assert_eq!(
+            gateway.classify_request(Some("GIT.GENARRATIVE.WORLD"), "/assets/app.js"),
+            route
+        );
+        assert_eq!(
+            gateway.classify_request(Some("dev.genarrative.world"), "/api/creation-entry/config"),
+            classify_path("/api/creation-entry/config")
+        );
+    }
+
+    #[test]
+    fn gitea_routes_bypass_maintenance_body_limit_and_protection() {
+        let route = RouteDecision::Proxy {
+            target: ProxyTarget::Gitea,
+            body_limit: None,
+        };
+
+        assert!(!route.applies_maintenance_gate());
+        assert!(!route.is_api_like());
+        assert_eq!(route.body_limit(), None);
+        assert_eq!(protection_class_for_route(&route, "/api/v1/repos"), None);
+        assert!(should_disable_accel_buffering(&route));
+    }
+
+    #[test]
+    fn normalizes_gateway_hosts_for_matching() {
+        assert_eq!(
+            normalize_gateway_host("Git.Genarrative.World:443"),
+            Some("git.genarrative.world".to_string())
+        );
+        assert_eq!(
+            normalize_gateway_host("git.genarrative.world."),
+            Some("git.genarrative.world".to_string())
+        );
+        assert!(normalize_gateway_host("git.genarrative.world/path").is_none());
+        assert!(normalize_gateway_host("[::1]:3000").is_none());
+        assert!(normalize_gateway_host("bad\r\nhost").is_none());
+    }
+
+    #[test]
+    fn validates_gitea_host_routing_config() {
+        let config = GatewayConfig {
+            gitea_hosts: vec!["git.genarrative.world".to_string()],
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            gitea_upstream: Some("127.0.0.1:3000".parse().unwrap()),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            gitea_hosts: vec!["git.genarrative.world".to_string()],
+            gitea_upstream: Some("127.0.0.1:8082".parse().unwrap()),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            gitea_hosts: vec!["git.genarrative.world".to_string()],
+            gitea_upstream: Some("127.0.0.1:3000".parse().unwrap()),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn http_redirect_mode_redirects_non_acme_routes_only() {
+        assert_eq!(
+            classify_http_redirect_path("/api/creation-entry/config"),
+            RouteDecision::Local(LocalResponse::HttpToHttpsRedirect)
+        );
+        assert_eq!(
+            classify_http_redirect_path("/.well-known/acme-challenge/token"),
+            RouteDecision::Local(LocalResponse::Static {
+                root: StaticRoot::Acme,
+                mode: StaticMode::Exact,
+            })
+        );
+    }
+
+    #[test]
+    fn identifies_streaming_payload_limit_errors() {
+        let error = Error::explain(HTTPStatus(413), PAYLOAD_TOO_LARGE_CONTEXT);
+        assert!(is_payload_too_large_error(&error));
+
+        let unrelated = Error::explain(HTTPStatus(413), "other");
+        assert!(!is_payload_too_large_error(&unrelated));
+    }
+
+    #[test]
+    fn maps_gateway_proxy_errors_to_stable_json_codes() {
+        assert!(gateway_proxy_error_body(502).contains("GATEWAY_UPSTREAM_ERROR"));
+        assert!(gateway_proxy_error_body(504).contains("GATEWAY_UPSTREAM_TIMEOUT"));
+        assert!(gateway_proxy_error_body(500).contains("GATEWAY_PROXY_ERROR"));
+    }
+
+    #[test]
+    fn formats_access_log_as_tab_separated_key_values() {
+        let line = format_access_log_line(&AccessLogRecord {
+            request_id: "req-1",
+            method: "GET",
+            path: "/api/test",
+            uri: "/api/test?a=1\t2",
+            host: "example.test",
+            client_ip: "127.0.0.1",
+            status: 200,
+            route: "Proxy",
+            proxy_target: "Api",
+            upstream: "127.0.0.1:8082",
+            content_length: None,
+            body_bytes_seen: 0,
+            protection_class: Some("api"),
+            protection_client: "127.0.0.1",
+            elapsed_ms: 12,
+            error: None,
+        });
+
+        assert!(line.contains("request_id=req-1\tmethod=GET\tpath=/api/test"));
+        assert!(line.contains("uri=/api/test?a=1\\t2"));
+        assert!(line.contains("content_length=-"));
+        assert!(line.ends_with("error=-\n"));
+    }
+
+    #[test]
+    fn rejects_placeholder_or_short_shadow_probe_tokens() {
+        assert!(validate_shadow_probe_token("__GENARRATIVE_PINGORA_PROBE_TOKEN__").is_err());
+        assert!(validate_shadow_probe_token("changeme").is_err());
+        assert!(validate_shadow_probe_token("too-short").is_err());
+        assert!(validate_shadow_probe_token("0123456789abcdef").is_ok());
+    }
+
+    #[test]
+    fn rejects_burst_without_rate_limit() {
+        let config = ProtectionClassConfig {
+            max_concurrent: 1,
+            rate_per_second: 0,
+            burst: 1,
+        };
+        assert!(config.validate("api").is_err());
+    }
+
+    #[test]
+    fn rejects_access_log_directory_paths() {
+        let temp_dir = std::env::temp_dir();
+        assert!(validate_access_log_file(&temp_dir).is_err());
+        assert!(validate_access_log_file(&temp_dir.join("pingora-access.log")).is_ok());
+    }
+
+    #[test]
+    fn rejects_incomplete_tls_and_redirect_config() {
+        let config = GatewayConfig {
+            tls_listen_addr: Some("127.0.0.1:18443".to_string()),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            http_redirect_listen_addr: Some("127.0.0.1:18080".to_string()),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            tls_listen_addr: Some("127.0.0.1:18081".to_string()),
+            tls_cert_file: Some(PathBuf::from("/missing/cert.pem")),
+            tls_key_file: Some(PathBuf::from("/missing/key.pem")),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+    }
+
+    #[test]
+    fn validates_redirect_target_host_and_scheme() {
+        assert!(validate_redirect_target_scheme("https").is_ok());
+        assert!(validate_redirect_target_scheme("http").is_err());
+        assert!(is_valid_redirect_host("genarrative.world"));
+        assert!(is_valid_redirect_host("localhost:8443"));
+        assert!(is_valid_redirect_host("[::1]:8443"));
+        assert!(!is_valid_redirect_host("evil.test/path"));
+        assert!(!is_valid_redirect_host("evil.test\r\nx: y"));
+    }
+
+    #[test]
+    fn builds_stable_static_validators() {
+        let modified = UNIX_EPOCH + Duration::from_secs(1_700_000_123);
+
+        assert_eq!(
+            build_static_etag(4096, Some(modified)),
+            "W/\"1000-6553f17b\""
+        );
+        assert_eq!(build_static_etag(0, None), "W/\"0-0\"");
+        assert_eq!(
+            truncate_system_time_to_seconds(modified + Duration::from_millis(900)),
+            modified
+        );
+    }
+
+    #[test]
+    fn matches_static_if_none_match_values() {
+        assert!(if_none_match_matches("*", "W/\"1000-6553f17b\""));
+        assert!(if_none_match_matches(
+            "\"other\", W/\"1000-6553f17b\"",
+            "W/\"1000-6553f17b\""
+        ));
+        assert!(if_none_match_matches(
+            "\"1000-6553f17b\"",
+            "W/\"1000-6553f17b\""
+        ));
+        assert!(!if_none_match_matches(
+            "\"other\", W/\"bad\"",
+            "W/\"1000-6553f17b\""
+        ));
+    }
+
+    #[test]
+    fn parses_static_byte_ranges() {
+        assert_eq!(
+            parse_static_range("bytes=0-3", 10),
+            StaticRangeDecision::Partial { start: 0, end: 3 }
+        );
+        assert_eq!(
+            parse_static_range("Bytes=5-", 10),
+            StaticRangeDecision::Partial { start: 5, end: 9 }
+        );
+        assert_eq!(
+            parse_static_range("bytes=-4", 10),
+            StaticRangeDecision::Partial { start: 6, end: 9 }
+        );
+        assert_eq!(
+            parse_static_range("bytes=-20", 10),
+            StaticRangeDecision::Partial { start: 0, end: 9 }
+        );
+        assert_eq!(
+            parse_static_range("bytes=8-20", 10),
+            StaticRangeDecision::Partial { start: 8, end: 9 }
+        );
+        assert_eq!(
+            parse_static_range("bytes=10-11", 10),
+            StaticRangeDecision::Unsatisfiable
+        );
+        assert_eq!(
+            parse_static_range("bytes=4-3", 10),
+            StaticRangeDecision::Unsatisfiable
+        );
+        assert_eq!(
+            parse_static_range("bytes=-0", 10),
+            StaticRangeDecision::Unsatisfiable
+        );
+        assert_eq!(
+            parse_static_range("bytes=0-1,3-4", 10),
+            StaticRangeDecision::Full
+        );
+        assert_eq!(
+            parse_static_range("items=0-1", 10),
+            StaticRangeDecision::Full
+        );
+        assert_eq!(
+            parse_static_range("bytes=0-1", 0),
+            StaticRangeDecision::Unsatisfiable
+        );
+    }
+
+    #[test]
+    fn matches_static_if_range_values() {
+        let modified = UNIX_EPOCH + Duration::from_secs(1_700_000_123);
+        let metadata = StaticResponseMetadata {
+            len: 4096,
+            etag: build_static_etag(4096, Some(modified)),
+            last_modified: Some(modified),
+        };
+
+        assert!(static_if_range_value_matches(
+            &fmt_http_date(modified + Duration::from_secs(30)),
+            &metadata
+        ));
+        assert!(!static_if_range_value_matches(
+            &fmt_http_date(modified - Duration::from_secs(30)),
+            &metadata
+        ));
+        assert!(!static_if_range_value_matches(&metadata.etag, &metadata));
+        assert!(!static_if_range_value_matches(
+            "\"1000-6553f17b\"",
+            &metadata
+        ));
+    }
+
+    #[test]
+    fn only_allows_static_read_methods() {
+        assert!(is_static_read_method(&Method::GET));
+        assert!(is_static_read_method(&Method::HEAD));
+        assert!(!is_static_read_method(&Method::POST));
+        assert!(!is_static_read_method(&Method::PUT));
+    }
+
+    #[test]
+    fn rejects_invalid_gzip_level() {
+        let config = GatewayConfig {
+            gzip_level: 10,
+            ..test_gateway_config()
+        };
+
+        assert!(config.validate().is_err());
+    }
+
+    #[test]
+    fn rejects_invalid_gzip_min_length() {
+        let config = GatewayConfig {
+            gzip_min_length_bytes: 0,
+            ..test_gateway_config()
+        };
+
+        assert!(config.validate().is_err());
+    }
+
+    #[test]
+    fn rejects_static_cache_control_header_injection() {
+        let config = GatewayConfig {
+            static_cache: StaticCacheConfig {
+                html_cache_control: "no-cache\nX-Bad: yes".to_string(),
+                asset_cache_control: DEFAULT_ASSET_CACHE_CONTROL.to_string(),
+                static_cache_control: DEFAULT_STATIC_CACHE_CONTROL.to_string(),
+            },
+            ..test_gateway_config()
+        };
+
+        assert!(config.validate().is_err());
+    }
+
+    #[test]
+    fn rejects_unconfirmed_multi_instance_protection() {
+        let config = GatewayConfig {
+            instance_count: 0,
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            instance_count: 2,
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            instance_count: 2,
+            shared_protection_confirmed: true,
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_ok());
+
+        let config = GatewayConfig {
+            instance_count: 2,
+            protection: ProtectionConfig {
+                enabled: false,
+                ..test_gateway_config().protection
+            },
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn rejects_zero_upstream_timeouts() {
+        assert!(
+            UpstreamTimeoutConfig {
+                connect_timeout_ms: 0,
+                default_read_timeout_seconds: DEFAULT_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS,
+                api_read_timeout_seconds: DEFAULT_UPSTREAM_API_READ_TIMEOUT_SECONDS,
+                long_read_timeout_seconds: DEFAULT_UPSTREAM_LONG_READ_TIMEOUT_SECONDS,
+                write_timeout_seconds: DEFAULT_UPSTREAM_WRITE_TIMEOUT_SECONDS,
+            }
+            .validate()
+            .is_err()
+        );
+        assert!(
+            UpstreamTimeoutConfig {
+                connect_timeout_ms: DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS,
+                default_read_timeout_seconds: DEFAULT_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS,
+                api_read_timeout_seconds: 0,
+                long_read_timeout_seconds: DEFAULT_UPSTREAM_LONG_READ_TIMEOUT_SECONDS,
+                write_timeout_seconds: DEFAULT_UPSTREAM_WRITE_TIMEOUT_SECONDS,
+            }
+            .validate()
+            .is_err()
+        );
+    }
+
+    #[test]
+    fn chooses_long_upstream_timeout_for_gallery_and_spacetime_routes() {
+        let timeouts = UpstreamTimeoutConfig {
+            connect_timeout_ms: 100,
+            default_read_timeout_seconds: 60,
+            api_read_timeout_seconds: 10,
+            long_read_timeout_seconds: 3600,
+            write_timeout_seconds: 20,
+        };
+        let generic_api = classify_path("/api/creation-entry/config");
+        let gallery = classify_path("/api/runtime/puzzle/gallery");
+        let subscribe = classify_path("/v1/database/genarrative/subscribe");
+
+        assert_eq!(
+            timeouts.read_timeout_for_route(&generic_api, "/api/creation-entry/config"),
+            Duration::from_secs(10)
+        );
+        assert_eq!(
+            timeouts.read_timeout_for_route(&gallery, "/api/runtime/puzzle/gallery"),
+            Duration::from_secs(3600)
+        );
+        assert_eq!(
+            timeouts.read_timeout_for_route(&subscribe, "/v1/database/genarrative/subscribe"),
+            Duration::from_secs(3600)
+        );
+    }
+
+    #[test]
+    fn rejects_unsupported_compression_algorithms() {
+        assert!(CompressionConfig::parse("zstd".to_string()).is_err());
+        assert!(CompressionConfig::parse("gzip,br".to_string()).is_err());
+    }
+
+    #[test]
+    fn selects_configured_gateway_compression_algorithm() {
+        let gzip_only = CompressionRequestConfig {
+            enabled: true,
+            gzip: true,
+            min_length_bytes: DEFAULT_GZIP_MIN_LENGTH_BYTES,
+            gzip_level: DEFAULT_GZIP_LEVEL,
+        };
+
+        let mut req = RequestHeader::build(Method::GET, b"/assets/app.js", None).unwrap();
+        req.insert_header("Accept-Encoding", "br, gzip").unwrap();
+        normalize_accept_encoding_for_gateway_compression(&mut req, gzip_only).unwrap();
+        assert_eq!(
+            req.headers
+                .get("accept-encoding")
+                .and_then(|value| value.to_str().ok()),
+            Some("gzip")
+        );
+
+        let mut br_only = RequestHeader::build(Method::GET, b"/assets/app.js", None).unwrap();
+        br_only.insert_header("Accept-Encoding", "br").unwrap();
+        normalize_accept_encoding_for_gateway_compression(&mut br_only, gzip_only).unwrap();
+        assert!(br_only.headers.get("accept-encoding").is_none());
+
+        let mut gzip_disabled = RequestHeader::build(Method::GET, b"/assets/app.js", None).unwrap();
+        gzip_disabled
+            .insert_header("Accept-Encoding", "gzip")
+            .unwrap();
+        normalize_accept_encoding_for_gateway_compression(
+            &mut gzip_disabled,
+            CompressionRequestConfig {
+                enabled: false,
+                gzip: true,
+                min_length_bytes: DEFAULT_GZIP_MIN_LENGTH_BYTES,
+                gzip_level: DEFAULT_GZIP_LEVEL,
+            },
+        )
+        .unwrap();
+        assert!(gzip_disabled.headers.get("accept-encoding").is_none());
+
+        assert_eq!(parse_accepted_encodings("br, gzip;q=1"), ["br", "gzip"]);
+        assert_eq!(parse_accepted_encodings("br, gzip;q=0"), ["br"]);
+    }
+
+    #[test]
+    fn honors_configured_gzip_min_length() {
+        let mut small = ResponseHeader::build(200, Some(1023)).unwrap();
+        small.insert_header("Content-Length", "1023").unwrap();
+        small
+            .insert_header("Content-Type", "application/javascript")
+            .unwrap();
+        assert!(!should_allow_gateway_compression_for_response(
+            &small,
+            DEFAULT_GZIP_MIN_LENGTH_BYTES
+        ));
+
+        let mut exact = ResponseHeader::build(200, Some(1024)).unwrap();
+        exact.insert_header("Content-Length", "1024").unwrap();
+        exact
+            .insert_header("Content-Type", "application/javascript")
+            .unwrap();
+        assert!(should_allow_gateway_compression_for_response(
+            &exact,
+            DEFAULT_GZIP_MIN_LENGTH_BYTES
+        ));
+
+        let mut unknown_length = ResponseHeader::build(200, None).unwrap();
+        unknown_length
+            .insert_header("Content-Type", "application/javascript")
+            .unwrap();
+        assert!(should_allow_gateway_compression_for_response(
+            &unknown_length,
+            DEFAULT_GZIP_MIN_LENGTH_BYTES
+        ));
+
+        let mut partial = ResponseHeader::build(206, Some(1024)).unwrap();
+        partial.insert_header("Content-Length", "1024").unwrap();
+        partial
+            .insert_header("Content-Range", "bytes 0-1023/4096")
+            .unwrap();
+        assert!(!should_allow_gateway_compression_for_response(
+            &partial,
+            DEFAULT_GZIP_MIN_LENGTH_BYTES
+        ));
+
+        let mut not_modified = ResponseHeader::build(304, Some(0)).unwrap();
+        not_modified.insert_header("Content-Length", "0").unwrap();
+        assert!(!should_allow_gateway_compression_for_response(
+            &not_modified,
+            DEFAULT_GZIP_MIN_LENGTH_BYTES
+        ));
+    }
+
+    #[test]
+    fn disables_accel_buffering_for_api_proxy_only() {
+        assert!(should_disable_accel_buffering(&classify_path(
+            "/api/creation-entry/config"
+        )));
+        assert!(should_disable_accel_buffering(&classify_path(
+            "/api/runtime/puzzle/gallery"
+        )));
+        assert!(!should_disable_accel_buffering(&classify_path(
+            "/v1/database/genarrative/subscribe"
+        )));
+        assert!(!should_disable_accel_buffering(&classify_path(
+            "/assets/app.js"
+        )));
+    }
+
+    #[test]
+    fn maps_proxy_routes_to_protection_classes() {
+        let cases = [
+            ("/admin/api/users", Some(ProtectionClass::AdminApi)),
+            (
+                "/api/runtime/puzzle/gallery",
+                Some(ProtectionClass::GalleryList),
+            ),
+            (
+                "/api/runtime/custom-world-gallery/profile-a/owner-b",
+                Some(ProtectionClass::GalleryDetail),
+            ),
+            ("/api/creation-entry/config", Some(ProtectionClass::Api)),
+            (
+                "/v1/database/genarrative/subscribe",
+                Some(ProtectionClass::Spacetime),
+            ),
+            ("/assets/app.js", None),
+        ];
+
+        for (path, expected) in cases {
+            assert_eq!(
+                protection_class_for_route(&classify_path(path), path),
+                expected,
+                "path: {path}"
+            );
+        }
+    }
+
+    #[test]
+    fn protection_rejects_when_concurrency_is_exhausted() {
+        let config = ProtectionConfig {
+            enabled: true,
+            api: ProtectionClassConfig {
+                max_concurrent: 1,
+                rate_per_second: 0,
+                burst: 0,
+            },
+            admin_api: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 0,
+                burst: 0,
+            },
+            gallery_list: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 0,
+                burst: 0,
+            },
+            gallery_detail: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 0,
+                burst: 0,
+            },
+            spacetime: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 0,
+                burst: 0,
+            },
+        };
+        let protection = Arc::new(GatewayProtection::new(config));
+        let first = protection
+            .try_acquire(ProtectionClass::Api, "127.0.0.1".to_string())
+            .expect("first request should be accepted");
+
+        assert!(matches!(
+            protection.try_acquire(ProtectionClass::Api, "127.0.0.1".to_string()),
+            Err(RejectReason::Concurrent)
+        ));
+
+        if let Some(key) = first {
+            protection.release(&key);
+        }
+        assert!(
+            protection
+                .try_acquire(ProtectionClass::Api, "127.0.0.1".to_string())
+                .expect("request should be accepted after release")
+                .is_some()
+        );
+    }
+
+    #[test]
+    fn protection_rejects_when_rate_bucket_is_empty() {
+        let config = ProtectionConfig {
+            enabled: true,
+            api: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 1,
+                burst: 0,
+            },
+            admin_api: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 0,
+                burst: 0,
+            },
+            gallery_list: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 0,
+                burst: 0,
+            },
+            gallery_detail: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 0,
+                burst: 0,
+            },
+            spacetime: ProtectionClassConfig {
+                max_concurrent: 0,
+                rate_per_second: 0,
+                burst: 0,
+            },
+        };
+        let protection = Arc::new(GatewayProtection::new(config));
+        let first = protection
+            .try_acquire(ProtectionClass::Api, "127.0.0.1".to_string())
+            .expect("first request should pass");
+        if let Some(key) = first {
+            protection.release(&key);
+        }
+
+        assert!(matches!(
+            protection.try_acquire(ProtectionClass::Api, "127.0.0.1".to_string()),
+            Err(RejectReason::Rate)
+        ));
+        assert!(
+            protection
+                .try_acquire(ProtectionClass::Api, "127.0.0.2".to_string())
+                .expect("different client should have an independent bucket")
+                .is_some()
+        );
+    }
+
+    #[test]
+    fn rejects_path_traversal_for_static_files() {
+        assert!(sanitize_static_path(Path::new("/srv/web"), "/assets/app.js").is_some());
+        assert!(sanitize_static_path(Path::new("/srv/web"), "/assets/../secret").is_none());
+        assert!(sanitize_static_path(Path::new("/srv/web"), "/assets/%2e%2e/secret").is_none(),);
+        assert!(sanitize_static_path(Path::new("/srv/web"), "/assets%2fsecret").is_none());
+        assert!(sanitize_static_path(Path::new("/srv/web"), "/assets/%GG").is_none());
+    }
+
+    #[test]
+    fn decodes_percent_encoded_static_path_segments() {
+        assert_eq!(
+            sanitize_static_path(
+                Path::new("/srv/web"),
+                "/Icons/Admurin%27s%20Pixel%20Items/General/Singles/499_Iron_Gear.png",
+            ),
+            Some(PathBuf::from(
+                "/srv/web/Icons/Admurin's Pixel Items/General/Singles/499_Iron_Gear.png",
+            )),
+        );
+    }
+
+    #[test]
+    fn classifies_static_cache_policy() {
+        let root = StaticRoot::Web;
+        assert_eq!(
+            classify_static_cache_kind(root, "/", Path::new("/srv/web/index.html")),
+            StaticCacheKind::Html
+        );
+        assert_eq!(
+            classify_static_cache_kind(
+                root,
+                "/assets/index-B4dmVw0r.js",
+                Path::new("/srv/web/assets/index-B4dmVw0r.js"),
+            ),
+            StaticCacheKind::FingerprintedAsset
+        );
+        assert_eq!(
+            classify_static_cache_kind(
+                root,
+                "/admin/assets/admin-Ca8f3012.css",
+                Path::new("/srv/web/admin/assets/admin-Ca8f3012.css"),
+            ),
+            StaticCacheKind::FingerprintedAsset
+        );
+        assert_eq!(
+            classify_static_cache_kind(root, "/assets/app.js", Path::new("/srv/web/assets/app.js")),
+            StaticCacheKind::Other
+        );
+        assert_eq!(
+            classify_static_cache_kind(
+                StaticRoot::Acme,
+                "/.well-known/acme-challenge/token-12345678",
+                Path::new("/var/www/html/.well-known/acme-challenge/token-12345678"),
+            ),
+            StaticCacheKind::Other
+        );
+    }
+}
diff --git a/server-rs/crates/shared-contracts/src/puzzle_agent.rs b/server-rs/crates/shared-contracts/src/puzzle_agent.rs
index b417ca801..6d585f5b6 100644
--- a/server-rs/crates/shared-contracts/src/puzzle_agent.rs
+++ b/server-rs/crates/shared-contracts/src/puzzle_agent.rs
@@ -1,6 +1,7 @@
 use serde::{Deserialize, Serialize};
 
 use crate::creation_audio::CreationAudioAsset;
+use crate::external_generation::ExternalGenerationJobStatusRecord;
 
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
@@ -280,6 +281,8 @@ pub struct PuzzleAgentOperationResponse {
     pub progress: u32,
     #[serde(default)]
     pub error: Option<String>,
+    #[serde(default)]
+    pub queue_state: Option<ExternalGenerationJobStatusRecord>,
 }
 
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
diff --git a/server-rs/crates/spacetime-module/src/puzzle.rs b/server-rs/crates/spacetime-module/src/puzzle.rs
index 8b253e7e7..2a568294e 100644
--- a/server-rs/crates/spacetime-module/src/puzzle.rs
+++ b/server-rs/crates/spacetime-module/src/puzzle.rs
@@ -1874,12 +1874,7 @@ fn update_puzzle_work_tx(
     ctx: &TxContext,
     input: PuzzleWorkUpsertInput,
 ) -> Result<PuzzleWorkProfile, String> {
-    let row = ctx
-        .db
-        .puzzle_work_profile()
-        .profile_id()
-        .find(&input.profile_id)
-        .ok_or_else(|| "拼图作品不存在".to_string())?;
+    let row = find_or_recover_puzzle_work_profile_row_for_update(ctx, &input)?;
     if row.owner_user_id != input.owner_user_id {
         return Err("无权修改该拼图作品".to_string());
     }
@@ -1957,6 +1952,97 @@ fn update_puzzle_work_tx(
     )
 }
 
+fn find_or_recover_puzzle_work_profile_row_for_update(
+    ctx: &TxContext,
+    input: &PuzzleWorkUpsertInput,
+) -> Result<PuzzleWorkProfileRow, String> {
+    if let Some(row) = ctx
+        .db
+        .puzzle_work_profile()
+        .profile_id()
+        .find(&input.profile_id)
+    {
+        return Ok(row);
+    }
+
+    let recovery = resolve_stable_puzzle_work_profile_recovery_ids(&input.profile_id)
+        .ok_or_else(|| "拼图作品不存在".to_string())?;
+    let row = get_owned_session_row(ctx, &recovery.session_id, &input.owner_user_id).map_err(
+        |error| {
+            if error.contains("无权") {
+                "无权修改该拼图作品".to_string()
+            } else {
+                "拼图作品不存在".to_string()
+            }
+        },
+    )?;
+    if row.stage == PuzzleAgentStage::Published
+        || row.published_profile_id.as_deref() == Some(input.profile_id.as_str())
+    {
+        return Err("拼图作品不存在".to_string());
+    }
+    let recovered_profile_id = recovery.profile_id.clone();
+    let draft = deserialize_draft_required(&row.draft_json)?;
+    let profile = build_recovered_puzzle_work_profile_from_session(
+        recovery,
+        &input.owner_user_id,
+        &draft,
+        input.updated_at_micros,
+    )?;
+    upsert_puzzle_work_profile(ctx, profile)?;
+    ctx.db
+        .puzzle_work_profile()
+        .profile_id()
+        .find(&recovered_profile_id)
+        .ok_or_else(|| "拼图作品不存在".to_string())
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct PuzzleWorkProfileRecoveryIds {
+    work_id: String,
+    profile_id: String,
+    session_id: String,
+}
+
+fn resolve_stable_puzzle_work_profile_recovery_ids(
+    profile_id: &str,
+) -> Option<PuzzleWorkProfileRecoveryIds> {
+    let normalized_profile_id = profile_id.trim();
+    let stable_suffix = normalized_profile_id.strip_prefix("puzzle-profile-")?;
+    if stable_suffix.trim().is_empty() {
+        return None;
+    }
+    let session_id = format!("puzzle-session-{stable_suffix}");
+    let (work_id, derived_profile_id) = build_puzzle_work_ids_from_session_id(&session_id);
+    if derived_profile_id != normalized_profile_id {
+        return None;
+    }
+    Some(PuzzleWorkProfileRecoveryIds {
+        work_id,
+        profile_id: derived_profile_id,
+        session_id,
+    })
+}
+
+fn build_recovered_puzzle_work_profile_from_session(
+    recovery: PuzzleWorkProfileRecoveryIds,
+    owner_user_id: &str,
+    draft: &PuzzleResultDraft,
+    updated_at_micros: i64,
+) -> Result<PuzzleWorkProfile, String> {
+    // 中文注释：update 可能晚于草稿投影落库执行；只恢复稳定 session 派生的草稿 profile。
+    create_work_profile(
+        recovery.work_id,
+        recovery.profile_id,
+        owner_user_id.to_string(),
+        Some(recovery.session_id),
+        "陶泥儿主".to_string(),
+        draft,
+        updated_at_micros,
+    )
+    .map_err(|error| error.to_string())
+}
+
 fn sync_puzzle_source_session_draft_from_work(
     ctx: &TxContext,
     work_row: &PuzzleWorkProfileRow,
@@ -4243,6 +4329,62 @@ mod tests {
         assert_eq!(draft.work_title, "我的猫街合集");
     }
 
+    #[test]
+    fn stable_puzzle_profile_id_recovers_source_session_ids() {
+        let ids = resolve_stable_puzzle_work_profile_recovery_ids(
+            "puzzle-profile-b1cf819ea2d944c4a7e34ca668f8a97c",
+        )
+        .expect("stable puzzle profile should be recoverable");
+
+        assert_eq!(
+            ids.session_id,
+            "puzzle-session-b1cf819ea2d944c4a7e34ca668f8a97c"
+        );
+        assert_eq!(ids.work_id, "puzzle-work-b1cf819ea2d944c4a7e34ca668f8a97c");
+        assert_eq!(
+            ids.profile_id,
+            "puzzle-profile-b1cf819ea2d944c4a7e34ca668f8a97c"
+        );
+        assert!(resolve_stable_puzzle_work_profile_recovery_ids("").is_none());
+        assert!(resolve_stable_puzzle_work_profile_recovery_ids("onboarding-profile-1").is_none());
+        assert!(resolve_stable_puzzle_work_profile_recovery_ids("puzzle-profile-").is_none());
+    }
+
+    #[test]
+    fn recovered_puzzle_work_profile_keeps_draft_identity() {
+        let anchor_pack = infer_anchor_pack("画面描述：一只猫在雨夜灯牌下回头。", None);
+        let draft = compile_result_draft_from_seed(
+            &anchor_pack,
+            &[],
+            Some("画面描述：一只猫在雨夜灯牌下回头。"),
+        );
+        let recovery = resolve_stable_puzzle_work_profile_recovery_ids(
+            "puzzle-profile-b1cf819ea2d944c4a7e34ca668f8a97c",
+        )
+        .expect("stable ids should resolve");
+
+        let profile =
+            build_recovered_puzzle_work_profile_from_session(recovery, "user-1", &draft, 1_000)
+                .expect("profile should recover from draft");
+
+        assert_eq!(
+            profile.work_id,
+            "puzzle-work-b1cf819ea2d944c4a7e34ca668f8a97c"
+        );
+        assert_eq!(
+            profile.profile_id,
+            "puzzle-profile-b1cf819ea2d944c4a7e34ca668f8a97c"
+        );
+        assert_eq!(
+            profile.source_session_id.as_deref(),
+            Some("puzzle-session-b1cf819ea2d944c4a7e34ca668f8a97c")
+        );
+        assert_eq!(profile.owner_user_id, "user-1");
+        assert_eq!(profile.publication_status, PuzzlePublicationStatus::Draft);
+        assert_eq!(profile.updated_at_micros, 1_000);
+        assert_eq!(profile.levels.len(), draft.levels.len());
+    }
+
     #[test]
     fn failed_generation_returns_result_draft_stage_instead_of_refining() {
         let anchor_pack = infer_anchor_pack("画面描述：一只猫在雨夜灯牌下回头。", None);
diff --git a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
index f35b2358c..ba5eccb4f 100644
--- a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
+++ b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
@@ -165,6 +165,7 @@ import {
   fetchCreationEntryConfig,
 } from '../../services/creationEntryConfigService';
 import {
+  type CreationUrlState,
   clearCreationUrlState,
   readCreationUrlState,
   writeCreationUrlState,
@@ -499,6 +500,7 @@ import {
   type PendingDraftShelfKind,
   type PendingDraftShelfMap,
   type PendingDraftShelfMetadata,
+  buildPuzzleDraftOpenNoticeKeys,
   resolveBigFishDraftOpenIntent,
   resolveJumpHopDraftOpenIntent,
   resolveMatch3DDraftOpenIntent,
@@ -909,6 +911,29 @@ function pushPuzzleResultHistoryEntry(
   writeCreationUrlState(buildPuzzleCreationUrlState(session));
 }
 
+function pushPuzzleGeneratingHistoryEntry(
+  session: PuzzleAgentSessionSnapshot | null,
+  fallbackState?: CreationUrlState,
+) {
+  pushAppHistoryPath('/creation/puzzle/generating');
+  writeCreationUrlState(
+    session ? buildPuzzleCreationUrlState(session) : (fallbackState ?? {}),
+  );
+}
+
+function buildPuzzleCreationUrlStateFromWork(
+  item: PuzzleWorkSummary,
+): CreationUrlState {
+  const sourceSessionId = item.sourceSessionId?.trim() || null;
+
+  return {
+    sessionId: sourceSessionId,
+    profileId:
+      item.profileId?.trim() || buildPuzzleResultProfileId(sourceSessionId),
+    workId: item.workId?.trim() || buildPuzzleResultWorkId(sourceSessionId),
+  };
+}
+
 const PUZZLE_DRAFT_GENERATION_POINT_COST = 2;
 const PUZZLE_BACKGROUND_ACTION_POLL_INTERVAL_MS = 3000;
 const PUZZLE_BACKGROUND_ACTION_MAX_POLL_ATTEMPTS = 160;
@@ -4247,6 +4272,7 @@ export function PlatformEntryFlowShellImpl({
             );
           activePuzzleGenerationSessionIdRef.current =
             response.session.sessionId;
+          pushPuzzleGeneratingHistoryEntry(response.session);
           setSelectionStage('puzzle-generating');
           markDraftGenerating('puzzle', [
             response.session.sessionId,
@@ -4391,6 +4417,7 @@ export function PlatformEntryFlowShellImpl({
       );
       selectionStageRef.current = 'puzzle-generating';
       activePuzzleGenerationSessionIdRef.current = session.sessionId;
+      pushPuzzleGeneratingHistoryEntry(session);
       setSelectionStage('puzzle-generating');
       const nextGenerationState = createPuzzleDraftGenerationStateFromPayload(
         formPayload ?? buildPuzzleFormPayloadFromSession(session),
@@ -5657,6 +5684,7 @@ export function PlatformEntryFlowShellImpl({
       }
       selectionStageRef.current = 'puzzle-generating';
       activePuzzleGenerationSessionIdRef.current = nextSession.sessionId;
+      pushPuzzleGeneratingHistoryEntry(nextSession);
       setSelectionStage('puzzle-generating');
 
       try {
@@ -12060,6 +12088,66 @@ export function PlatformEntryFlowShellImpl({
       setPuzzleRun(null);
       setPuzzleRuntimeAuthMode('default');
       setSelectedPuzzleDetail(null);
+      const restorePuzzleGeneratingSession = (
+        latestSession: PuzzleAgentSessionSnapshot,
+      ) => {
+        const payload = buildPuzzleFormPayloadFromSession(latestSession);
+        const startedAtMs = resolveMiniGameDraftGenerationStartedAtMs(
+          latestSession.updatedAt,
+        );
+        const baseGenerationState =
+          createMiniGameDraftGenerationStateForRestoredDraft(
+            'puzzle',
+            {
+              puzzleAiRedraw: payload.aiRedraw ?? true,
+              puzzleProgressPercent:
+                latestSession.draft && !latestSession.draft.formDraft
+                  ? latestSession.progressPercent
+                  : undefined,
+            },
+            startedAtMs,
+          );
+        const generationState = mergePuzzleSessionProgressIntoGenerationState(
+          baseGenerationState,
+          latestSession,
+        );
+        puzzleFlow.setSession(latestSession);
+        setPuzzleFormDraftPayload(payload);
+        setPuzzleGenerationState(generationState);
+        setPuzzleBackgroundCompileTasks((current) => ({
+          ...current,
+          [latestSession.sessionId]: {
+            session: latestSession,
+            payload,
+            generationState,
+            error: null,
+          },
+        }));
+        enterCreateTab();
+        selectionStageRef.current = 'puzzle-generating';
+        activePuzzleGenerationSessionIdRef.current = latestSession.sessionId;
+        pushPuzzleGeneratingHistoryEntry(latestSession);
+        setSelectionStage('puzzle-generating');
+      };
+      const openPuzzleReadyResultSession = (
+        latestSession: PuzzleAgentSessionSnapshot,
+      ) => {
+        const payload = buildPuzzleFormPayloadFromSession(latestSession);
+        puzzleFlow.setSession(latestSession);
+        setPuzzleFormDraftPayload(payload);
+        setPuzzleGenerationState(null);
+        setPuzzleBackgroundCompileTasks((current) => {
+          const next = { ...current };
+          delete next[latestSession.sessionId];
+          return next;
+        });
+        enterCreateTab();
+        selectionStageRef.current = 'puzzle-result';
+        activePuzzleGenerationSessionIdRef.current = null;
+        markDraftNoticeSeen(buildPuzzleDraftOpenNoticeKeys(item));
+        pushPuzzleResultHistoryEntry(latestSession);
+        setSelectionStage('puzzle-result');
+      };
 
       if (openIntent.type === 'open-published-detail') {
         await openPuzzleDetail(item.profileId, { tab: 'create' });
@@ -12125,6 +12213,10 @@ export function PlatformEntryFlowShellImpl({
         enterCreateTab();
         selectionStageRef.current = 'puzzle-generating';
         activePuzzleGenerationSessionIdRef.current = sourceSessionId;
+        pushPuzzleGeneratingHistoryEntry(
+          failedSession,
+          buildPuzzleCreationUrlStateFromWork(item),
+        );
         setPuzzleGenerationState(failedGenerationState);
         setSelectionStage('puzzle-generating');
         return;
@@ -12139,6 +12231,10 @@ export function PlatformEntryFlowShellImpl({
         enterCreateTab();
         selectionStageRef.current = 'puzzle-generating';
         activePuzzleGenerationSessionIdRef.current = sourceSessionId;
+        pushPuzzleGeneratingHistoryEntry(
+          puzzleSession ?? backgroundTask?.session ?? null,
+          buildPuzzleCreationUrlStateFromWork(item),
+        );
         setPuzzleGenerationState(rebasedGenerationState);
         if (backgroundTask) {
           setPuzzleBackgroundCompileTasks((current) => ({
@@ -12169,6 +12265,7 @@ export function PlatformEntryFlowShellImpl({
         enterCreateTab();
         selectionStageRef.current = 'puzzle-generating';
         activePuzzleGenerationSessionIdRef.current = sourceSessionId;
+        pushPuzzleGeneratingHistoryEntry(rebasedTask.session);
         setSelectionStage('puzzle-generating');
         return;
       }
@@ -12177,42 +12274,14 @@ export function PlatformEntryFlowShellImpl({
         try {
           const { session: latestSession } =
             await getPuzzleAgentSession(sourceSessionId);
-          const payload = buildPuzzleFormPayloadFromSession(latestSession);
-          const startedAtMs = resolveMiniGameDraftGenerationStartedAtMs(
-            latestSession.updatedAt,
-          );
-          const baseGenerationState =
-            createMiniGameDraftGenerationStateForRestoredDraft(
-              'puzzle',
-              {
-                puzzleAiRedraw: payload.aiRedraw ?? true,
-                puzzleProgressPercent:
-                  latestSession.draft && !latestSession.draft.formDraft
-                    ? latestSession.progressPercent
-                    : undefined,
-              },
-              startedAtMs,
-            );
-          const generationState = mergePuzzleSessionProgressIntoGenerationState(
-            baseGenerationState,
-            latestSession,
-          );
-          puzzleFlow.setSession(latestSession);
-          setPuzzleFormDraftPayload(payload);
-          setPuzzleGenerationState(generationState);
-          setPuzzleBackgroundCompileTasks((current) => ({
-            ...current,
-            [latestSession.sessionId]: {
-              session: latestSession,
-              payload,
-              generationState,
-              error: null,
-            },
-          }));
-          enterCreateTab();
-          selectionStageRef.current = 'puzzle-generating';
-          activePuzzleGenerationSessionIdRef.current = sourceSessionId;
-          setSelectionStage('puzzle-generating');
+          if (
+            !isPuzzleFormOnlyDraft(latestSession) &&
+            isPuzzleCompileActionReady(latestSession)
+          ) {
+            openPuzzleReadyResultSession(latestSession);
+            return;
+          }
+          restorePuzzleGeneratingSession(latestSession);
           return;
         } catch (error) {
           setPuzzleError(
@@ -12238,6 +12307,10 @@ export function PlatformEntryFlowShellImpl({
         setSelectionStage('puzzle-agent-workspace');
       } else {
         setPuzzleFormDraftPayload(null);
+        pushPuzzleResultHistoryEntry(restoredSession);
+        selectionStageRef.current = 'puzzle-result';
+        activePuzzleGenerationSessionIdRef.current = null;
+        setSelectionStage('puzzle-result');
       }
     },
     [
diff --git a/src/components/platform-entry/platformDraftGenerationShelfModel.test.ts b/src/components/platform-entry/platformDraftGenerationShelfModel.test.ts
index ac5118783..7d3d54f73 100644
--- a/src/components/platform-entry/platformDraftGenerationShelfModel.test.ts
+++ b/src/components/platform-entry/platformDraftGenerationShelfModel.test.ts
@@ -99,6 +99,58 @@ describe('platformDraftGenerationShelfModel', () => {
     });
   });
 
+  test('resolvePuzzleDraftOpenIntent ignores stale generating notice after puzzle draft is ready', () => {
+    expect(
+      resolvePuzzleDraftOpenIntent({
+        item: buildPuzzleWork({
+          generationStatus: 'ready',
+          coverImageSrc: '/generated-puzzle-assets/session/cover.png',
+          levels: [
+            {
+              levelId: 'level-1',
+              levelName: '金色数字舞台',
+              pictureDescription: '123456',
+              pictureReference: null,
+              candidates: [],
+              selectedCandidateId: null,
+              coverImageSrc: '/generated-puzzle-assets/session/cover.png',
+              coverAssetId: 'asset-1',
+              generationStatus: 'ready',
+            },
+          ],
+        }),
+        notices: {
+          'puzzle:puzzle-session-base': {
+            status: 'generating',
+            seen: false,
+          },
+        },
+        generation: emptyGenerationFacts(),
+      }),
+    ).toMatchObject({
+      type: 'restore-draft',
+    });
+  });
+
+  test('resolvePuzzleDraftOpenIntent restores generating page from notice even before persisted status catches up', () => {
+    expect(
+      resolvePuzzleDraftOpenIntent({
+        item: buildPuzzleWork({
+          generationStatus: 'idle',
+        }),
+        notices: {
+          'puzzle:puzzle-session-base': {
+            status: 'generating',
+            seen: false,
+          },
+        },
+        generation: emptyGenerationFacts(),
+      }),
+    ).toMatchObject({
+      type: 'restore-generating',
+    });
+  });
+
   test('resolveMatch3DDraftOpenIntent opens published work detail unless forced into draft', () => {
     const item = buildMatch3DWork({
       publicationStatus: 'published',
diff --git a/src/components/puzzle-result/PuzzleResultView.test.tsx b/src/components/puzzle-result/PuzzleResultView.test.tsx
index ad6d3514c..6fc05b575 100644
--- a/src/components/puzzle-result/PuzzleResultView.test.tsx
+++ b/src/components/puzzle-result/PuzzleResultView.test.tsx
@@ -595,7 +595,7 @@ describe('PuzzleResultView', () => {
     );
   });
 
-  test('adds and deletes levels from the list', async () => {
+  test('keeps a blank new level local until the creator edits it', async () => {
     vi.useFakeTimers();
     vi.mocked(puzzleWorksService.updatePuzzleWork).mockResolvedValue({
       item: {} as never,
@@ -621,25 +621,36 @@ describe('PuzzleResultView', () => {
     expect(
       within(dialog).queryByRole('button', { name: /关卡测试/u }),
     ).toBeNull();
-    fireEvent.click(screen.getByLabelText('关闭关卡详情'));
-    expect(screen.getAllByText('第2关').length).toBeGreaterThan(0);
 
     await act(async () => {
       await vi.runAllTimersAsync();
     });
 
-    expect(puzzleWorksService.updatePuzzleWork).toHaveBeenLastCalledWith(
+    expect(screen.getByRole('dialog', { name: '关卡详情' })).toBeTruthy();
+    expect(screen.queryByText('保存中')).toBeNull();
+    expect(puzzleWorksService.updatePuzzleWork).not.toHaveBeenCalled();
+
+    fireEvent.change(within(dialog).getByLabelText('关卡名称'), {
+      target: { value: '钟楼猫街' },
+    });
+
+    await act(async () => {
+      await vi.runAllTimersAsync();
+    });
+
+    expect(puzzleWorksService.updatePuzzleWork).toHaveBeenCalledWith(
       'puzzle-profile-session-1',
       expect.objectContaining({
         levels: expect.arrayContaining([
           expect.objectContaining({ levelId: 'puzzle-level-1' }),
-          expect.objectContaining({ levelName: '' }),
+          expect.objectContaining({ levelName: '钟楼猫街' }),
         ]),
       }),
     );
 
-    fireEvent.click(screen.getByLabelText('删除关卡 第2关'));
-    expect(screen.queryByText('第2关')).toBeNull();
+    fireEvent.click(screen.getByLabelText('关闭关卡详情'));
+    fireEvent.click(screen.getByLabelText('删除关卡 钟楼猫街'));
+    expect(screen.queryByText('钟楼猫街')).toBeNull();
 
     await act(async () => {
       await vi.runAllTimersAsync();
@@ -657,6 +668,48 @@ describe('PuzzleResultView', () => {
     );
   });
 
+  test('keeps the blank level dialog open across incoming draft refreshes', async () => {
+    vi.useFakeTimers();
+    const base = createSession();
+    const { rerender } = render(
+      <PuzzleResultView
+        session={base}
+        profileId="puzzle-profile-session-1"
+        onBack={() => {}}
+        onExecuteAction={() => {}}
+      />,
+    );
+
+    openPuzzleLevelsTab();
+    fireEvent.click(screen.getByRole('button', { name: /新增关卡/u }));
+    expect(screen.getByRole('dialog', { name: '关卡详情' })).toBeTruthy();
+
+    rerender(
+      <PuzzleResultView
+        session={{
+          ...base,
+          updatedAt: '2026-04-26T10:00:01.000Z',
+        }}
+        profileId="puzzle-profile-session-1"
+        onBack={() => {}}
+        onExecuteAction={() => {}}
+      />,
+    );
+
+    const dialog = screen.getByRole('dialog', { name: '关卡详情' });
+    expect(
+      (within(dialog).getByLabelText('关卡名称') as HTMLInputElement).value,
+    ).toBe('');
+    expect(screen.getByLabelText('删除关卡 第2关')).toBeTruthy();
+    expect(screen.queryByText('保存中')).toBeNull();
+
+    await act(async () => {
+      await vi.runAllTimersAsync();
+    });
+
+    expect(puzzleWorksService.updatePuzzleWork).not.toHaveBeenCalled();
+  });
+
   test('generates image for a newly added level with the current levels snapshot', () => {
     vi.spyOn(Date, 'now').mockReturnValue(1_775_000_000_000);
     const onExecuteAction = vi.fn();
diff --git a/src/components/puzzle-result/PuzzleResultView.tsx b/src/components/puzzle-result/PuzzleResultView.tsx
index ea2ee1e9c..684e872da 100644
--- a/src/components/puzzle-result/PuzzleResultView.tsx
+++ b/src/components/puzzle-result/PuzzleResultView.tsx
@@ -166,6 +166,96 @@ function resolveLevelFormalImageSrc(level: PuzzleDraftLevel) {
   );
 }
 
+function normalizeOptionalPuzzleLevelText(value?: string | null) {
+  return value?.trim() || null;
+}
+
+function normalizePuzzleLevelForSave(level: PuzzleDraftLevel) {
+  return {
+    ...level,
+    levelName: level.levelName.trim(),
+    pictureDescription: level.pictureDescription.trim(),
+    pictureReference: normalizeOptionalPuzzleLevelText(level.pictureReference),
+    uiBackgroundPrompt: normalizeOptionalPuzzleLevelText(
+      level.uiBackgroundPrompt,
+    ),
+    uiBackgroundImageSrc: normalizeOptionalPuzzleLevelText(
+      level.uiBackgroundImageSrc,
+    ),
+    uiBackgroundImageObjectKey: normalizeOptionalPuzzleLevelText(
+      level.uiBackgroundImageObjectKey,
+    ),
+    levelSceneImageSrc: normalizeOptionalPuzzleLevelText(
+      level.levelSceneImageSrc,
+    ),
+    levelSceneImageObjectKey: normalizeOptionalPuzzleLevelText(
+      level.levelSceneImageObjectKey,
+    ),
+    uiSpritesheetImageSrc: normalizeOptionalPuzzleLevelText(
+      level.uiSpritesheetImageSrc,
+    ),
+    uiSpritesheetImageObjectKey: normalizeOptionalPuzzleLevelText(
+      level.uiSpritesheetImageObjectKey,
+    ),
+    levelBackgroundImageSrc: normalizeOptionalPuzzleLevelText(
+      level.levelBackgroundImageSrc,
+    ),
+    levelBackgroundImageObjectKey: normalizeOptionalPuzzleLevelText(
+      level.levelBackgroundImageObjectKey,
+    ),
+    generationStatus: level.generationStatus || 'idle',
+  };
+}
+
+function normalizeDraftEditStateForSave(state: DraftEditState): DraftEditState {
+  return {
+    ...state,
+    workTitle: state.workTitle.trim(),
+    workDescription: state.workDescription.trim(),
+    themeTags: normalizeThemeTagInput(state.themeTags.join('，')),
+    levels: state.levels.map(normalizePuzzleLevelForSave),
+  };
+}
+
+function isBlankPuzzleLevel(level: PuzzleDraftLevel) {
+  return (
+    !level.levelName.trim() &&
+    !level.pictureDescription.trim() &&
+    !level.pictureReference?.trim() &&
+    !level.uiBackgroundPrompt?.trim() &&
+    !level.uiBackgroundImageSrc?.trim() &&
+    !level.uiBackgroundImageObjectKey?.trim() &&
+    !level.levelSceneImageSrc?.trim() &&
+    !level.levelSceneImageObjectKey?.trim() &&
+    !level.uiSpritesheetImageSrc?.trim() &&
+    !level.uiSpritesheetImageObjectKey?.trim() &&
+    !level.levelBackgroundImageSrc?.trim() &&
+    !level.levelBackgroundImageObjectKey?.trim() &&
+    !level.selectedCandidateId?.trim() &&
+    !level.coverImageSrc?.trim() &&
+    !level.coverAssetId?.trim() &&
+    !level.backgroundMusic &&
+    level.candidates.length === 0 &&
+    (level.generationStatus || 'idle') === 'idle'
+  );
+}
+
+function removeUnsavedBlankPuzzleLevels(
+  state: DraftEditState,
+  originalState: DraftEditState,
+) {
+  const originalLevelIds = new Set(
+    originalState.levels.map((level) => level.levelId),
+  );
+  return {
+    ...state,
+    levels: state.levels.filter(
+      (level) =>
+        originalLevelIds.has(level.levelId) || !isBlankPuzzleLevel(level),
+    ),
+  };
+}
+
 function buildFallbackLevelFromDraft(
   draft: PuzzleResultDraft,
 ): PuzzleDraftLevel {
@@ -261,13 +351,20 @@ function mergeDraftEditStateWithIncomingState(
       incomingLevel?.generationStatus !== 'generating'
     );
   });
+  const hasLocalBlankLevel = currentState.levels.some(
+    (level) =>
+      !incomingLevelsById.has(level.levelId) && isBlankPuzzleLevel(level),
+  );
 
-  if (!shouldPreserveLocalEdits) {
+  if (!shouldPreserveLocalEdits && !hasLocalBlankLevel) {
     return incomingState;
   }
 
   const mergedLevels = currentState.levels.map((level) => {
     const incomingLevel = incomingLevelsById.get(level.levelId);
+    if (!incomingLevel && isBlankPuzzleLevel(level)) {
+      return level;
+    }
     if (
       !incomingLevel ||
       level.generationStatus !== 'generating' ||
@@ -1411,36 +1508,17 @@ export function PuzzleResultView({
       return;
     }
 
-    const normalizedState: DraftEditState = {
-      ...editState,
-      workTitle: editState.workTitle.trim(),
-      workDescription: editState.workDescription.trim(),
-      themeTags: normalizeThemeTagInput(editState.themeTags.join('，')),
-      levels: editState.levels.map((level) => ({
-        ...level,
-        levelName: level.levelName.trim(),
-        pictureDescription: level.pictureDescription.trim(),
-        pictureReference: level.pictureReference?.trim() || null,
-        uiBackgroundPrompt: level.uiBackgroundPrompt?.trim() || null,
-        uiBackgroundImageSrc: level.uiBackgroundImageSrc?.trim() || null,
-        uiBackgroundImageObjectKey:
-          level.uiBackgroundImageObjectKey?.trim() || null,
-        levelSceneImageSrc: level.levelSceneImageSrc?.trim() || null,
-        levelSceneImageObjectKey:
-          level.levelSceneImageObjectKey?.trim() || null,
-        uiSpritesheetImageSrc: level.uiSpritesheetImageSrc?.trim() || null,
-        uiSpritesheetImageObjectKey:
-          level.uiSpritesheetImageObjectKey?.trim() || null,
-        levelBackgroundImageSrc: level.levelBackgroundImageSrc?.trim() || null,
-        levelBackgroundImageObjectKey:
-          level.levelBackgroundImageObjectKey?.trim() || null,
-        generationStatus: level.generationStatus || 'idle',
-      })),
-    };
     const originalState =
       savedEditStateRef.current ?? createDraftEditState(draft);
+    const normalizedOriginalState =
+      normalizeDraftEditStateForSave(originalState);
+    const normalizedState = removeUnsavedBlankPuzzleLevels(
+      normalizeDraftEditStateForSave(editState),
+      normalizedOriginalState,
+    );
     const changed =
-      JSON.stringify(normalizedState) !== JSON.stringify(originalState);
+      JSON.stringify(normalizedState) !==
+      JSON.stringify(normalizedOriginalState);
 
     if (!changed || normalizedState.levels.length <= 0) {
       return;