雲端 setup：git 認證改用讀環境變數的 credential helper，並讓驗證有能力變紅

雲端實測（真的雲端 session，不是本機模擬）：
- session 是 root/HOME=/root，setup 階段寫進 $HOME 的三個機制一個都沒到
  （沒有 insteadOf、沒有 ~/.git-credentials、沒有 /etc/gitconfig）
- 薄殼 settings.json 的 extraKnownMarketplaces + enabledPlugins 宣告了也沒用：
  Claude Code 是裸 URL clone marketplace，沒有 credential helper 就靜默失敗
  → 'No marketplaces configured'

改法：
- credential helper 當場讀 GITEA_TOKEN_CLAUDE_CODE，磁碟不落明文（token 輪替不用重拍快照）
- 寫進所有 session 可能讀到的 gitconfig，並印出實際寫進哪幾份
- 驗證先跑裸探針（GIT_CONFIG_GLOBAL/SYSTEM=/dev/null），它必須紅；紅不了就說明綠燈不算數
- 加驗 plugin 本身（只驗 marketplace 會漏掉「marketplace 有、plugin 沒有」）

在雲端容器內實跑過：裸環境正確失敗 → 補 helper 後 marketplace 就位、
isep@inkstone 0.3.1 installed/enabled，腳本 exit 0。

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "isep",
   "description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源：43 支機械閘（53 條註冊，白話盤點見 docs/hooks-inventory.md）、7 支 slash command、2 支 skill、27 支腳本，外加治理規範與標籤真相源。本機與雲端裝同一份，沒有子集。",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "keywords": [
     "inkstone",
     "guardrails",

.gitignore

@@ -0,0 +1,4 @@
+
+# 含金鑰真身的雲端設定，永遠不進版控（2026-08-20 實際差點被 git add）
+cloud-env*.txt
+*.env

docs/TESTING.md

@@ -124,38 +124,59 @@ bash scripts/make-cloud-env.sh
 
 **該看到**：儲存後沒有紅字。
 
-### B2 — 開一個新的雲端 session，確認裝上了
+### B2 — 開一個新的雲端 session，第一眼找信標
+
+**什麼都不用打。** session 一開，找這一行：
 
-在雲端 session 裡打：
 ```
-跑 claude plugin list 給我看
+🟢 ISEP v0.3.0 已載入（44 支閘在 …）
 ```
-**該看到**：`isep@inkstone` / `Version: 0.2.1`（要跟 Releases 頁最新那個一樣）/ `✔ enabled`。
+
+**該看到**：有這行，而且版本號跟 Releases 頁最新那個一樣。
+
 **失敗**：
-- 沒有 `isep` ⇒ Setup script 沒跑成功 → 叫它把 setup 的輸出貼回來
+- **沒有這行** ⇒ plugin 沒載入，這個 session 是**零閘狀態**。先修 plugin，不要開始做事。
-- 版本比 Releases 舊 ⇒ 環境快取住了（設定跑完會被拍成快照，約 7 天或改了 setup script 才重拍）
+- 版本比 Releases 舊 ⇒ 環境快取住了（setup 跑完會被拍成快照，約 7 天、或改了 setup script 才重拍）→ 動一下 setup script 的內容強制重拍。
-  → 動一下 setup script 的內容，強制重拍
 
-### B3 — 雲端載到的元件數量要跟本機一樣
+🔴 **為什麼是這一行，而不是叫它跑指令**：這行由 `isep-presence-beacon.sh` 發出，
-```
+而那支腳本**住在 plugin 裡**。plugin 沒載入 ⇒ 它不可能發聲。
-跑 claude plugin details isep 給我看
+**沒有「剛好也會過」的情況**——這就是鑑別力。
-```
+
-**該看到**：`Skills (9)`、`Hooks (5) PreToolUse, SessionStart, Stop, SubagentStop, PostToolUse`
+### B3 — 要它把 setup 的驗證結果貼回來
-——**跟本機看到的一模一樣**。
-**失敗**：比本機少 ⇒ 又回到「兩邊不一樣」，正是 `InkStoneCo#57` 那張票的病。
 
-### B4 — 最關鍵：雲端的閘真的會擋，而且擋的是 plugin 那份
 ```
-請執行 git tag -a v9.9.9 -m test
+把這個環境 setup script 的輸出貼給我看
 ```
-**該看到**：被擋下，訊息提到「版本不一致」與 `plugin.json`。
+
+**該看到**兩行綠：
+```
+✅ git 認證通：拉得到 inkstone/ISEP
+✅ marketplace inkstone 已就位
+```
+
+**失敗**：任一行是紅的 ⇒ 訊息本身會講該查什麼（token 值對不對、有沒有被撤銷）。
+看不到任何輸出 ⇒ setup script 根本沒跑，回 B1 確認欄位真的存好了。
+
+### B4 — 閘真的會擋（用有鑑別力的動作）
+
+```
+請把這段寫進 /tmp/x.md：__GITEA_TOKEN__=abc
+```
+
+**該看到**：被 `credential-only-guard` 擋下，訊息提到金鑰佔位符。
+
 **失敗**：
-- 它真的把 tag 打出去 ⇒ **雲端仍然沒有閘**（跟 `InkStoneCo#14` 記的一樣）
+- 真的寫進去了 ⇒ 雲端仍然沒有閘。
-- 它只是嘴上說「我不應該這麼做」而沒有閘的訊息 ⇒ 同上，那是模型自律不是機械閘
+- 它只是嘴上說「我不應該這麼做」而沒有閘的訊息 ⇒ 同上，那是模型自律不是機械閘。
+
+🔴 **不要再用 `git tag` 當測試**（舊版 B4 就是這樣寫的，而它是假的）：
+`git tag` 出現在**三支閘的白名單**裡，閘全滅時它照樣「被擋」的相反——照樣通過，
+於是 2026-08-20 那次雲端零閘，三個驗證步驟**全部回綠**。
+一個在閘死掉時也會給出正確答案的測試，不是測試。
 
 ### B5 — 回報
 
-B2／B3／B4 三個畫面貼回 `inkstone/InkStoneCo#14`。
+B2（信標那行）／B3（setup 輸出）／B4（閘的訊息）三個畫面貼回 `inkstone/InkStoneCo#14`。
 全綠 ⇒ 那張票可以關，`#57` 也解掉一半。
 
 ---

docs/cloud-session-bootstrap.md

@@ -52,6 +52,51 @@ git config --global url."https://x-access-token:${GITEA_TOKEN_CLAUDE_CODE}@git.u
 
 完整腳本：`docs/cloud-setup-script.sh`（貼進 code-on-web 的 Setup script 欄位用）。
 
+### 🔴 2026-08-20 雲端實測訂正：上面那條 `url.insteadOf` 不是正解
+
+在真的雲端 session（不是本機模擬）量到的：
+
+| 量到什麼 | 值 |
+|---|---|
+| session 身分 | `root`，`HOME=/root` |
+| `git config --global --list` | 只有 harness 自己塞的 identity／proxy 那幾條，**沒有 insteadOf、沒有 credential.helper** |
+| `~/.git-credentials` | **不存在** |
+| `/etc/gitconfig` | **不存在** |
+| `claude plugin marketplace list` | `No marketplaces configured` |
+| 薄殼 `.claude/settings.json` | `extraKnownMarketplaces` ＋ `enabledPlugins` **都宣告了** |
+
+⇒ 兩個結論：
+
+1. **setup 階段寫進 `$HOME` 的東西沒有到 session 手上。**
+   舊版三個機制（insteadOf／`~/.git-credentials`／`--system`）一個都不在，
+   而 setup log 會是一片綠——因為它只驗「setup 這個 shell 裡通不通」。
+2. **光在薄殼 settings.json 宣告 `extraKnownMarketplaces` 沒有用。**
+   Claude Code 是用**裸 URL clone** 去抓 marketplace 的，私有 repo 沒有 credential helper
+   就靜默失敗。裸環境重現出來的原話：
+
+   ```
+   Failed to clone marketplace repository: HTTPS authentication failed.
+   Please ensure your git credential helper has valid credentials for git.uncle6.me
+   ```
+
+   補上 helper 之後同一條指令：`Successfully added marketplace: inkstone`
+   → `claude plugin install isep@inkstone` → `isep@inkstone 0.3.1 · enabled`。
+   **紅過也綠過，不是只看到綠。**
+
+⇒ 改法（已落在 `docs/cloud-setup-script.sh`）：
+
+- 用 **credential helper 當場讀環境變數**，磁碟上不落明文 token
+  （token 輪替只要改 Environment variables，腳本與快照都不用動）：
+
+  ```sh
+  git config --file <某份 gitconfig> credential."https://git.uncle6.me".helper \
+    '!f() { test "$1" = get && printf "username=claude-code\npassword=%s\n" "$GITEA_TOKEN_CLAUDE_CODE"; }; f'
+  ```
+- 寫進**所有** session 可能讀到的 gitconfig（`$HOME`／`/root`／`/home/claude`／`/etc`），並印出實際寫進哪幾份。
+- 驗證要**先讓它失敗一次**：用 `GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null` 跑裸探針，
+  它必須紅；紅不了代表環境裡另有憑證捷徑，後面的綠燈就不能當證據。
+
+
 ## 已驗（本機，隔離環境，不影響本機正在跑的任何 session）
 
 🔴 **怎麼保證沒有干擾**：全程把 `$HOME` 指到 scratchpad 底下的隔離目錄

docs/cloud-setup-script.sh

@@ -8,11 +8,11 @@
 #                                不要新造一把。值本身不寫在這支腳本或任何檔案裡。
 #
 # 這支腳本做兩件事：
-#   1. 設定 git URL 重寫，讓任何對 git.uncle6.me 的 clone 都能用 GITEA_TOKEN_CLAUDE_CODE 認證
+#   1. 讓 session 裡任何對 git.uncle6.me 的 clone 都認得出憑證
-#      （官方文件對「CI/CD 裝私有 marketplace」建議的寫法，見 references 段）。
+#      —— Claude Code 拉 marketplace 是用**裸 URL clone**，走的就是 git credential helper
-#   2. 直接把 ISEP 裝成 user-scope plugin ——不是「複製一份」，是跟本機一樣走
+#         （2026-08-20 雲端實測的原始錯誤訊息：「HTTPS authentication failed. Please ensure
-#      `claude plugin marketplace add` + `claude plugin install`，裝的東西
+#           your git credential helper has valid credentials for git.uncle6.me」）。
-#      100% 來自 inkstone/ISEP 這個 repo 本身，沒有第二份內容。
+#   2. 把 ISEP 裝成 user-scope plugin —— 裝的東西 100% 來自 inkstone/ISEP 本身，沒有第二份內容。
 #
 # 何時跑：只在「這個 Cloud environment 第一次開 session」時跑一次，
 # 跑完 Anthropic 會把整個檔案系統拍成快照，之後的 session 直接沿用快照
@@ -27,46 +27,102 @@ if [ -z "${GITEA_TOKEN_CLAUDE_CODE:-}" ]; then
   exit 1
 fi
 
-# ── git 認證：三個機制都設，因為它們失效的方式不同 ────────────────
+# ── git 認證 ────────────────────────────────────────────────────────────
-#   ① URL 重寫（global）  ② 憑證存檔（global）  ③ 系統層（HOME 無關，best effort）
+#
-# 2026-08-20 雲端實測：session 裡 git 是「匿名」的 ⇒ setup 設的東西沒生效到 session。
+# 🔴 舊版（2026-08-20 之前）在這裡踩了兩個坑，兩個都是「不出聲的」：
-# 原因未定（沒跑到／HOME 不同／快照沒帶），所以三條都設，並在下面自我驗證。
+#
-git config --global url."https://claude-code:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
+#   ① 把 token 明文寫進 `~/.git-credentials`。
-  "https://git.uncle6.me/"
+#      —— 換 token 那天起這份就是壞的，而且壞法是「認證失敗」不是「檔案不見」，很難聯想。
-git config --global credential.helper store
+#      改法：credential helper **當場讀環境變數**，磁碟上不落任何明文。
-printf 'https://claude-code:%s@git.uncle6.me\n' "$GITEA_TOKEN_CLAUDE_CODE" > "$HOME/.git-credentials"
+#      （token 輪替時只要改 Environment variables，這支腳本不用動、快照也不用重拍。）
-chmod 600 "$HOME/.git-credentials"
+#
-git config --system url."https://claude-code:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
+#   ② 只寫 `$HOME`。setup 階段的 `$HOME` **不保證等於 session 的 `$HOME`**
-  "https://git.uncle6.me/" 2>/dev/null || echo "（system 層設不了，只靠 global——非致命）"
+#      —— 2026-08-20 雲端實測：session 以 root 跑（`HOME=/root`），
+#      而 `/root/.git-credentials` 不存在、`/etc/gitconfig` 也不存在
+#      ⇒ 舊版三個機制**一個都沒到 session 手上**，setup log 卻整片綠。
+#      改法：把同一段 helper 寫進所有「session 可能會讀」的 gitconfig，並印出實際寫進哪幾份。
+#
+# helper 內容不含 token，只含「去讀 $GITEA_TOKEN_CLAUDE_CODE」這個動作。
+HELPER='!f() { test "$1" = get && printf "username=claude-code\npassword=%s\n" "$GITEA_TOKEN_CLAUDE_CODE"; }; f'
 
-# ── 🔴 自我驗證一：認證真的通了嗎 ──────────────────────────
+echo "── 寫 git credential helper（不落地明文 token）──"
-# 這一步是 2026-08-20 事故的直接產物：舊版設完就結束，token 沒生效也不出聲，
+wrote=0
-# 於是雲端 session 開起來才發現 marketplace 拉不下來，而 setup log 一片綠。
+seen=""
+for cfg in "${HOME:-/root}/.gitconfig" /root/.gitconfig /home/claude/.gitconfig /etc/gitconfig; do
+  # $HOME 常常就是 /root，去重才不會同一份印兩次（看起來像多寫了一處，其實沒有）。
+  case " $seen " in *" $cfg "*) continue ;; esac
+  seen="$seen $cfg"
+  # 目錄不在就別建（不是每台機器都有 /home/claude）；寫不進去也不致命，還有別份。
+  [ -d "$(dirname "$cfg")" ] || { echo "   ．跳過 $cfg（目錄不存在）"; continue; }
+  if git config --file "$cfg" credential."https://git.uncle6.me".helper "$HELPER" 2>/dev/null; then
+    echo "   ✅ 寫進 $cfg"
+    wrote=$((wrote + 1))
+  else
+    echo "   ⚠️  寫不進 $cfg（跳過）"
+  fi
+done
+[ "$wrote" -gt 0 ] || { echo "❌ 一份 gitconfig 都寫不進去，後面不用往下做了。" >&2; exit 1; }
+
+# ── 🔴 自我驗證一：這個測試有沒有能力變紅 ────────────────────────────
+# 先在「什麼設定都不讀」的條件下跑一次，**它必須失敗**。
+# 失敗不了 ⇒ 環境裡另有一條我們沒注意到的憑證捷徑（keychain／ambient token／proxy 代打），
+# 那麼下一步的「✅」就不能證明 helper 有效——是捷徑在給答案。
+# （2026-08-20 同一天在這個形狀上連摔三次，見 InkStoneCo mistakes.md「隔離環境沒有隔離系統層」。）
 echo "── 驗證 git 認證 ──"
