トラブルシューティング¶
Skill または tool が見つからない¶
Plugin の install/update 後に新しい Codex session を開始します。installed
plugin-diagnostics Skill で manifest、provenance、明示的な update status、MCP health を確認します。
installed cache を直接編集して修復しません。
marketplace refresh 後も古い version が残る¶
exact-ref marketplace は一般的な marketplace refresh を実行しても、review 済みの immutable commit に留まります。これは想定された動作で、refresh の成功は固定 ref が進んだ証拠では ありません。完全な exact-ref update journeyに従い、対象を 検出・review し、安定した directory で packaged updater の preflight を実行し、exact transition を authorize・実行して、version/enabled/Release/provenance state を確認した後、新しい session を 開始します。
updater が rejected を返した場合は required action に従います。update effect は発生して
いません。rolled-back の場合は failure evidence を保持し、新しい session で復元された exact
identity を確認します。unresolved の場合は retry や独自の remove/add をせず、追加 effect の
前に exact marketplace と Plugin state を調べます。config.toml、marketplace JSON、installed
cache を手作業で編集しません。
GitHub operation を実行できない¶
選択 provider で repository identity、authentication、permission を確認します。AI Teams は 先行 provider が unavailable、unauthorized、unsupported と明示された場合だけ対応 fallback へ進みます。成功を捏造せず、system of record を黙って変更しません。
Validation が通らない¶
failed evidence を保持します。candidate failure は修正し、runner/workflow unavailable は isolated
self-hosted path を復旧します。merge には新しい exact-head hosted validate success が必要で、
local result や skipped check は waiver になりません。
Windows mount 上の WSL path で worktree validation が停止する¶
AI Teams の worktree readiness と CI preflight には Linux-native filesystem semantics が
必要です。/mnt/c や /mnt/d のような Windows-mounted path 上に repository/worktree を置くと
DrvFS/9P operation で停止することがあるため、Issue worktree だけを Linux-native filesystem
へ移すことで supported-path mismatch を避けられます。
Linux-native は literal /home を必須にせず、WSL virtual disk を Windows system drive に置く
ことも要求しません。VHDX は配置した Windows drive の容量を消費します。容量が問題になる場合は、
worktree を DrvFS/9P に戻さず、Microsoft の現行
WSL distribution relocation guidance
に従ってください。移設手順は Microsoft 所有で destructive step を含むため、host を変更する前に
同ページで backup と version の前提を確認してください。
install と MCP の詳細は machine-facing diagnostic contractを参照してください。