修 gitlint 门禁在 CI 空转：runner 无 git 身份致 254 被误报成信息违规

task 31（首次真跑出的 L0）失败与提交信息无关：actions/checkout 把 HOME
指向每次任务的临时目录，SYSTEM 账号没有全局 git 身份，gitlint 在读到任何
规则之前就以 Missing git configuration: please set user.name 退出——254
是配置错误，不是规则违规。旧脚本还把失败原因写死成"标题超 100 字符"，加
上该步 exit 1，后面 26 个钩子一个都没跑。

改三处：① 先探测身份，缺失则用 GIT_CONFIG_COUNT/KEY/VALUE 注入一次性身
份，只进子进程环境、不写任何文件，开发者机器不受影响；② 254 与真实违规
分开报（2 = 门禁没跑起来，1 = 信息确实违规），不再替 gitlint 猜规则；
③ 钩子输出改走 ForEach-Object { "$_" }，避免 PS 5.1 把原生 stderr 包成
ErrorRecord 污染日志。

实测：空 HOME 下同一条命令改前 254、改后 0 failed；正常环境 10 条提交全
过；脚本纯 ASCII、解析 0 错。同批文档：§7 排障表新增本坑与"新建分支首
次 push 不触发 run"，两份变更记录各加一行。

docs/CI/README.md

@@ -81,6 +81,7 @@
 
 | 日期 | 变更 |
 |---|---|
+| 2026-10-12 | 🐛 **首次真跑出 run**：`L0.5` **成功**（`10 runner(s), 647/647, fail=0`，与本地逐字一致）；`L0` **假失败**——gitlint 因 runner 无 git 身份而 `exit 254`（`Missing git configuration: please set user.name`），旧文案把它说成"提交信息违规"，且该步 `exit 1` 连带让 26 个钩子全部没跑。已在 `ci_gitlint_range.ps1` 用 `GIT_CONFIG_*` 注入一次性身份（不写文件）并区分 254/1 退出码。另记：**新建分支的首次 push 不触发 run**，需 `workflow_dispatch` 或再推一个非文档提交。详见指南 §7 |
 | 2026-10-12 | 🔀 本轮 CI 修复随 `master` **合入 `v2-on-ui`**（该分支另有 21 个功能提交；冲突仅 `AGENTS.md` 与 `docs/README.md` 两处，解法是"保留其新版结构 + 把 CI 指针搬进对应位置"）。因该分支门禁更多（**26 钩子 / 10 单测套件** vs master 的 18 / 3），指南里写死的数字已改为**规则 + 分分支快照**，见指南 §6 / §7 / §10 |
 | 2026-10-12 | ✅ 双看门狗缺陷**实测收敛**（管理员 `-StartNow` 清掉 3 个残留 → 单实例、链路恢复、runner online）。另修两处：daemon 日志走 stderr 被 PS 5.1 `2>&1` 包成 ErrorRecord（2 行真日志写成 8 行，每 4 行 3 行噪声）→ 启动器改 `ForEach-Object { "$_" }`；`-Status` 诚实化（非管理员读不到 SYSTEM 进程命令行 → 明说需提权而非谎报"无看门狗"；重启循环判据改看进程存活时长，不再靠不轮转日志的尾部字符串报假警）。详见指南 §7.3 |
 | 2026-10-12 | 🔴 **修复"双看门狗抢 `.runner.lock`"缺陷**：`Unregister-ScheduledTask` 不停旧实例进程 → 孤儿看门狗养着旧 daemon 占锁，新看门狗每 10 秒失败一次，而 runner 网页照样 online、`-Status` 也说"在跑"。现 `-StartNow` 先清残留进程再启动、`-Status` 报重复实例与锁冲突。同日清理机器侧：`config.yaml` 头部错误指引（"改用 sc.exe / New-Service"）改为看门狗口径，删除已废弃的 `deploy_runner_task.ps1` 与 `run_runner.cmd`，`check_env.ps1` 提示同步改指 bootstrap |

docs/CI/远程CI完整指南.md

@@ -1059,7 +1059,8 @@ date +%s   # 对比 last_online
 | `l0-gates` 报 `no Python with a SYSTEM-visible pre-commit` | runner 是 SYSTEM：PATH 上的 python 无 pre-commit、用户级 site 不可见、`.venv` 未入库（§4.1 三重坑） | `ci_runner_bootstrap.ps1 -SetEnv` 写机器级 `DTU_PRECOMMIT_PYTHON`，或把 pre-commit 装进机器级解释器；**改完必须重启 runner** |
 | `l0-gates` 报 `runner missing cppcheck` | 机器 PATH 无 Cppcheck 且无机器级 `DTU_CPPCHECK` | `-SetEnv`（会自动发现 `C:\Program Files\Cppcheck`）或装 `Cppcheck.Cppcheck` |
 | **钩子条数对不上**（CI 报告条数 = 定义数 − 1；2026-10-12 实测 `master` 18 定义 / 17 报告，`v2-on-ui` 26 定义 / 25 报告——**增删钩子的分支必须重算这个差值**） | `gitlint` 的 `stages: [commit-msg]` 写在**上游** `.pre-commit-hooks.yaml`（项目 `.pre-commit-config.yaml` 里 grep 不到，别据此断定"没限制"），`pre-commit run --all-files` **跑不到它**，且表现为全绿——静默空转 | 已由 `scripts/ci_gitlint_range.ps1` 单独校验；**以后增删钩子必须核对"定义数 == 日志条数 + gitlint"** |
