06 問題與困難
狀態：已解＝有腳本或 gate 接住；繞過＝有固定做法但根因未除；未解＝目前只能認知它的存在。
| # | 症狀 | 原因 | 現況 | 對應工具 | 狀態 |
|---|---|---|---|---|---|
| 1 | 跑到一半 MySQL 連線斷、Hikari pool total=0；或 Docker 引擎整個凍住 | Docker Desktop 重啟或 Resource Saver 讓引擎休眠 | 測試只透過單一入口進入，它先探測 Docker、每分鐘再探一次，凍結時停掉 Gradle 並回報 DOCKER_LOST；Resource Saver 已關閉 | run-docker-tests.sh、docker-ensure.sh | 已解 |
| 2 | agent 不能任意 push，sudo 一律被拒 | 刻意的權限邊界 | 只放行以 push-pinned.sh 推 feature/ron/*：它推送已驗收的固定 SHA，pre-push 在暫時 worktree 驗收該 SHA，其他 session 同時合入也不影響；沒有這個權限的 session 停在 PUSH_REQUIRED 交人推；sudo 由人在自己的終端跑 | push-pinned.sh、close-issue.mjs、check-before-push.sh、pre-push hook | 已解 |
| 3 | 多個 session 同時合入或跑回歸互相干擾、結果對不上 | 整合分支與回歸是共用資源 | 合入只有一個入口且有 lock 與預約；驗收回歸 FIFO 排隊；只改工具或文件的分支可插隊；不手寫等待迴圈 | merge-into-integration.sh、queue-regression.mjs | 已解 |
| 4 | 有人繞過腳本直接 merge、改寫整合分支歷史；git stash pop 套到別的 session 的東西 | git 本身不擋；stash 清單跨 worktree 共用 | reference-transaction hook 擋掉非腳本的合併；worktree 間搬東西用 git show／git archive | install-integration-guard-hook.sh | 已解（已知縫隙：pack-refs、不帶舊 SHA 的 update-ref -d） |
| 5 | 規則寫在 memory／skill 裡仍被忽略 | 文字規則沒有強制力 | 重複失誤就升級成腳本或 gate，失敗時印修正指示 | 各 check-*、/retro | 已解（原則） |
| 6 | Orca worktree create／rm 回 runtime_unavailable，但 worktree 其實已建好或已刪 | Orca 從 WSL 呼叫時回應早於實際完成 | 只呼叫一次，用 git worktree list 輪詢確認；絕不重試（會多出 <name>-2）；找不到 selector 時改用 path: | orca-worktree-create.mjs、worktree-audit.mjs | 繞過 |
| 7 | Orca 看板與 GitLab 看板兩邊狀態不一致，開單就建 worktree 造成一堆空 worktree | 兩套看板、worktree 建得太早 | 只用 GitLab board；worktree 延到認領時才建；Orca 只負責建／刪 | issue-state.mjs（原名 sync-orca-board，只改 label） | 繞過 |
| 8 | 改了一行註解，測試或 pre-push 就紅 | 某些檔被 SHA-256 釘住（compat fixture、site-progress） | 改既有檔前先查是否被釘住 | pinned-sources.mjs | 繞過 |
| 9 | 時間相關測試偶發 500 | WSL 時鐘跳動 1 到 3 ms，timesyncd 關了也一樣 | 先單獨重跑確認不是負載；用 runner 的 --clock-probe 量測；接受偶發 | run-spay4-isolated-tests.py --clock-probe | 未解 |
| 10 | GitLab 自動 pipeline 不跑 | CI 已暫停，只接受手動 web pipeline（spay4-contract-check、spay4-schema-verifier-test） | 把關全靠本地 pre-push；push 前用 report-push-scope.mjs 看範圍；本地每道 gate 的強度與邊界見 08 品質校驗時間軸 | check-before-push.sh、ci-checks.md | 未解 |
另外幾條小坑：
- 手動 SQL 貼到終端會被 CRLF 換行弄壞，一律以檔案交付，
COMMENT用 HEX 檢查。 - 背景工作會繼承 SIGINT 忽略，看起來像 timeout；先在前景與背景各單獨重跑一次再怪負載。
gc的「unreachable objects」警告多半是 rebase 殘留，gc.log一天後自動消失，不要手動git prune。.claude/settings.json的權限規則只能由人改；agent 需要新規則時會請人加。- headless Chromium 在 WSL 沒有中文字型，截圖裡 SVG 文字會變方框（見 07）。