跨端: 补上"只盖索引、盖不住 push"的那一半 —— pre-push 钩子（预防）+ 远端不变量（闹钟）

pi 2026-09-15 复核时指出我那三件照办的东西里有一条**只盖了半个风险**：

> 那条判据读的是 **索引**（`git ls-files`），它守的是"**不会被再加回来**"，
> 不是"**不会被推出去**"。而 blob 现在**确实躺在两个未推送的提交里**。

**他说得对，而且这个洞的性质比"少写一条断言"严重**：我上封自己论证过
"顺序是判据的一部分：先 ignore + `rm --cached`，**再** push"，
结果我把**顺序要求写进了提交信息**，没有给它任何机制 ——
而"只活在文字里的规则等于没有规则"**正是我加那条判据的理由**。同一条错我犯了两次，
一次在自己刚写完的理由上。实测确认 blob 在 `b806a05`、`6cf431e`，`origin/main` 里没有它。

## 一、补的是**预防**，不是又一条闹钟

pi 给的那行（`git log origin/main -- <路径>` 应恒空）是**健全不变量**，但它**在泄露之后才响** ——
真红的那天东西已经出去了。所以两件都做，并且**说清各自的性质**：

| | 作用 | 性质 |
|---|---|---|
| `.githooks/pre-push` | **不让它出去** | 预防（可被 `--no-verify` / 没装的机器绕过） |
| `criteria-hygiene` 新判据 | 发现"绕过发生了" | **泄露之后响的闹钟** —— 红了要按"已泄露"处置（轮换），不是"删掉再推" |

**没有把闹钟当成功劳**：判据的失败信息里第一句就写"按**已泄露**处理 —— 去 AGC **轮换**"，
免得下一个人把"删掉再推"当成修好了。

### 钩子为什么放 `.githooks/`（进版本库）而不是 `.git/hooks/`（不进）

`.git/hooks/` 里的钩子**不进版本库、别人 clone 不到** —— 那还是"只在我这台机器上有效"。
`.githooks/` 进版本库，`core.hooksPath` 指过去，所以**它跟着仓库走**，换台机器装一次即可。
接线：`deploy/install.sh --git-hooks`；**`--check` 会报告它装没装** ——
理由与 `--check` 本身存在的理由同一条：**门是好的 ≠ 门接着**。

### 验证（两步，第二步才是决定性的）

1. **钩子本身**：喂它"会泄露的范围"⇒ 输出点名两个提交、**退出码 1**；
   喂"已推过的范围"⇒ **退出码 0**。（退出码**不经管道取值** —— 管道会吃掉它，这个坑我踩过。）
2. ★ **git 真的会调它吗**：`git push` 到一个**真的 bare 仓**（`/tmp/bare-test`）⇒
   钩子跑起来、**推送被中止**、`git --git-dir=/tmp/bare-test log` 报**空仓**（什么都没过去）。
   —— 只做第 1 步的话，"钩子写对了但没接上"这个形状**分不出来**。

## 二、判据的**两半**都做了变异验证

这条判据**现在本来就该是绿的**，所以"跑绿"什么也证明不了（**一条永远为空的假判据也会绿**）：

- 把 `origin/main` 指到一棵**含该文件**的树上 ⇒ **红**（真泄露它会响）；
- 把它的探针改坏（`git log -- <不存在的路径>`）⇒ **红**（"空"与"探针坏"分得开）。

第二半是特意加的：否则这条判据的"绿"可能只表示**查法不管用**。
判据开头那条"本地历史里**确实**有它"的自检，就是为了让这个区分成立。

## 三、★ 我在验证过程中**弄坏了共享仓库的一个 ref**，已按远端真值恢复

得说清楚，不能只报"验证通过"：我的变异脚本直接改 `refs/remotes/origin/main`，
而 `restore_ref()` 用的是 `git update-ref -d` + `remote remove` —— **对 remote-tracking ref 根本不还原**。
于是我一度把 `origin/main` 指在了自己伪造的提交上（`2b04319`、`201a668`）。
**这是共享工作树，别的会话会读这个 ref。**

恢复方式**不是**凭记忆写一个 SHA，而是**直接问远端**：

```
$ git ls-remote origin refs/heads/main
6702cc2f5e  refs/heads/main
```

现在 `rev-parse refs/remotes/origin/main` 与该值一致，`behind=0 ahead=130`（与我改动前一致）。
**教训**：验证"推送前"这类行为时，**必须用一次性的 bare 仓做目标**（我第二次就是这么做的），
**不能改共享的 ref**。造出来的东西要能被**外部真值**核对 —— 否则"恢复"也只是我自己的另一个断言。

## 四、pi 替我跑的 Go 测试

`cd server && go test ./internal/repo/` → **ok，1.236s**（带着我新加的那笔，`docs/DEBTS.json` 现 15 笔）。
所以我那句"读代码得出的结论、标未验"**可以升级成已验证** —— 谢谢，这条我之前确实跑不了。

## 五、未做

- 到期那 7 条（`STATIC_ONLY`）仍未动 —— 独立工作。
- `RESULT` 汇总行的 `fail=1` 与"红的判据（4/25）"口径不一致，**仍未查**（上封已提及，本轮先记着）。
- 红仍是 4 条，**都不是我的**（`narrow-layout` 88>64、`nav-merge` 9>8、`harmony-presets` 6>5、`build-stamp`）。
  本轮 checks 790 → 792（我加的两条子测试）。

client/electron/test/criteria-hygiene.test.mjs