-| push 后 Actions 页**空白/无任务** | ① 服务端开关未开 ② workflow 没 push 到远程 ③ 只改了 `docs/**`（被 `paths-ignore` 滤掉） | 逐条核对 §1 / §5.1 / §5.2 |
+| gitlint 步骤 **Failed 但提交信息其实合规**（同一条命令在本地全绿），日志里是 `exit code: 254` + `Missing git configuration: please set user.name` | `actions/checkout` 把 HOME 临时指向每次任务的临时目录，而 SYSTEM 账号没有全局 git 身份 → gitlint **在读到任何规则之前**就因配置错误退出（**254 不是规则违规**）。旧脚本末尾那句 `::error::...rule: single-line Chinese title, < 100 chars` 是**写死的猜测文案**，把环境问题伪装成"提交信息不合格"；且该步 `exit 1` 会让后面的 `--all-files` **整个不跑**——看着像"门禁拦住了"，实际 26 个钩子一个都没执行 | `ci_gitlint_range.ps1` 先探测身份，缺失就用 `GIT_CONFIG_COUNT/KEY/VALUE` 注入一次性身份（**不写任何文件**，开发者机器不受影响），并把 254 与真实违规分开报（**2 = 门禁没跑起来**，1 = 信息确实违规）。实测同一命令：空 HOME 下改前 254、改后 `0 failed`（2026-10-12 task 31 首次暴露） |
+| push 后 Actions 页**空白/无任务** | ① 服务端开关未开 ② workflow 没 push 到远程 ③ 只改了 `docs/**`（被 `paths-ignore` 滤掉） ④ **新建分支的首次 push**（实测 2026-10-12：创建 `v2-on-ui-ci` 那次 push 没产生 run——runner 在线空闲、job 日志零新增；紧接着一次普通 push 立刻出 task。原因：`before` 是全零 SHA，变更文件集算不出来，`paths-ignore` 求值时被滤空） | ①②③ 逐条核对 §1 / §5.1 / §5.2；④ 用 `workflow_dispatch` 手动触发，或再推一个非文档路径的提交 |
 | 任务一直 **Waiting / 排队** | 没有 label 匹配 `windows` 的 runner | 检查 `--labels "windows:host"`；Settings→Runners 是否 Idle |
 | `l0-gates` 报 `::error::runner 缺少：Python, cppcheck` | runner 没装或不在 PATH | 装完后**重启 runner 服务**（新进程才吃到新 PATH） |
 | `checkout` 步骤卡住/超时 | 拉不到 `actions/checkout@v4`（内网） | 见 §5.3 |
@@ -1350,6 +1351,7 @@ powershell -ExecutionPolicy Bypass -File scripts\ci_runner_bootstrap.ps1 -DryRun
 
 | 日期 | 变更 |
 |---|---|
