Merge pull request '釋出：本機複本一個 domain 一把鎖，重啟閘門不等整輪判定' (#66) from develop into master

Reviewed-on: #66
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署",
   "skills": "./skills",
   "jsc": {

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署",
   "skills": "./skills/",
   "jsc": {

references/behaviors.md

@@ -18,9 +18,9 @@
 | --- | --- |
 | 觸發時機 | 整組 jsc 技能要在這台機器的每一支已安裝 CLI 上安裝、更新或解除安裝時用。只處理單一技能不用；只想知道版本落後與否，看 doctor 就夠 |
 | 關鍵步驟 | 先跑一次 `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，解到那一層就停，不再往下解成帶版本號的快取路徑——那種路徑放不進允許清單，版本號寫成萬用字元也對不上；同一步再跑 `[ -d "{剛印出來的路徑}" ]` 確認目錄存在，`JSC_HOME` 沒設時它印的是 `/current`、結束碼 0，非空又是絕對路徑，只看那兩項擋不下來。整輪只解這一次，之後每一次跨外掛腳本呼叫都填成那個字面絕對路徑，不留 `$JSC_HOME` 也不留波浪號；技能自己那四支 `tools/*.sh` 一律不走 `current`，即使那裡擺著 `jsc-cli` 那一條也一樣——第四步會為每個部署到的 domain 刷新連結，所以跑過一輪之後那一條通常在，但第一次建起它的正是這一輪，沒部署過的機器、或上一輪 link 回 fail 的機器，那一條不在或還停在舊版，四支腳本會解到不存在的路徑或自己的舊副本；根目錄取自 CLI 載入這支技能時講明的外掛基底目錄，原樣當字面絕對路徑用，一個指令都不跑，四支一律寫成 `{外掛根目錄}/tools/{腳本}`；那個基底目錄帶版本號，四次呼叫都會跳權限詢問，這一支有人在現場（第三步要問模式）所以按得掉，無人值守的技能不得照抄，叫用文字沒講明基底目錄就回報外掛根目錄不明並停手，不猜前綴——權限層靜態比對路徑，帶未展開變數的呼叫一律要人核准，無人看管的輪次會停在第一支腳本，補權限規則也擋不住，因為規則字面同樣是靜態比對；解不出來就停手回報。接著同時取得三項事實（detect-clis.sh 的 CLI 清單、version-guard.sh 的 report 版本表與 recommend 結論、marketplace.json 的 domain 清單）、把版本表原樣秀出並定出建議、依 jsc-ask 決策樹問出模式（呼叫端已帶模式就沿用並標明來源）、每支 CLI 各開一個 sub agent 同時跑 tools/deploy.sh {mode} {cli} {domain}...、讀 deploy.sh 收尾印出的 link 行確認 `current` 連結農場刷新到位（install 與 update 把每一條指到這次裝的版本目錄，uninstall 清掉指向已消失的那幾條；一台機器只有一組農場而五支 CLI 各有副本，所以只有基準 CLI 那一輪會動它，基準是 claude、codex、copilot、kiro 之中這台機器第一支裝得到的，其餘四支各印一行 link 標明基準是誰，平行覆寫會讓最後指到哪一份變成隨機；狀態 ok 要把指向抄進收尾報告，removed 不必處置，skip 帶 domain 是那個路徑上擺著非符號連結的東西、腳本刻意不覆寫而要人工處理，fail 是版本目錄取不到或連結建不起來、部署本身仍然成立但那條文件路徑可能還停在舊版，整輪判 degraded，連結失敗一律不記成部署失敗，否則會連重啟閘門與 result 行一起跳過，把一台裝好的機器講成失敗）、安裝或更新後把 CLI 清單交給 jsc-hooks:hooks-install、整台機器跑一次 tools/write-guides.sh、彙整每支 CLI 的結果並要求重新啟動工作階段，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:deploy 寫下這一輪的結果。收尾那一筆接在彙整回報之後，不取代它；走每一條出口，連停在偵測不到 CLI 那一條也要寫。status 五選一，每支 CLI 都回 0、hooks-install 判定乾淨、兩份指引都寫成、基準 CLI 的 link 行全是 ok 或 removed 是 ok，偵測不到任何 CLI、整輪沒下過任何外掛命令是 blocked，marketplace 讀不到或每支 CLI 都失敗、冒煙結果出現 No such file 是 failed，部分 CLI 成功部分失敗、有 domain 被 skip、write-guides.sh 回 4 讓機器沒有最新指引、或有 link 行回 fail 與帶 domain 的 skip 是 degraded，使用者沒選模式或在第一支 CLI 開跑前停手是 aborted。detail 只放模式與各項筆數，cmd 與 exit 行留在回報裡 |
-| 外部呼叫 | `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，加上同一步的 `[ -d ]` 確認，是整輪唯一容許帶變數的兩個指令；跨外掛腳本一律用它組成的字面絕對路徑呼叫：{current 目錄}/jsc-hooks/hooks/version-guard.sh 的 report 與 recommend、{current 目錄}/jsc-gitea/tools/gitea.sh 讀 plugins/meta 的 marketplace.json、{current 目錄}/jsc-hooks/tools/report-status.sh skill-end。技能自己那四支腳本走外掛根目錄組成的字面絕對路徑：{外掛根目錄}/tools/detect-clis.sh、{外掛根目錄}/tools/deploy.sh、{外掛根目錄}/tools/write-guides.sh、{外掛根目錄}/tools/check-requires.sh（由 deploy.sh 在每個 domain 更新前轉呼叫）。第四步那段內文提到的 `jsc-hooks/hooks/version-guard.sh` 是在講擋人發生在哪一層，不是這支技能要下的呼叫，整輪只有第一步那一次真的跑它。另有 jsc-hooks/hooks/restart-gate.sh require（由 deploy.sh 收尾轉呼叫）、jsc-ask:ask、jsc-hooks:hooks-install。`current` 連結農場的刷新不是另一支腳本，是 deploy.sh 自己收尾做的，技能只讀它印的 link 行，不自己下 ln 或 rm |
+| 外部呼叫 | `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，加上同一步的 `[ -d ]` 確認，是整輪唯一容許帶變數的兩個指令；跨外掛腳本一律用它組成的字面絕對路徑呼叫：{current 目錄}/jsc-hooks/hooks/version-guard.sh 的 report 與 recommend、{current 目錄}/jsc-gitea/tools/gitea.sh 讀 plugins/meta 的 marketplace.json、{current 目錄}/jsc-hooks/tools/report-status.sh skill-end。技能自己那四支腳本走外掛根目錄組成的字面絕對路徑：{外掛根目錄}/tools/detect-clis.sh、{外掛根目錄}/tools/deploy.sh、{外掛根目錄}/tools/write-guides.sh、{外掛根目錄}/tools/check-requires.sh（由 deploy.sh 在每個 domain 更新前轉呼叫）。第四步那段內文提到的 `jsc-hooks/hooks/version-guard.sh` 是在講擋人發生在哪一層，不是這支技能要下的呼叫，整輪只有第一步那一次真的跑它。另有 jsc-hooks/hooks/restart-gate.sh require（由 deploy.sh 收尾轉呼叫，install 與 update 一律呼叫，整輪判定成 fail 也照呼叫——外掛已經換了一部分，那時候更需要重啟；原本只在成功時呼叫，實測有一輪被一條與部署無關的 git pull 判成 fail，那一支 CLI 就沒有被掛上閘門）、jsc-ask:ask、jsc-hooks:hooks-install。`current` 連結農場的刷新不是另一支腳本，是 deploy.sh 自己收尾做的，技能只讀它印的 link 行，不自己下 ln 或 rm |
 | 完成條件 | `current` 那個目錄在第一步就解出一條存在的絕對路徑（用 `[ -d ]` 查過，而且沒有再往下解成帶版本號的快取路徑），技能自己那四支腳本也有一條字面絕對的外掛根目錄可用，後續每一支腳本都用這兩條之一組成的字面絕對路徑呼叫；每一支偵測到的 CLI 都回報結束碼與 result 行，每個 skip、warn、compat、link 行都照實列出；基準 CLI 那一輪每個 domain 都有一條 link 行，狀態 ok 的把指向抄進收尾報告，狀態 fail 與帶 domain 的 skip 都點名外掛與原因並整輪判 degraded，非基準的那幾支各有一行標明基準是誰；安裝或更新還要拿到 hooks-install 對每支 CLI 的總結，兩份指引都印出 wrote，收尾印出重啟指示、兩份指引路徑，以及每個外掛的連結現在指到哪一個版本目錄。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼 |
-| 可驗證跡象 | 各 CLI 的外掛目錄多出或少掉 jsc-{domain}：claude 與 codex 在各自的 plugin 快取、copilot 在 installed-plugins、antigravity 與 kiro 走 $JSC_LOCAL_PLUGINS 的本地 clone 與 $JSC_KIRO_SKILLS 的複製。$JSC_HOME/current/ 底下每個外掛一條符號連結，安裝或更新之後拿 `readlink` 讀出來的指向，就是基準 CLI 這一輪裝到的那個帶版本號目錄，跟 link 行第五欄逐字相同，也跟 version-guard.sh report 那張表上該外掛的本機版本對得起來——這一項驗得到連結指向正確：連結上的版本號與剛裝上的版本號不一致，就是刷新沒做到；解除安裝之後，指向已消失的那幾條不再留在目錄裡，`readlink -e` 對每一條都解得出存在的目錄，沒有一條是斷的；那個目錄底下也不會出現實體目錄，非符號連結的項目腳本刻意不動並留下一行 skip。$JSC_HOME/restart-required.d/{cli} 出現這次的重啟狀態檔；$JSC_HOME/update-guide.md 與 $JSC_HOME/remove-guide.md 被重寫；各 CLI 的 hook 設定檔由 hooks-install 改寫；$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-cli:deploy，status 與 exit 就是這一輪的結果。回報與逐行紀錄裡出現的腳本路徑全是字面絕對路徑，找不到 `$JSC_HOME`、`$` 開頭或波浪號開頭的呼叫，唯一的例外是開頭那一次 `readlink -f "$JSC_HOME/current"` 與同一步的 `[ -d ]` 確認；跨外掛那幾支的路徑中段是 `current`，不是 `cache/jsc/{外掛}/{版本}`，技能自己那四支則一律是外掛根目錄接 `tools/`，沒有一支寫成裸的相對路徑 |
+| 可驗證跡象 | 各 CLI 的外掛目錄多出或少掉 jsc-{domain}：claude 與 codex 在各自的 plugin 快取、copilot 在 installed-plugins、antigravity 與 kiro 走 $JSC_LOCAL_PLUGINS 的本地 clone 與 $JSC_KIRO_SKILLS 的複製；那一份本地 clone 一台機器只有一份而五支 CLI 平行跑，所以 deploy.sh 對每個 domain 取一把 mkdir 鎖再 pull，拿不到鎖或 pull 回非零時印一行 warn 並改用磁碟上現有的內容、不判整輪失敗（clone 不存在那一種照舊算失敗，磁碟上沒東西可裝）。$JSC_HOME/plugins/.lock-{domain} 在一輪跑完之後一個都不該留著。$JSC_HOME/current/ 底下每個外掛一條符號連結，安裝或更新之後拿 `readlink` 讀出來的指向，就是基準 CLI 這一輪裝到的那個帶版本號目錄，跟 link 行第五欄逐字相同，也跟 version-guard.sh report 那張表上該外掛的本機版本對得起來——這一項驗得到連結指向正確：連結上的版本號與剛裝上的版本號不一致，就是刷新沒做到；解除安裝之後，指向已消失的那幾條不再留在目錄裡，`readlink -e` 對每一條都解得出存在的目錄，沒有一條是斷的；那個目錄底下也不會出現實體目錄，非符號連結的項目腳本刻意不動並留下一行 skip。$JSC_HOME/restart-required.d/{cli} 出現這次的重啟狀態檔；$JSC_HOME/update-guide.md 與 $JSC_HOME/remove-guide.md 被重寫；各 CLI 的 hook 設定檔由 hooks-install 改寫；$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-cli:deploy，status 與 exit 就是這一輪的結果。回報與逐行紀錄裡出現的腳本路徑全是字面絕對路徑，找不到 `$JSC_HOME`、`$` 開頭或波浪號開頭的呼叫，唯一的例外是開頭那一次 `readlink -f "$JSC_HOME/current"` 與同一步的 `[ -d ]` 確認；跨外掛那幾支的路徑中段是 `current`，不是 `cache/jsc/{外掛}/{版本}`，技能自己那四支則一律是外掛根目錄接 `tools/`，沒有一支寫成裸的相對路徑 |
 
 ## doctor
 

skills/deploy/SKILL.md

@@ -95,6 +95,8 @@ Nothing passed in → run every step as written below.
 
    On update, `{CLI_ROOT}/tools/check-requires.sh {cli} {manifest}` checks each domain's `jsc.requires` before that domain is updated. Exit 0 updates the domain as usual. Exit 1 — a missing or too-old required jsc plugin — prints a `warn` line and the domain **is still updated**: skipping it would leave a behind domain permanently unable to reach the version its dependency needs. The block lives one layer up, at skill invocation time, where `jsc-hooks/hooks/version-guard.sh` stops that domain's skills. **That last mention is a description of where the block happens, not a call this skill makes** — nothing here runs `version-guard.sh` except step 1.2, which is written as `{JSC_ROOT}/jsc-hooks/hooks/version-guard.sh`, so do not read it as a call site that was left un-prefixed. Exit 4 — the manifest is unreadable, is not valid JSON, or python3 is missing — prints a `note` line and also still updates the domain: no verdict is not the same fact as behind, so it gets its own line rather than a `warn` that would send the operator hunting for a version problem that is not there. Exit 2 or any other code — a `check-requires.sh` usage error or a broken script — prints a `skip` line and leaves that domain untouched, because a checker that failed outright is not a pass. Codex update preserves old `jsc-cli` and `jsc-hooks` cache version paths as symlinks to the newest installed version, so a still-running Codex deploy can keep using its helper scripts and a still-running Codex session whose hook_run_id points at the old cache can finish without `No such file`. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content.
 
+   **That one clone is shared by all five CLIs, and this step runs them in parallel, so the script takes a per-domain lock around its `git pull` and a `warn` line is what a contended or failed pull looks like.** Every CLI reaches that clone: the four that install from it, and `check-requires.sh`, which reads each domain's manifest there. Measured: two CLIs collided inside one round, one could not create `ORIG_HEAD.lock` and the other could not move its remote refs, and **both runs came back `fail` while every plugin had in fact installed** — a report saying failure over a machine that succeeded, for a reason that has nothing to do with deploying. So a pull that cannot get the lock within thirty seconds, or that exits non-zero on a clone already on disk, prints `warn` and **does not fail the run**: the content is there, it may simply be older than the remote. Read every such `warn` line into the report as "this CLI installed what was already on disk" — it is the one line between that and a silent install of a stale version. A `git clone` that fails is different and still fails the run: nothing is on disk to install.
+
    **The `link` lines say where `{JSC_ROOT}` now points, and they are the reason step 0's literal paths keep working.** `{JSC_ROOT}` is a farm of version-free symbolic links, one per plugin, each pointing at that plugin's versioned directory in a CLI's plugin cache. Every literal absolute path this skill builds rests on it, so a link left on an old version silently runs an old script — and a script that old version never shipped is simply absent, which stops a heartbeat without printing anything. `deploy.sh` refreshes the whole farm at the end of its run: install and update repoint every link at the version just installed, uninstall clears the ones whose target is gone.
 
    Only one CLI's run touches the farm. The machine has one farm and five CLIs hold five copies, so the script picks the first of claude, codex, copilot, kiro that is installed and lets only that run write; every other CLI prints one `link<TAB>-<TAB>skip` line naming the base CLI, which is how a deliberate skip is told apart from a farm nobody refreshed. Read the base CLI's sub agent output for the real result. Each line is `link<TAB>{domain}<TAB>{status}<TAB>{link path}<TAB>{target or reason}`.
@@ -110,7 +112,7 @@ Nothing passed in → run every step as written below.
 
    A failed link never fails the deploy. By the time the farm is refreshed the plugins are installed and working, and marking the round failed would skip the restart gate and the `result` line too, handing the operator a fully deployed machine described as a failure. The stale link is a real defect, but its remedy is a line the operator can see and act on.
 
-   Done when every detected CLI has reported an exit code and a `result` line, every skipped domain has a checker-failure reason or a local-tree reason, every `warn` domain is named with the version it still has to catch up to, and every `link` line has been read — with each `ok` target in hand for step 7 and each `fail` or domain-level `skip` named as an operator action.
+   Done when every detected CLI has reported an exit code and a `result` line, every skipped domain has a checker-failure reason or a local-tree reason, every `warn` domain is named with either the version it still has to catch up to or the reason its local clone was not refreshed this round, and every `link` line has been read — with each `ok` target in hand for step 7 and each `fail` or domain-level `skip` named as an operator action.
 
 5. After install or update, call `jsc-hooks:hooks-install` and **hand it the CLI list from step 1.1**, so it does not probe the same five executables a second time. `hooks-install` still detects for itself when it receives no list — that fallback is what keeps it usable on its own.
 
@@ -133,7 +135,7 @@ Nothing passed in → run every step as written below.
 
    State the farm explicitly: name `{JSC_ROOT}` and, per plugin, the version directory its link now points at, taken from the `ok` targets. That one list is what lets the next round's operator check by eye that a documented path leads to the version just deployed, instead of finding out through a heartbeat that quietly stopped.
 
-   For install or update, the same block ends with the restart instruction, in these words: 「請關閉目前的工作階段並重新啟動，新的技能內容才會載入」. `deploy.sh` recorded this round in `$JSC_HOME/restart-required.d/{cli}` — one file per CLI — and prints its path on a `restart` line; `jsc-hooks` reads only that CLI's own file and keeps reminding until that CLI restarts, with `JSC_RESTART_GATE=off` as the escape hatch. Restarting one CLI clears its own file and leaves the others' gates standing. Name the two guide paths from step 6 in that same closing block, so the operator knows where this machine's update and removal commands now live.
+   For install or update, the same block ends with the restart instruction, in these words: 「請關閉目前的工作階段並重新啟動，新的技能內容才會載入」. `deploy.sh` recorded this round in `$JSC_HOME/restart-required.d/{cli}` — one file per CLI — and prints its path on a `restart` line. **It writes that file on every install and update, including a run it judged `fail`**: a partial failure means part of what is on disk changed, which makes a restart more necessary, not less. It used to write it only on success, and one round proved the cost — an unrelated `git pull` failure turned the run into a `fail`, that branch never reached the gate, and the one CLI running the freshly replaced code was the only one never told to restart. Report a `restart` line missing from a `fail` run as a defect in that script rather than raising the gate by hand; `jsc-hooks` reads only that CLI's own file and keeps reminding until that CLI restarts, with `JSC_RESTART_GATE=off` as the escape hatch. Restarting one CLI clears its own file and leaves the others' gates standing. Name the two guide paths from step 6 in that same closing block, so the operator knows where this machine's update and removal commands now live.
 
    Done when every detected CLI appears in the report with its `result` status, every plugin's refreshed link target is named, and — for install or update — the restart instruction is printed with both guide paths named, or step 6's failure is repeated in their place.
 

tools/deploy.sh

@@ -9,11 +9,16 @@
 #   cmd<TAB>{指令}                                     即將執行的指令
 #   exit<TAB>{結束碼}<TAB>{指令}                       該指令的結束碼；dry-run 時結束碼印「-」
 #   skip<TAB>{domain}<TAB>{原因}                       本地 clone 是開發中的樹，略過 git pull
-#   warn<TAB>{domain}<TAB>{原因}                       相依版本不符，仍照樣更新的提醒
+#   warn<TAB>{domain}<TAB>{原因}                       照樣裝下去、但要人知道的事：相依版本不符，
+#                                                      或本機複本這一輪沒有重新拉取（拿不到
+#                                                      更新鎖，或 git pull 回非零），那時候
+#                                                      裝的是磁碟上現有的內容，可能不是最新版
 #   compat<TAB>codex<TAB>{舊路徑}<TAB>{新路徑}          codex 舊版快取路徑補成指向新版的相容連結
 #   note<TAB>{cli}<TAB>{原因}                          非逐指令的說明（例：kiro 整批改走複製退路的理由）
 #   link<TAB>{domain}<TAB>{狀態}<TAB>{連結路徑}<TAB>{指向或原因}  current 連結農場這一條的刷新結果
-#   restart<TAB>{路徑}                                 這次寫下的重啟狀態檔
+#   restart<TAB>{路徑}                                 這次寫下的重啟狀態檔。install 與 update
+#                                                      一律寫，整輪判定成 fail 也照寫：外掛
+#                                                      已經換了一部分，這時候更需要重啟
 #   requires<TAB>{domain}<TAB>{檢查結果}                update 前的 jsc.requires 檢查
 #   result<TAB>{cli}<TAB>{mode}<TAB>{domain 清單}<TAB>{ok|fail}
 # 結束碼：全部指令成功 0；任一指令失敗 1；參數錯誤 2。skip、warn、note、link 不算失敗，
@@ -381,21 +386,93 @@ local_hold() { # $1=存取庫路徑
   [ "${ahead:-0}" -eq 0 ] || printf '有 %s 個未推送的 commit' "$ahead"
 }
 
+# 取一個 domain 的更新鎖。
+#
+# 這一份本機複本一台機器只有一份，而五支 CLI 的部署是平行跑的——平行是對的，它們寫的是
+# 不同的外掛目錄。但這裡不是：五支都會來 pull 同一個目錄，而 git 對同一個存取庫的併發寫入
+# 沒有保護。
+# 2026-09-07 實測踩到：同一輪裡兩支 CLI 撞在一起，一支拿不到 ORIG_HEAD.lock、一支的遠端
+# refs 換不上去，兩支的整輪判定都變成 fail——而外掛其實全部裝好了。那是最難查的一種失效：
+# 報告說失敗，實際成功，而真正的原因跟部署無關。
+# 一個 domain 一把鎖，用 mkdir 取：那是檔案系統這一層唯一原子的建立動作，兩支同時 mkdir
+# 只有一支成功。等不到就改用磁碟上的內容——別人正在拉同一份，硬等下去只是排隊。
+clone_lock() { # $1=鎖目錄 $2=最多試幾次（每次之間睡一秒，所以約等於秒數）；0=拿到了
+  _try=0
+  while :; do
+    mkdir "$1" 2>/dev/null && return 0
+    _try=$((_try + 1))
+    [ "$_try" -ge "$2" ] && break
+    sleep 1
+  done
+  # 等不到還要分一種情形：上一輪中途死掉會留下一個沒有人放的鎖，那種鎖永遠等不到。
+  # 判準取鎖的年紀，門檻放寬到等待秒數的四倍——比任何一次正常的 pull 都久。
+  if [ -d "$1" ]; then
+    _age=$(( $(date +%s) - $(date -r "$1" +%s 2>/dev/null || date +%s) ))
+    if [ "$_age" -gt $(( $2 * 4 )) ]; then
+      rmdir "$1" 2>/dev/null || true
+      mkdir "$1" 2>/dev/null && return 0
+    fi
+  fi
+  return 1
+}
+
+# 截一段訊息到指定長度。cut -c 數的是位元組不是字元，一個多位元組字剛好被切成兩半時
+# 尾巴會留一個替代字元，而亂碼不影響結束碼、沒有人會來報。截完再過一次 iconv -c 丟掉
+# 那個不完整的序列；iconv 不在這台機器上就退回原樣。
+clip1() { # $1=位元組上限；讀標準輸入
+  _raw=$(tr '\n' ' ' | cut -c"1-$1")
+  _cln=$(printf '%s' "$_raw" | iconv -c -f UTF-8 -t UTF-8 2>/dev/null)
+  if [ -n "$_cln" ]; then printf '%s' "$_cln"; else printf '%s' "$_raw"; fi
+}
+
 # 把某 domain 的存取庫抓到本地：有 .git 就 pull，沒有就 clone。
 # 目標是開發中的樹時只印 skip，改用現地內容安裝，不 pull：這支腳本可以被指到任何
 # 目錄，蓋掉維護者未提交或未推送的工作救不回來，安裝一份舊內容還能重跑。
 sync_local() { # $1=domain
   dir="$LOCAL_DIR/$1"
+  lock="$LOCAL_DIR/.lock-$1"
   if [ -d "$dir/.git" ]; then
     hold=$(local_hold "$dir")
     if [ -n "$hold" ]; then
       printf 'skip\t%s\t%s %s，未執行 git pull\n' "$1" "$dir" "$hold"
       return 0
     fi
-    run git -C "$dir" pull
+    # 乾跑一步都不能動，連鎖都不取：取鎖是建目錄，那已經是寫入了。
-  else
+    if [ "$DRYRUN" = 1 ]; then
-    run git clone "$REPO_BASE/$1.git" "$dir"
+      printf 'cmd\t%s\n' "git -C $dir pull"
+      printf 'exit\t-\t%s\n' "git -C $dir pull"
+      return 0
     fi
+    if ! clone_lock "$lock" 30; then
+      printf 'warn\t%s\t%s\n' "$1" "$dir 的更新鎖等了 30 秒還拿不到，別的 CLI 正在拉同一份；這一輪改用磁碟上現有的內容，沒有重新拉取"
+      return 0
+    fi
+    printf 'cmd\t%s\n' "git -C $dir pull"
+    _out=$(git -C "$dir" pull 2>&1); _rc=$?
+    rmdir "$lock" 2>/dev/null || true
+    printf 'exit\t%s\t%s\n' "$_rc" "git -C $dir pull"
+    if [ "$_rc" -ne 0 ]; then
+      # 複本已經在磁碟上，拉不動不等於裝不了：安裝改用現有內容，那可能是舊版。
+      # 這裡刻意不記 FAILED。記了整輪會判成 fail，而 fail 那條路徑會連重啟閘門一起跳過
+      # ——外掛換了一半而沒有人被告知要重啟，比一句「拉不動」嚴重得多。
+      # 但一定要印出來：安靜地裝一份舊內容，是這一組工具最怕的那種失效。
+      printf 'warn\t%s\t%s\n' "$1" "git pull 回 $_rc，這一輪用磁碟上現有的內容安裝，可能不是最新版：$(printf '%s' "$_out" | clip1 160)"
+    fi
+    return 0
+  fi
+  if [ "$DRYRUN" = 1 ]; then
+    run git clone "$REPO_BASE/$1.git" "$dir"
+    return 0
+  fi
+  if ! clone_lock "$lock" 60; then
+    FAILED=1
+    printf 'warn\t%s\t%s\n' "$1" "$dir 還不存在，而 clone 鎖等了 60 秒拿不到，這個 domain 這一輪沒有本機複本可以裝"
+    return 1
+  fi
+  run git clone "$REPO_BASE/$1.git" "$dir"
+  _rc=$?
+  rmdir "$lock" 2>/dev/null || true
+  return "$_rc"
 }
 
 # claude、copilot、kiro-cli 共用的 plugin 指令組。
@@ -581,8 +658,15 @@ esac
 
 refresh_links
 
+# 重啟閘門一律先掛，不等整輪判定。
+#
+# 部分失敗代表磁碟上的外掛已經換了一部分，這時候更需要重啟，不是更不需要。
+# 2026-09-07 實測踩到：一條與部署無關的 git pull 失敗把整輪判成 fail，而原本的寫法是
+# 「判定成功才掛閘門」——於是那一支 CLI 沒有被掛上閘門，沒有人被告知要重啟，而它跑的
+# 是舊版程式碼。一道只在成功時才生效的提醒，在最需要它的那一次不會出現。
+mark_restart
+
 if [ "$FAILED" -eq 0 ]; then
-  mark_restart
   printf 'result\t%s\t%s\t%s\tok\n' "$CLI" "$MODE" "$DOMAINS"
   exit 0
 fi