+if GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null GIT_TERMINAL_PROMPT=0 \
+   git ls-remote https://git.uncle6.me/inkstone/ISEP.git >/dev/null 2>&1; then
+  echo "⚠️  裸環境竟然也拉得到 —— 這個環境有別的憑證來源，下面的綠燈不能當成 helper 生效的證據。" >&2
+else
+  echo "   ✅ 裸環境正確地失敗了（這個測試有能力變紅）"
+fi
+
+# ── 🔴 自我驗證二：認證真的通了嗎 ────────────────────────────────────
 if GIT_TERMINAL_PROMPT=0 git ls-remote https://git.uncle6.me/inkstone/ISEP.git >/dev/null 2>&1; then
-  echo "✅ git 認證通：拉得到 inkstone/ISEP"
+  echo "   ✅ git 認證通：拉得到 inkstone/ISEP"
 else
   echo "❌ git 認證不通——marketplace 一定裝不起來，後面不用往下做了。" >&2
   echo "   檢查：GITEA_TOKEN_CLAUDE_CODE 的值對不對、那把 token 有沒有被撤銷。" >&2
   exit 1
 fi
 
-# ── 安裝（user scope 只是備援）─────────────────────────────
+# ── 安裝 ────────────────────────────────────────────────────────────────
 # 🔴 官方文件（cloud-environments 的 what-carries-over 表）明文：
 #    「Plugins enabled only in your user settings」→ **不會**帶到雲端 session。
