bug: wrapper runtime state 記「期望版本」而非「實際執行版本」— 下載失敗時 staleness 偵測假陰性 (#335 verify)

[kiki830621]

Problem

plugin/bin/che-apple-mail-mcp-wrapper.sh 在 spawn 時把 期望版本（來自 plugin.json 的 pin）寫進 runtime state file，而不是實際執行中 binary 的版本（#335 verify codex lens）。

下載失敗、或 exec 的其實是舊 binary 時，state file 仍記著新版本 → hooks/session-start.sh 的 staleness 比對（#76/#77 機制）讀到「已是新版」→ 假陰性：不 SIGTERM、不重 spawn，使用者持續跑舊 binary 而無任何訊號。

Type

bug（imported pre-existing — #335 純 relocation 帶入）

Expected

State file 的 version 欄位改由實際 binary 回報（--version，#303 起可用）或在下載/驗證成功後才寫入；寫入時機與 #303 的 version sidecar、preflightAutomation staleness warning 對齊，避免三套機制各說各話。

Related

• refactor: plugin shell 從 aggregator 遷入本 repo 自營 marketplace（比照 che-ical-mcp） #335 verify report（PR refactor: co-locate the plugin shell with its binary source (#335) #338 conversation）
• wrapper: silent staleness — running MCP process doesn't detect plugin.json bump until restart #76 / wrapper: sidecar tracks plugin shell version, not binary version (binary-only releases silently skipped) #77 — staleness detection 機制
• A stale long-lived MCP server can still hang-to-disconnect: #297/#301 fix the server, but the session-boundary-only staleness kill can miss an old in-memory image #303 — server 自報版本 / version sidecar
• Staleness self-check is inert for Claude Desktop .mcpb installs — no version sidecar next to the packaged executable #312 — .mcpb install 無 sidecar（同族缺口）

Filed by /idd-verify Step 5b follow-up triage (unattended).

Current Status

Phase: implemented
Updated: 2026-08-26

📊 Dashboard comment

Tasks

• Diagnose — Simple（…6231）
• Implement — cluster PR fix: wrapper download-chain integrity + honest runtime version (#392, #393) #398（5308cb0：runtime version_at_spawn 改讀 sidecar 實際值）
• Verify
• Close

Blocking

（無）

[kiki830621]

Diagnosis

Type

bug

（issue 無 attachment — Step 1.5 空 manifest。）

Root Cause / Analysis

Issue 的主張需限縮範圍後成立（read-code 修正）：wrapper 有兩個版本記錄，狀態不同——

檔案	現況	判定
~/bin/.CheAppleMailMCP.version（sidecar）	已修：#77 起從 release URL 解析 ACTUAL 版本寫入（wrapper 內註解明載「keeps the sidecar honest」）	✅ 誠實
~/bin/.CheAppleMailMCP.runtime.json 的 version_at_spawn	仍寫 ${DESIRED_VERSION:-unknown} —— 期望值，不是實際值	❌ 本案標的

失效鏈（具體）：下載失敗但舊 binary 可用 → wrapper 保舊 binary 繼續 exec（正確的 fail-open）→ runtime.json 卻記 version_at_spawn = DESIRED（新版號）→ hooks/session-start.sh 比對 runtime vs plugin.json binary_version 相等 → 永不 kill/respawn → stale binary 無限期跑下去且零訊號。fallback-to-latest 路徑同構（ACTUAL=latest ≠ DESIRED，runtime 記 DESIRED）。

註：hook 端註解已寫「Runtime state records BINARY tag (per #77 fix to wrapper)」——hook 假設的契約正是 actual，是 wrapper 的 runtime 寫入端沒跟上 #77。本案是把 wrapper 對齊 hook 已文件化的假設。

Impact

• 影響檔案：plugin/bin/che-apple-mail-mcp-wrapper.sh（runtime 寫入區塊，~5 行）+ wrapper 測試
• 影響流程：wrapper: silent staleness — running MCP process doesn't detect plugin.json bump until restart #76/wrapper: sidecar tracks plugin shell version, not binary version (binary-only releases silently skipped) #77 staleness 偵測鏈的正確性（假陰性消除）

Strategy

• runtime 寫入前重讀 VERSION_FILE（sidecar = 實際安裝版本的 source of truth），version_at_spawn 改寫 sidecar 值；sidecar 缺失/不可讀才 fallback DESIRED（並記 unknown 優於說謊）
• 效果：下載失敗保舊時 runtime 記舊版 → hook 偵測 mismatch → SIGTERM respawn → wrapper 重試下載（這是期望的復原迴圈；下載持續失敗 = 每 session start 一次重試+一行警告，有界且可見）
• 測試併入 bug: wrapper 下載鏈零完整性驗證 — curl 缺 --fail、有 .sha256 asset 卻不驗、pinned-tag 落空每次 spawn 重下載 (#335 verify) #392 的 test-wrapper-download.sh（同 mock 基建）：下載失敗路徑斷言 runtime 記 INSTALLED 而非 DESIRED
• 驗收：mock 測試綠 + 手動情境（改 plugin.json pin 成不存在版本 → spawn → runtime.json 記實際版本）

Conflict Class

C_shared_module_coord — 共享資源具名：plugin/bin/che-apple-mail-mcp-wrapper.sh（與 #392 同檔）。與 #392 同 branch/cluster 實作。

Complexity

Simple

• 清晰 root cause + 單一寫入點修正 + 既有 pattern（sidecar 讀取已存在）；決策空間近零
• Hard-gate: not triggered — 單檔 ~5 行 + 測試斷言，無 shared abstraction 變更

Vagueness Pre-check

• V1: 2 — 寫入點與修法唯一（讀 sidecar）
• V4: 2 — 驗收條件機械可判（runtime.json 內容斷言）
• Triggered: no — both axes ≤ 3

Risks

1. 「每 session start kill+respawn+重試下載」在下載長期失敗時是重複動作 —— 有界（每 session 一次）且正是使用者該看到的訊號；不視為回歸
2. 與 bug: wrapper 下載鏈零完整性驗證 — curl 缺 --fail、有 .sha256 asset 卻不驗、pinned-tag 落空每次 spawn 重下載 (#335 verify) #392 改同一區塊 —— cluster 實作規避

Residue

(none)

[kiki830621]

📊 For Reviewer / Collaborator

現在：已實作（cluster PR #398 等 verify）：runtime 記實際版本，staleness 假陰性消除（測試斷言 ×3）。
Blocking：無
你該做什麼：等 6-AI verify → review PR #398。

last-updated by idd-implement at implemented, 2026-08-26

[kiki830621]

Verify round → PR #398

Implementation + the cross-model verify report are on PR #398 (shared with #392). Round 2 returned 65 findings, 18 HIGH.

Status: implemented, fixes pushed, NOT independently re-verified (MAX_ROUND=2 reached).

What round 2 changed for this issue — the retry story, which round 1 had backwards:

• degraded_pin was written on transient failures too. The session-start hook suppresses the kill whenever that field is set, and the kill is the only thing that makes Claude Code respawn the wrapper. So "will retry next spawn" meant never retries. The field is now written if and only if a .fallback-tried marker was written, stated as a named invariant at the top of the wrapper and locked by tests.
• The hook never checked the marker or its TTL, which made the degraded state permanent. The 24h TTL is only ever evaluated by the wrapper, which cannot run again until a kill respawns it — so at TTL+1h the hook was still suppressing and the pin was never retried. Deleting the marker by hand did not help either, because nothing consulted it. The hook now re-derives the decision from the marker itself (existence, pin, TTL, clock skew) and falls through to the normal stale kill once it lapses.
• The sidecar no longer falls back to the DESIRED pin when the tag cannot be parsed from the URL — that is exactly the bug: wrapper runtime state 記「期望版本」而非「實際執行版本」— 下載失敗時 staleness 偵測假陰性 (#335 verify) #393 lie. It writes unknown.
• The marker's third field (miss | verify) was written but never read, so a digest mismatch was reported as "unavailable upstream". It is now reported as a possible tampering signal.
• A fresh install that substitutes latest for an unresolvable pin now says so instead of silently deviating.

Suite: 76 asserts / 19 scenarios, including an expired marker lifting the suppression, a hand-deleted marker doing the same (the escape hatch the message advertises now actually works), and the negative control. Nine mutations run, nine caught.

Not closing — /idd-close stays yours.