+| 2026-10-12 | 🐛 **第一次真跑出 run，当场暴露 gitlint 门禁空转**：把本轮修复推到新分支 `v2-on-ui-ci` 后拿到 task 31/32——**L0.5 成功**（`10 runner(s), 647/647 assertions passed, fail=0`，与本地逐字一致），**L0 失败**却与提交信息毫无关系：`exit code: 254` + `Missing git configuration: please set user.name`。根因是 `actions/checkout` 把 HOME 指向每次任务的临时目录、SYSTEM 账号没有 git 身份，gitlint 在读到规则之前就配置错误退出；旧脚本还把失败原因**写死**成"标题超 100 字符"，加上该步 `exit 1` 让后面 26 个钩子**一个都没跑**。修法：脚本先探测身份，缺失就用 `GIT_CONFIG_COUNT/KEY/VALUE` 注入一次性身份（不写文件、不碰开发者机器），并区分 254（门禁没跑起来 → `exit 2`）与真实违规（→ `exit 1`）。另记一条新坑：**新建分支的首次 push 不产生 run**（§7 排障表 ④） |
 | 2026-10-12 | 🔀 **随 `master` 合入 `v2-on-ui`：数字口径改为分支中立**。本指南原先写死 master 的数字（18 钩子 / 17 报告、3 runner / 288 断言），而 `v2-on-ui` 是 **26 钩子 / 10 套件**——同一篇文档在两个分支上必然有一个是错的。§6 验收第 8 行、§7 排障表、§10 验收标准三处改为讲规则（**报告数 = 定义数 − 1**；**runner 数 = `test/host/` 下 `run_unit_test.py` 个数**）+ 分分支实测快照。本次合并只带文档与脚本，**零 C 代码改动**；合并后本分支 `@build` 0 错 0 警、`ci_local.py` 全绿（L0 25 钩子 + L0.5 10 runner / 647 断言） |
 | 2026-10-12 | ✅ **双看门狗缺陷实测收敛** + 修掉日志里的 PS 5.1 stderr 包装噪声与 `-Status` 假警。① 管理员 `-StartNow` 杀掉 3 个残留（孤儿看门狗 26900/19716 + 占锁 daemon 53848）→ `daemon up: pid 40360 (single instance)`，监管链 `svchost → 看门狗 → daemon`，看门狗日志 25 秒零增长、runner 回 online。② 新坑：daemon 日志写 **stderr**，PS 5.1 的 `2>&1` 把每行包成 ErrorRecord → `gitea-runner.exe : ` 前缀 + 4 行 `CategoryInfo` 块，实测 2 行真日志写成 8 行（**每 4 行有 3 行是噪声**，且就在文档让大家第一个打开的文件里）。启动器改为 `2>&1 \| ForEach-Object { "$_" } \| Out-File -Encoding utf8`（实测与 cmd 包装等价但免引号剥离坑，`$LASTEXITCODE` 不受影响）；§7.2 方式 B 的示例原本正是 `> log 2>&1`（UTF-16LE + 包装双坑），已改；新增 §7.3 汇总这两条。③ `-Status` 两处诚实化：非管理员**读不到 SYSTEM 进程命令行**（`CommandLine` 为 null → 过滤器静默匹配 0 个），改为明说"需提权"而不是谎报"没有看门狗"；重启循环判据不再靠"日志尾部有没有错误串"（文件不轮转，修好后旧失败仍在尾部 → 对健康 runner 报假警），改看 **daemon 进程存活时长**（CIM `CreationDate` 非管理员可读，`Process.StartTime` 对 SYSTEM 进程不可读） |
 | 2026-10-12 | 🔴 **实测揪出"双看门狗抢锁"缺陷并修复** + 机器侧清理。① 现象：runner 网页 online、`-Status` 说 daemon 在跑，但 `runner-watchdog.log` 每 10 秒刷 `starting daemon → daemon exited, exit code 1`，daemon 日志 `runner file is already locked by another process`。② 根因：`Unregister-ScheduledTask` **不停旧实例启动的进程**——13:22 重跑 bootstrap 时旧看门狗(12:53 起)成孤儿并继续养着旧 daemon、占住 `.runner.lock`，新看门狗永远抢不到锁，任务实际谁也没管，日志以约 20 MB/天在刷。③ 修复：`ci_runner_bootstrap.ps1` 的 `-StartNow` 现在**先停孤儿看门狗与残留 daemon 再启动**并回显单实例确认；`-Status` 新增重复实例计数与锁冲突检测。④ 机器侧清理：`config.yaml` 头部那句**错误指引**（"常驻改用 Windows sc.exe / New-Service"，正是 §3.0 证伪的路）改为看门狗口径并指向本文；删除已废弃的 `deploy_runner_task.ps1` 与 `run_runner.cmd`（§3.2），`check_env.ps1` 指向它们的提示同步改指 bootstrap。⑤ 核实：`config.yaml` 改后 YAML 可解析且**所有配置值与改前逐项一致**（只动注释）；`check_env.ps1` 带 BOM 且语法 0 错；删除前确认计划任务动作目标是 `run_runner_watchdog.ps1`，删除不影响在跑 runner |

scripts/ci_gitlint_range.ps1

@@ -6,12 +6,13 @@
 .DESCRIPTION
     Why this file exists (2026-10-11 CI audit):
 
-    .pre-commit-config.yaml defines 17 hooks, but CI reported 16
+    CI always reports ONE hook fewer than .pre-commit-config.yaml defines
-    (passed=15 failed=0 skipped=1). The missing one was `gitlint`: its hook
+    (measured 2026-10-12: master 18 defined / 17 reported, v2-on-ui 26 / 25).
-    definition declares `stages: [commit-msg]`, while `pre-commit run
+    The missing one is `gitlint`: its hook definition declares
-    --all-files` only runs the `pre-commit` stage. So the commit-message rule
+    `stages: [commit-msg]`, while `pre-commit run --all-files` only runs the
-    from AGENTS.md (single-line Chinese title < 100 chars) was enforced on
+    `pre-commit` stage. So the commit-message rule from AGENTS.md (title
-    developer machines and NEVER in CI -- a silent gate gap, not a failure.
+    < 100 chars, body lines <= 80) was enforced on developer machines and
+    NEVER in CI -- a silent gate gap, not a failure.
 
     pre-commit cannot check "the commits of this push" on its own, so this
     script feeds each commit message to the hook through