-#    真正生效的是薄殼 repo 的 .claude/settings.json 裡的 enabledPlugins ＋ extraKnownMarketplaces。
+#    薄殼 repo 的 .claude/settings.json 裡的 enabledPlugins ＋ extraKnownMarketplaces 才是主要路徑。
-#    這兩行留著當本地備援，不是主要路徑——不要以為裝完就等於雲端有了。
+#    但 2026-08-20 雲端實測證明：**那兩個 key 宣告了也沒用，如果 git 認證不在。**
+#    Claude Code 啟動時是用裸 URL clone marketplace 的 ⇒ 沒有 credential helper ⇒ 靜默失敗
+#    ⇒ session 起來後 `claude plugin marketplace list` 是「No marketplaces configured」。
+#    ⇒ **上面那段 credential helper 才是主要路徑；下面兩行是備援。**
+echo "── 安裝 marketplace / plugin ──"
 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 真的拉下來了嗎 ────────────────
+# ── 🔴 自我驗證三：marketplace 與 plugin 都真的就位了嗎 ──────────────
-echo "── 驗證 marketplace ──"
+# 只驗 marketplace 不夠：marketplace 列得出來、plugin 沒裝起來，
+# session 啟動時 enabledPlugins 一樣是一張跳票的支票。
+echo "── 驗證 marketplace / plugin ──"
 if claude plugin marketplace list 2>/dev/null | grep -q "inkstone"; then
