diff --git a/deploy/install.sh b/deploy/install.sh
index 008fc51..149757e 100755
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -424,10 +424,37 @@ if [[ $CHECK_ONLY -eq 1 ]]; then
   fi
   # 环境不再在这里逐个预检 —— 开头 source 的 env-defaults.sh 已经保证
   # HOME/TMPDIR/GOMODCACHE/PATH 齐备（那道预检是"第四次"的补丁，已被一处取代）。
-  if ! ( cd "$REPO/server" && go vet ./... && go test ./... ); then
+  # ★★ 环境失败**不许冒充代码缺陷**（pi 2026-09-15；规矩本来就在 `lib/env-defaults.sh:25`：
+  #   "失败要说清是环境问题…不要让它冒充代码缺陷"）。
+  #
+  #   实测过的形状：`go vet ./...` 报
+  #     internal/middleware/auth.go:9:2: open /root/.cache/go-build/55/…-d: permission denied
+  #   —— 它**指着源码文件**说 permission denied，而一行 .go 都没问题；跟着本步原来那句
+  #   "不过 —— 先修好再安装" 就把人送去改代码。pi 用 `go vet ./internal/repo/`（通过）
+  #   vs `go vet ./...`（死在缓存条目）两条命令就分开了 ⇒ 真因是 build 缓存不可用。
+  #
+  #   现在**两道**：① `env-defaults.sh` 的 ③c 预检 GOCACHE（可写、探针实测）；
+  #   ② 这里按**输出分类**兜住剩下的（预检过不了的在 ① 就 exit 2 了，这里是二手保险）。
+  #   分类命中 ⇒ 退出码 **2（环境）**，并且**不再说"先修好"**。
+  GOOUT="$(mktemp -t agentmail-govet-XXXXXX)"
+  if ! ( cd "$REPO/server" && go vet ./... && go test ./... ) >"$GOOUT" 2>&1; then
+    cat "$GOOUT" >&2
+    # ⚠️ 分类必须在 `rm` **之前**读那个文件 —— 先删再 grep 会让这条分类**永远不触发**
+    #    （那正是本仓反复出现的形状：判据存在但永远不会响）。
+    if grep -qE 'permission denied|cannot find (package|module)|no space left on device|module cache not found|build cache is required|GOCACHE' "$GOOUT"; then
+      rm -f "$GOOUT"
+      echo "  [FAIL] go vet / go test **跑不起来**（环境问题，不是代码缺陷）" >&2
+      echo "         上面报错里出现了缓存/权限/空间类的字样 —— 它常常**指着源码文件**报错，" >&2
+      echo "         但一行 .go 都没问题（实测形状：open <GOCACHE>/…-d: permission denied）。" >&2
+      echo "         药方：GOCACHE=<可写目录> 重跑。按仓库约定这算**环境**（退出码 2）。" >&2
+      exit 2
+    fi
+    rm -f "$GOOUT"
     echo "  [FAIL] go vet / go test 不过 —— 先修好再安装" >&2
+    echo "         （本次输出里**没有**缓存/权限/空间类字样 ⇒ 按**代码缺陷**处理。）" >&2
     exit 1
   fi
+  rm -f "$GOOUT"
   echo "  [ OK ] go vet + go test 通过"
   cat <<'EOF'
 
diff --git a/deploy/lib/env-defaults.sh b/deploy/lib/env-defaults.sh
index ac619db..848ad4a 100644
--- a/deploy/lib/env-defaults.sh
+++ b/deploy/lib/env-defaults.sh
@@ -168,6 +168,75 @@ fi
 
 export AGENTMAIL_ENV_DEFAULTS="${AGENTMAIL_ENV_DEFAULTS# }"
 