@@ -78,6 +79,35 @@ try {
         $PythonExe = "$PythonExe".Trim()
         Write-Host "gitlint: using python $PythonExe"
 
+        # --- git identity guard ---------------------------------------------
+        # Measured on CI 2026-10-12 (task 31): actions/checkout points HOME at
+        # a per-job temp dir and the SYSTEM account has no global identity, so
+        # gitlint aborted with "Missing git configuration: please set
+        # user.name" and exit code 254 BEFORE reading a single rule. Every push
+        # failed this gate no matter how good the message was, and the log made
+        # it look like a message violation.
+        # Inject a throwaway identity through GIT_CONFIG_* (git >= 2.31): it is
+        # inherited by the child git processes only, so NO file is written and
+        # a developer machine keeps its own identity untouched. gitlint needs
+        # an identity merely to start; it does not judge the author.
+        $savedPref = $ErrorActionPreference
+        $ErrorActionPreference = 'Continue'
+        $idName  = git config user.name 2>$null
+        $idMail  = git config user.email 2>$null
+        $ErrorActionPreference = $savedPref
+        if (-not "$idName".Trim() -or -not "$idMail".Trim()) {
+            if ($env:GIT_CONFIG_COUNT) {
+                Write-Host '::warning::gitlint: GIT_CONFIG_* already set by the caller -- leaving it alone'
+            } else {
+                $env:GIT_CONFIG_COUNT   = '2'
+                $env:GIT_CONFIG_KEY_0   = 'user.name'
+                $env:GIT_CONFIG_VALUE_0 = 'dtu-ci'
+                $env:GIT_CONFIG_KEY_1   = 'user.email'
+                $env:GIT_CONFIG_VALUE_1 = 'dtu-ci@invalid.local'
+                Write-Host '::warning::gitlint: no git identity here -- injected a throwaway one via GIT_CONFIG_* (needed only so gitlint can start)'
+            }
+        }
+
         # --- resolve the commit range ---------------------------------------
         $range = ''
         $cleanBase = "$BaseSha".Trim()
@@ -115,6 +145,7 @@ try {
 
         $checked = 0
         $failed = 0
+        $gateBroken = $false
         foreach ($sha in $shas) {
             $sha = "$sha".Trim()
             $checked++
@@ -134,12 +165,22 @@ try {
 
             $savedPref = $ErrorActionPreference
             $ErrorActionPreference = 'Continue'
-            & $PythonExe -s -m pre_commit run --hook-stage commit-msg `
+            # ForEach-Object { "$_" } unwraps the ErrorRecords that PS 5.1's
-                --commit-msg-filename $msgPath gitlint 2>&1
+            # 2>&1 builds for every native stderr line, without disturbing
+            # $LASTEXITCODE (docs/CI guide, section 7.3).
+            $hookOut = & $PythonExe -s -m pre_commit run --hook-stage commit-msg `
+                --commit-msg-filename $msgPath gitlint 2>&1 | ForEach-Object { "$_" }
             $rc = $LASTEXITCODE
             $ErrorActionPreference = $savedPref
+            $hookOut | ForEach-Object { Write-Host $_ }
 
-            if ($rc -ne 0) {
+            if ($rc -eq 254 -or ($hookOut -match 'Missing git configuration')) {
+                # The gate itself could not run. Never report that as a
+                # message violation -- it is a runner/environment fault and
+                # needs a different fix (see the identity guard above).
+                Write-Host "::error::gitlint: GATE BROKEN (exit $rc, git config error) at $($sha.Substring(0, 8)) -- NOT a message violation"
+                $gateBroken = $true
+            } elseif ($rc -ne 0) {
                 $failed++
                 Write-Host "::error::gitlint: commit $($sha.Substring(0, 8)) rejected -- `"$titleLine`""
             }
@@ -152,8 +193,12 @@ try {
             Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $summary -Encoding utf8
         }
 
+        if ($gateBroken) {
+            Write-Host '::error::commit message gate could not RUN -- fix the runner git identity; do NOT read this as a message violation'
+            exit 2
+        }
         if ($failed -gt 0) {
-            Write-Host '::error::commit message gate failed -- rule: single-line Chinese title, < 100 chars (see docs/ pre-commit usage guide + .gitlint)'
+            Write-Host '::error::commit message gate failed -- see the gitlint output above for the exact rule id (rules in .gitlint; AGENTS.md: title <= 100 chars, body lines <= 80)'
             exit 1
         }
         exit 0