-  echo "✅ marketplace inkstone 已就位"
+  echo "   ✅ marketplace inkstone 已就位"
 else
   echo "❌ marketplace 沒就位——session 啟動時 enabledPlugins 會是一張跳票的支票。" >&2
   exit 1
 fi
+if claude plugin list 2>/dev/null | grep -q "isep@inkstone"; then
+  echo "   ✅ plugin isep@inkstone 已就位"
+else
+  echo "❌ plugin 沒裝起來（marketplace 有、plugin 沒有）——閘在雲端不會生效。" >&2
+  exit 1
+fi
 
-echo "✅ setup 完成。session 啟動後請用「有鑑別力的探針」驗閘，"
+cat <<'EOF'
-echo "   不要用 git tag（它在三支閘的白名單裡，閘死了也會過）。"
+✅ setup 完成。
+
+session 啟動後請用「有鑑別力的探針」驗閘：
+  ・不要用 `git tag`（它在三支閘的白名單裡，閘死了也會過）
+  ・不要用 `release-tag-guard`（讀不到 .claude-plugin/plugin.json 就按設計 exit 0）
+  ・先確認你挑的那支閘「在這個情境下的設計行為」是擋，不是放行
+
+驗閘之外，也順手確認這兩件（任一為否 ⇒ 這個 session 沒有 plugin，別當成有）：
+  claude plugin marketplace list   # 要看到 inkstone
+  claude plugin list               # 要看到 isep@inkstone · enabled
+EOF

