雲端零閘的兩個真因：setup 從不驗證自己＋沒有任何 release 撐版本號

2026-08-20 雲端 session 的閘全滅，而三個驗證步驟全部回綠。
今晚在隔離 HOME（GIT_CONFIG_NOSYSTEM=1）重現，把兩件事分開了：

① setup script 的寫法是對的
   裸環境失敗、加了 url.insteadOf 就成功 —— x-access-token 這個使用者名稱
   Gitea 也接受。所以先前我對 leo 說「URL 重寫沒作用到 marketplace 這條路徑」
   是錯的，這裡更正。
   （前兩次測試之所以誤導，是因為 /etc/gitconfig 的 macOS keychain helper
   還在幫忙 —— 「隔離 HOME」並沒有隔離系統層設定。同一個病第三次。）

② 真正的缺陷是這支腳本從不驗證自己
   設完就結束。token 沒生效也不出聲 ⇒ setup log 一片綠、
   session 開起來才發現 marketplace 拉不下來，而那時已經沒有任何線索。
   本次加兩道自我驗證：git 認證通不通、marketplace 有沒有就位，
   任一不通就 exit 1 並印出該查什麼。

③ 新增 isep-presence-beacon.sh（信標，不是閘）
   SessionStart 報「ISEP v幾 已載入、幾支閘」。
   它的全部意義是鑑別力：這行住在 plugin 裡，所以看得到就一定載入了，
   看不到就是零閘。不像 git tag（在三支閘的白名單裡，閘死了照樣過）。

④ plugin.json 0.0.0 → 0.3.0
   查清楚了：0.0.0 不是漂移，是誠實 —— ISEP 一個 tag 都沒有，從沒發過 release。
   而這正是「雲端拿不到更新」的另一半：claude plugin update 比對版本號，
   沒有 release 就永遠沒有新號碼可比。所以這一刀的收工是真的打 tag 發版。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/cloud-setup-script.sh

@@ -27,12 +27,46 @@ if [ -z "${GITEA_TOKEN_CLAUDE_CODE:-}" ]; then
   exit 1
 fi
 
-# 官方文件建議的私有 marketplace 認證寫法：只重寫這個 host 的 URL，不動其他 git 操作。
-git config --global url."https://x-access-token:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
+# ── git 認證：三個機制都設，因為它們失效的方式不同 ────────────────
+#   ① URL 重寫（global）  ② 憑證存檔（global）  ③ 系統層（HOME 無關，best effort）
+# 2026-08-20 雲端實測：session 裡 git 是「匿名」的 ⇒ setup 設的東西沒生效到 session。
+# 原因未定（沒跑到／HOME 不同／快照沒帶），所以三條都設，並在下面自我驗證。
+git config --global url."https://claude-code:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
   "https://git.uncle6.me/"
+git config --global credential.helper store
+printf 'https://claude-code:%s@git.uncle6.me\n' "$GITEA_TOKEN_CLAUDE_CODE" > "$HOME/.git-credentials"
+chmod 600 "$HOME/.git-credentials"
+git config --system url."https://claude-code:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
+  "https://git.uncle6.me/" 2>/dev/null || echo "（system 層設不了，只靠 global——非致命）"
 
-# 用乾淨網址（不帶 token）加 marketplace，實際認證交給上面那條 URL 重寫。
-claude plugin marketplace add https://git.uncle6.me/inkstone/ISEP.git --scope user
-claude plugin install isep@inkstone --scope user
+# ── 🔴 自我驗證一：認證真的通了嗎 ──────────────────────────
+# 這一步是 2026-08-20 事故的直接產物：舊版設完就結束，token 沒生效也不出聲，
+# 於是雲端 session 開起來才發現 marketplace 拉不下來，而 setup log 一片綠。
+echo "── 驗證 git 認證 ──"
+if GIT_TERMINAL_PROMPT=0 git ls-remote https://git.uncle6.me/inkstone/ISEP.git >/dev/null 2>&1; then
+  echo "✅ git 認證通：拉得到 inkstone/ISEP"
+else
+  echo "❌ git 認證不通——marketplace 一定裝不起來，後面不用往下做了。" >&2
+  echo "   檢查：GITEA_TOKEN_CLAUDE_CODE 的值對不對、那把 token 有沒有被撤銷。" >&2
+  exit 1
+fi
 
-echo "✅ ISEP 已裝成 user-scope plugin，之後每個 session 啟動時直接生效。"
+# ── 安裝（user scope 只是備援）─────────────────────────────
+# 🔴 官方文件（cloud-environments 的 what-carries-over 表）明文：
+#    「Plugins enabled only in your user settings」→ **不會**帶到雲端 session。
+#    真正生效的是薄殼 repo 的 .claude/settings.json 裡的 enabledPlugins ＋ extraKnownMarketplaces。
+#    這兩行留著當本地備援，不是主要路徑——不要以為裝完就等於雲端有了。
+claude plugin marketplace add https://git.uncle6.me/inkstone/ISEP.git --scope user 2>/dev/null || true
+claude plugin install isep@inkstone --scope user 2>/dev/null || true
+
+# ── 🔴 自我驗證二：marketplace 真的拉下來了嗎 ────────────────
+echo "── 驗證 marketplace ──"
+if claude plugin marketplace list 2>/dev/null | grep -q "inkstone"; then
+  echo "✅ marketplace inkstone 已就位"
+else
+  echo "❌ marketplace 沒就位——session 啟動時 enabledPlugins 會是一張跳票的支票。" >&2
+  exit 1
+fi
+
+echo "✅ setup 完成。session 啟動後請用「有鑑別力的探針」驗閘，"
+echo "   不要用 git tag（它在三支閘的白名單裡，閘死了也會過）。"