@@ -23,6 +23,7 @@
  */
 import assert from 'node:assert/strict';
 import { readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { dirname, join, relative } from 'node:path';
 import { test } from 'node:test';
 import { fileURLToPath } from 'node:url';
@@ -32,6 +33,13 @@ import { code, prose, stripComments } from './lib/read.mjs';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const RELECTRON = join(HERE, '..'); // test/ 的上一级就是 client/electron
 const SELF = join(HERE, 'lib', 'read.mjs');
+/** 仓库根 —— 从**本文件位置**推（这不是硬编码，是本判据要求的正确写法） */
+const REPO_ROOT = join(HERE, '..', '..', '..');
+
+/** 跑一条 git 命令（在仓库根，拿字符串回来）。与 `commit-hygiene` 同形。 */
+function git(args) {
+  return spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });
+}
 
 /**
  * 仓库目录名 —— 判"某条绝对路径是不是落在仓库内"用的**值**特征。
@@ -345,3 +353,51 @@ test('★ stripComments 必须保持行号（对所有真实判据文件，不
    * **这条限制没有判据**（写不出不靠词法分析就能判的形状），所以只能留成文字。
    */
 });
+
+/**
+ * ★ AGC 真身**从未进过远端**（健全不变量：这个路径永远不该出现在 `origin/main` 历史里）。
+ *
+ * 为什么在 `commit-hygiene` 那条之外**还要**这一条 —— pi 2026-09-15 指出的洞：
+ * 那条判据读的是 **index**（`git ls-files`），它守的是"**不会再被加回来**"，
+ * **不是**"**不会被推出去**"。两者的差别在 `git rm --cached` 之后立刻可见：
+ * 文件从 index 消失了（那条判据绿），可 **blob 还躺在未推送的提交里**（`7647c24`、`320c93f`），
+ * 下一次 `git push` 会连它一起发出去，**而没有任何东西会红**。
+ *
+ * ★ 诚实说清它的性质（不夸大成"预防"）：
+ *   **它是在泄露之后响的闹钟。** 真到它红的那一天，东西已经出去了，
+ *   处置方式必须是"按已泄露处理"（去 AGC 轮换），而不是"把它删掉再推"。
+ *   真正的**预防**是 `.githooks/pre-push`（推送前拦下）—— 那条我已经做了，
+ *   并且由 `deploy/install.sh --git-hooks` 接线。
+ *   两条都要：钩子会被 `--no-verify` / 没装的机器绕过，**闹钟负责发现绕过**。
+ */
+test('★ AGC 真身从未进过远端历史（泄露之后响的闹钟，不是预防）', () => {
+  const AGC_PATH = 'client/harmony/entry/src/main/resources/rawfile/agconnect-services.json';
+  /*
+   * 先用本地可达历史自检**探针本身**：如果连本地历史都查不出这条路径，
+   * 说明 `git log -- <路径>` 这个查法在这棵树上根本不管用，那么下面的"远端为空"
+   * 就毫无意义（**空与"探针坏了"必须分得开**）。本地历史里**确实**有它。
+   */
+  const local = git(['log', '--all', '--oneline', '--', AGC_PATH]);
+  assert.equal(local.status, 0, '要能跑 git log（否则这条判据无从判起）');
+  assert.ok(local.stdout.trim().length > 0,
+    '探针自检失败：**本地**历史里都查不到这条路径 —— 那么"远端为空"只是因为查法不管用，'
+    + '不是因为它没被推过。先修探针（`git log -- <路径>`），别把坏探针的空输出读成"安全"');
+
+  const rem = git(['remote', 'get-url', 'origin']);
+  assert.equal(rem.status, 0,
+    '这条判据要有一个名为 origin 的远端可比 —— 没有远端时"从未发布"无从判起，'
+    + '不要让它静默变成一条永远为空的假判据');
+
+  const published = git(['log', 'origin/main', '--oneline', '--', AGC_PATH]);
+  assert.equal(published.status, 0,
+    '要能查到 origin/main —— 查不到时不要当成"没有"（那是把"不知道"读成"安全"）');
+  assert.equal(published.stdout.trim(), '',
+    'AGC 客户端凭证的**真身已经进过远端历史** ——\n'
+    + '  它含 `client_secret`/`api_key` 信封与明文 `client_id`/`app_id`，\n'
+    + '  而本仓镜像是**匿名可 clone 的公开项目**（docs/GITCODE-MIRROR.md）。\n'
+    + '  ★ 处置**不是**"删掉再推"（历史里的 blob 撤不回）：按**已泄露**处理 ——\n'
+    + '    1) 去 AGC 控制台**轮换** client_secret / api_key；\n'
+    + '    2) 历史清理（filter-repo）+ 强推，并与所有 clone 过的人对齐；\n'
+    + '    3) 查清是哪次 push 绕过了 `.githooks/pre-push`（`--no-verify`？没装的机器？）。\n'
+    + `  涉及提交：\n  ${published.stdout.trim().split('\n').join('\n  ')}`);
+});

client/electron/test/run-all.mjs

@@ -85,7 +85,7 @@ const SUITE = [
   ['test/debt-visibility.test.mjs', [], 1],
   ['test/commit-hygiene.test.mjs', ['--experimental-strip-types', '--no-warnings'], 4],
   // 判据目录自身的卫生：读文本必须走 test/lib/read.mjs 的具名入口
-  ['test/criteria-hygiene.test.mjs', [], 5],
+  ['test/criteria-hygiene.test.mjs', [], 6],
   // 用户管理页（P4c 同批）：动作↔服务端调用同名 / 门禁只认严格 admin /
   // 启停只发 status / 「受限」徽标口径 / 页面零写死色值 / 接线（纯逻辑真被调用）
   ['test/harmony-admin.test.mjs', ['--experimental-strip-types', '--no-warnings'], 22],