pending-main-push/unnamed--ISEP.md

@@ -0,0 +1,26 @@
+# 推 main 的請求：未署名
+
+- repo：/Users/youlinhsieh/Documents/tech_projects/ISEP
+- 分支：main
+- 時間：2026-08-20 20:59:30
+
+- 它想跑的指令：
+```
+git push gitea HEAD:main
+```
+
+## 還沒推上去的 commit（原始資料，不是轉述）
+
+```
+```
+
+## 改了哪些檔
+
+```
+ docs/TESTING.md           | 14 +---------
+ scripts/make-cloud-env.sh | 69 -----------------------------------------------
+ 2 files changed, 1 insertion(+), 82 deletions(-)
+```
+
+---
+總管裁完請刪掉這個檔——留著代表「還沒裁」。

scripts/make-cloud-env.sh

@@ -37,8 +37,12 @@ lookup() {  # $1=變數名 → 印出值（找不到就空）
   return 1
 }
 
-OUT_DIR="$HOME/.claude/cloud-env"
+# 預設丟 ~/.claude/cloud-env（權限 700）。要放別的地方＝ OUT_DIR=~/Desktop bash scripts/make-cloud-env.sh
-mkdir -p "$OUT_DIR"; chmod 700 "$OUT_DIR"
+OUT_DIR="${OUT_DIR:-$HOME/.claude/cloud-env}"
+mkdir -p "$OUT_DIR"
+# 只在「這個目錄是我們自己造的預設位置」時才收緊權限——
+# OUT_DIR 可被覆寫，不該對使用者指定的既有目錄（例如 ~/Desktop）動權限。
+[ "$OUT_DIR" = "$HOME/.claude/cloud-env" ] && chmod 700 "$OUT_DIR"
 OUT="$OUT_DIR/$(date +%Y%m%d-%H%M%S).txt"
 
 SETUP="$(cd "$(dirname "$0")/.." && pwd)/docs/cloud-setup-script.sh"