+# ③c `GOCACHE`（go 的 **build** 缓存）—— pi 评审 2026-09-15 指出的**缺项**。
+#
+# ★ 上面 ③ 预检的是 `GOMODCACHE`/`GOPATH`（**模块**缓存），而 `go vet`/`go test`/`go build`
+#   还要用 **build** 缓存。缺了/不可用时的报错长这样：
+#
+#     internal/middleware/auth.go:9:2: open /root/.cache/go-build/55/559b2f74…-d: permission denied
+#
+#   —— 它**指着源码文件**说 permission denied，看起来完全像代码缺陷；而 `install.sh` 那一步
+#   接着打 `[FAIL] go vet / go test 不过 —— **先修好再安装**` ⇒ 把人送去改代码。
+#   pi 一条命令就把它分开了：`go vet ./internal/repo/` 通过、`go vet ./...` 死在缓存条目上
+#   ⇒ 真因是 build 缓存不可用，**不是任何 .go 文件有问题**。
+#   **这正是本文件上面第 25 行那条纪律要拦的东西**：
+#   "失败要**说清是环境问题**…**不要让它冒充代码缺陷**"。
+#
+# ★ 为什么必须**实测可写**而不是只判 `-d`：build cache 是**要写**的（未命中就写条目）。
+#   只判存在 ⇒ 目录在就放行，go 一写就 EACCES —— 本仓那条老毛病
+#   （见 ① HOME 的注释："对已存在的不可写目录，`mkdir -p` 会返回成功 ⇒ 必须单独判 `-w`"）。
+#
+# ⚠️ `go env GOCACHE` 可能返回字面量 `off`（实测：本机沙箱下就是 `off`）——
+#   那**不是目录**，按"拿不到可用的 build 缓存"处理，**不要**把 `off` 读成"用户特意关掉了、
+#   所以放行"：此时 go 确实用不了缓存，报错照样会冒充代码缺陷。
+if command -v go >/dev/null 2>&1; then
+  # 口径与本文件一致（**只设未设的**）：GOCACHE 已给就用它，没给才推导。
+  _am_gocache="${GOCACHE:-}"
+  if [ -z "$_am_gocache" ]; then
+    # 与 go 自己的默认同式：`$XDG_CACHE_HOME` 优先，否则 `$HOME/.cache`。
+    # ⚠️ **不能只靠 `go env GOCACHE`**：本机实测它在沙箱里返回字面量 `off`
+    #   （HOME 对 go 不可用时的表现），而 `HOME`/`XDG_CACHE_HOME` 都可用时它返回正常路径。
+    _am_gocache="${XDG_CACHE_HOME:-$HOME/.cache}/go-build"
+    GOCACHE="$_am_gocache"
+    export GOCACHE
+    AGENTMAIL_ENV_DEFAULTS="$AGENTMAIL_ENV_DEFAULTS GOCACHE=$GOCACHE"
+  fi
+  # ⚠️⚠️ **必须判"是绝对路径"** —— 这是我实测踩到的：`go env GOCACHE` 在本沙箱里返回
+  #   字面量 `off`，而我第一版直接 `mkdir -p "$_am_gocache"` ⇒ **在当前目录里造出一个 ./off**！
+  #   探针去写一个相对路径必然"成功" ⇒ 判据**假绿**，而且**留下副作用**
+  #   （"预检"自己改了工作树 —— 正是本仓刚从 `dist`/`gen:bg` 上修掉的那一类）。
+  #   ⇒ 非绝对路径**不可能是** go 真正会用的缓存目录 ⇒ 按"拿不到可用缓存"处理。
+  case "$_am_gocache" in
+    /*) : ;;
+    *)
+      printf '\n  [FAIL] 环境不足：GOCACHE 不是绝对路径（实得「%s」）\n' "$_am_gocache" >&2
+      printf '         这是**环境问题**，不是代码问题。\n' >&2
+      printf '         本机实测：沙箱里 `go env GOCACHE` 会给出字面量 `off` —— 那表示**它用不了 build 缓存**。\n' >&2
+      printf '         药方：GOCACHE=<可写目录的绝对路径> 重跑。\n' >&2
+      exit 2
+      ;;
+  esac
+  mkdir -p "$_am_gocache" 2>/dev/null || true
+  # 真的写一个探针文件 —— 与 go 自己要做的事**同形**（不只看权限位；root 无视权限位，`-w` 骗人）。
+  #
+  # ⚠️⚠️ **不要用 `set -e` 做这件事**（我第一版就是这么写的，**探针恒绿**）：
+  #   `if ! ( set -e; … )` 里那个子壳是**条件的一部分**，而 bash 在条件上下文里
+  #   **抑制 errexit**  ⇒ 写失败也不中止 ⇒ 子壳最后一条命令（`rm -f`）返回 0 ⇒
+  #   判据永远说"能写"。实测：`GOCACHE=/proc/self/nonexistent-gc` 时
+  #   `mkdir` 与重定向**都报 No such file or directory**，而探针 rc=0。
+  #   ⇒ 用**显式**的 `|| exit 1`，把失败直接变成退出码，不依赖 shell 选项的上下文语义。
+  if ! ( { : > "$_am_gocache/.agentmail-probe"; } 2>/dev/null || exit 1; rm -f "$_am_gocache/.agentmail-probe" ); then
+    printf '\n  [FAIL] 环境不足：GOCACHE=%s 不存在或不可写\n' "$_am_gocache" >&2
+    printf '         这是**环境问题**，不是代码问题。\n' >&2
+    printf '         症状（会冒充代码缺陷）：`go vet ./...` 报\n' >&2
+    printf '           internal/…: open %s/…-d: permission denied\n' "$_am_gocache" >&2
+    printf '         —— 它指着源码文件说 permission denied，而实际一行 .go 都没问题。\n' >&2
+    printf '         药方：GOCACHE=<可写目录> 重跑（或修 %s 的权限）。\n' "$_am_gocache" >&2
+    exit 2
+  fi
+  unset _am_gocache
+fi
+
 # ②b TMPDIR **可写 + 有空间** —— 与 ① HOME 同一条规则，必须一起落。
 #
 # ★ pi 评审 2026-09-14：① 那边我写了"`mkdir -p` 对已存在的不可写目录会返回成功 ⇒ 必须单独判 `-w`"，