下面是 Claude Code 想讓失敗的 GitNest check 再跑一次時呼叫的工具,內容就是 osFoundry 線上 MCP endpoint 在 tools/list 裡列出的樣子(取得目錄不需要 token):
{
"name": "propose_gitnest_check_rerun",
"description": "Ask the repository owner to retry one finished check on a specific composed change-set version. Approval rechecks repository access, version, commit and check state.",
"inputSchema": {
"type": "object",
"properties": {
"repository_id": {"type": "string"},
"change_set_id": {"type": "string"},
"check_name": {"type": "string", "maxLength": 200},
"expected_change_set_version": {"type": "integer", "minimum": 1},
"expected_composition_oid": {"type": "string"},
"idempotency_key": {"type": "string", "minLength": 8, "maxLength": 128}
},
"required": ["repository_id", "change_set_id", "check_name",
"expected_change_set_version", "expected_composition_oid", "idempotency_key"],
"additionalProperties": false
},
"annotations": {"readOnlyHint": false, "openWorldHint": false, "destructiveHint": true},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]
}
對應的讀取工具只吃兩個參數:list_gitnest_checks {repository_id, change_set_id},"bounded check status for the current composed commit of a change set"。另外還有兩個讀取工具提供判斷依據:list_gitnest_saved_results(limit 1–50)和 read_gitnest_work(kind 為 tasks、changes 或 runs)。三個都是 osfoundry:read,且 readOnlyHint: true。
只為了重跑一個 check 就要六個必填欄位,算是很多。CI 的按鈕只要一個 job ID。多出來的兩個,也就是 version 和 commit,就是這篇的主題。這台 Mac 沒有裝 claude 執行檔,所以由 checks_sim.py 扮演 client。程式碼和完整輸出都放在 code/。
agent 讀 check 時,「綠燈」到底是什麼意思?
agent 在提出任何提議之前,得先把 check 清單讀對。osFoundry 的 GitNest UI 用一個小小的純函式(check-runs.ts 裡的 summarise)彙總一個 commit 的 check run。它判斷的順序本身就是規則:
- 一個 run 都沒有就是
none,絕不是passed。 - 只要有
failure、timed_out或cancelled就是failed。 - 只要還有不是
success的,就維持running,連 client 不認得的狀態也算。 - 到這裡才是
passed。
腳本把這條規則移植過來,跟 model 自己常寫出來的兩種偷懶判斷做比較:
== verdict ==
case summarise no-failure ratio
no checks none green green
all passed passed 2 green green
one queued running 1/2 green red
one failed failed: e2e red red
one timed out failed: e2e green red
one cancelled failed: e2e green red
unknown status running 1/2 green red
shortcut wrong: no-failure 5/7, ratio 1/7
「沒有東西失敗,所以是綠燈」在 7 個案例裡錯了 5 個。它把沒檢查過的 commit 當綠燈、把還在排隊的 check 當綠燈、把 timeout 也當綠燈。用比例判斷(passed == total)比較接近,但 check 數為零時 0 == 0,它一樣會說綠燈。這正是 GitNest 程式碼註解裡說最容易誤導的情況,因為沒有任何 check 的 commit 根本沒被驗證過。UI 會顯示成 "No checks have run against this commit",不打勾。
如果你要 Claude Code 回答「現在是綠燈嗎?」,就把這四條規則寫進 CLAUDE.md。工具回傳的是狀態,不是結論。
為什麼重跑要帶 version 和 commit?
因為負責核准的人看的是某一個特定的 commit,而 change set 有可能在他按下去之前就變了。
GitNest 的 change set 是從已儲存的結果組成一個 commit。只要重新組合,不管是因為有新的儲存結果,還是 base 移動了,就會拿到新的 version 和新的組合 commit,它的 check 也會從頭開始。重跑提議要等人來處理。如果它只寫 "rerun e2e on cs_4e81a0",核准時就會對當下的 change set 重跑 e2e,而那可能是 owner 根本沒看過的 commit。
checks_sim.py 模擬的就是這段等待。每次試驗是一個提議。agent 讀到的是 version 3、commit A,e2e 失敗。owner 的審查時間假設為中位數 8 分鐘的對數常態分布。這是假設,不是實測。等待期間,change set 以 Poisson 過程重新組合,平均每 45 分鐘一次,重組後 check 要跑 4 分鐘。有 10% 的試驗裡,第二個 Claude Code session 讀到同一個失敗,用自己的 key 送出自己的提議,而 owner 兩個都核准。核准時的三種防護,各跑 10,000 次:
== approval-time guards (n=10000, review median 8 min, recompose mean every 45 min, 10% second session) ==
guard ran on reviewed commit ran on unreviewed commit duplicate run refused (stale) refused (not finished)
none 7789 1411 1764 0 0
version+oid 7789 0 740 2435 0
full 7789 0 0 2435 740
沒有防護時,有 1,411 次核准在 owner 沒審過的 commit 上重跑 check,還有 1,764 次把已經在排隊或執行中的 check 再排進佇列。核准時比對 version 和 commit,未審查的執行就降到 0,代價是拒絕 2,435 張過期的卡片。剩下的 740 筆重複來自第二個 session:version 一樣、commit 一樣,但第一次核准已經把 check 重新排進佇列了。第三道防護「這個 check 還是已完成狀態嗎?」會把它們擋下來。這就是工具說明裡列出的完整檢查:"Approval rechecks repository access, version, commit and check state."
重組頻率是最沒把握的輸入值,所以下面是三種頻率下無防護那一列的結果:
== sensitivity: unreviewed-commit runs with guard 'none' ==
recompose every 15 min unreviewed 2449 duplicates 3128
recompose every 45 min unreviewed 1411 duplicates 1764
recompose every 180 min unreviewed 452 duplicates 1208
就算 change set 每三小時才變一次,每 10,000 次仍有 452 次跑在錯的 commit 上。正常情況下防護完全沒有成本:三列裡跑在已審查 commit 上的次數都是 7,789。
為什麼 version 和 commit 都要?
在這個模型裡兩者總是一起變,所以只用其中一個分數也一樣。但它們回答的是不同的問題。version 是 change set 自己的計數器,內容變了它就跟著變。commit 則是 check 實際跑的對象,也是卡片上顯示為 "Reviewed commit: …" 的東西。要求 client 兩個都送,伺服器就能依任一個拒絕,而 owner 在卡片上看到的是 commit hash,不是內部計數器。schema 會強制 version 是 ≥ 1 的整數。commit 是自由字串,所以它的檢查在伺服器端進行。
呼叫之前 schema 會擋掉什麼?
腳本用 jsonschema 拿線上的 inputSchema 驗證參數:
== propose_gitnest_check_rerun arguments ==
ok PASS
no oid REJECT 'expected_composition_oid' is a required property
version 0 REJECT 0 is less than the minimum of 1
version as string REJECT '3' is not of type 'integer'
two checks REJECT ['e2e', 'lint'] is not of type 'string'
check 201 chars REJECT 'ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
key 7 chars REJECT 'abcdefg' is too short
extra 'force' REJECT Additional properties are not allowed ('force' was unexpected)
required: repository_id, change_set_id, check_name, expected_change_set_version, expected_composition_oid, idempotency_key
其中有兩個拒絕是刻意的設計,不只是資料衛生。check_name 是字串不是陣列,所以「全部重跑」等於每個 check 一張卡片,由 owner 逐一決定。另外 additionalProperties: false 讓自己編出 "force": true 的 model 會直接拿到錯誤,而不是一個被默默忽略的 flag。
idempotency key 應該由提議的內容決定,而不是由這次嘗試決定。腳本用的是 "rerun-" + sha256(change_set_id, version, oid, check_name)[:32]:
key retry same: True key after recompose same: False len 38
回應遺失後重試會送出同一個 key,不會產生第二張卡片。重組會改變 key,所以針對新 commit 的提議會是一張新卡片,這樣才對。
這些工具有多重?伺服器有多遠?
== tools/list ==
59 tools, 48140 B via json.dumps, 12722 tok (cl100k)
list_gitnest_checks 612 B 158 tok readOnly=True destructive=False scope=osfoundry:read
list_gitnest_saved_results 707 B 182 tok readOnly=True destructive=False scope=osfoundry:read
read_gitnest_work 685 B 189 tok readOnly=True destructive=False scope=osfoundry:read
propose_gitnest_check_rerun 1011 B 268 tok readOnly=False destructive=True scope=osfoundry:write
all 13 gitnest tools 11227 B 3009 tok
13 個 GitNest 工具大約占目錄 token 的四分之一(用 tiktoken cl100k_base 計算,請當成概略值)。從日本的這台 Mac 對線上 endpoint 各發十次未認證的呼叫:
$ python3 probe.py
initialize HTTP 200 308 B median 566 ms min 326 max 807
capabilities: {"tools": {"listChanged": false}}
tools/list HTTP 200 45368 B median 722 ms min 420 max 1406
tools/call list_gitnest_checks HTTP 401 337 B median 552 ms min 409 max 903
401 帶有 error_description="Connect osFoundry to continue" 和一個 resource_metadata URL,Claude Code 就是靠這個進入 OAuth 流程。initialize 沒有宣告任何 push,所以沒有東西會通知 client 重試已核准或 check 已跑完。等一個 check 要靠你機器上的 runner 加上一個人的點擊,是以分鐘計,不是毫秒。省事的做法是提議後就結束這一輪,等使用者說已經核准,再呼叫一次 list_gitnest_checks。
check 實際上是誰在跑?
不是 osFoundry。GitNest 的 runner 面板寫著 check "run on your machine, not ours"。註冊好的 runner 用自己的 token 輪詢(OSF_RUNNER_TOKEN=… osfoundry-runner --api https://api.osfoundry.io),沒有 runner 的話 check 會 "stay queued"。核准重試只會把 check 重新排進佇列。Claude Code 從來拿不到 runner token,讀取工具也不會回傳本機 binding 和憑證。agent 看得到 e2e 失敗,但沒有你和你的 runner,它什麼都跑不起來。
如果你要自己串接
- 把判斷綠燈的規則寫進 client 的指示,不要只放在你的 UI 裡。「沒有 check」和「未知狀態」正是 agent 會回報綠燈的地方。
- 讓重跑指定它被審查時的 commit,並在核准時比對,而不是在提議時。
- 核准時也要重新確認 check 本身的狀態。version 和 commit 抓不到針對同一個失敗的兩個提議。
- 一個提議只收一個 check。用陣列的話,重試一個不穩定的測試會變成沒人選過的全面重跑。
- idempotency key 由(change set、version、commit、check)推導,讓重試合併成一筆,重組則不會。
- 執行要遠離平台也遠離 agent:token 在 runner 手上,按鈕在人手上。
附 check 面板的 change set 審查頁面在 GitNest 頁面。協定本身請參考 MCP 詞彙條目。
Top comments (0)