本卡屬 FR-188（母卡），實作 D1、D2 的主系統端。依賴 S-1（套件重排與重新取檔）、E-1（環境卡）。嚴重度：高。
三件事。一、取檔失敗時，不管真正原因是前門擋下（413）、Agent 送了但檔不見、還是 Agent 真的連不上，畫面一律只看到「取回 Agent 掃描結果失敗（InternalServerError）」，查錯方向全錯。二、主系統處理完不會告訴 Agent 結果，Agent 只知道「紀錄送到了」就標「已回傳」，兩邊狀態矛盾。三、失敗的那筆在主系統上沒有「重新取檔」可以按。
首腦核對：今天雲端兩種失敗分別是 FILE_AGENT_500001（30 秒等不到回覆，實際是前門 413）與 FILE_AGENT_500002（Agent 回 done 但暫存檔不在，實際是 worker 讀不到 API 的暫存）。兩者在 sbom_scan_result_handler._process 都被包成 RESULT_FETCH_FAILED＋例外類名。
/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/infra/upload_file/remote_agent_adapter.py:206 _receive：spool.open 為 None → FILE_AGENT_BAD_RESPONSE
/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/infra/upload_file/remote_agent_adapter.py:216 _ask：AgentNoReply／AgentBusy → UNREACHABLE；AgentRequestFailed → BAD_RESPONSE
/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/common/code/error_code.py:24 FILE_AGENT_UNREACHABLE／FILE_AGENT_BAD_RESPONSE
/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/core/plugins/_source_scan_agent_gateway.py:80 fetch_agent_files
/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/api/remote_agent/routes/agent_local_run_route.py 主系統「Agent 掃描執行紀錄」API
/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/app/remote_agent/service/agent_request_service.py ask／逾時
/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be/core/plugins/_agent_commands.py 長輪詢指令送出
_ask／_receive 依實際原因給不同錯誤碼與白話訊息：等不到回覆（Agent 離線或回覆被擋下）、Agent 回 failed（附 Agent 給的 reason）、回 done 但檔不在。訊息要能讓人判斷下一步，例如「Agent 有回應但主系統收不到檔案，可能是前門大小限制或暫存設定」。新錯誤碼加在 common/code/error_code.py，命名照 <前綴>_<HTTP碼><序號>，同步 FE error-code.json（FE 那邊在 F-1 改，本卡回寫列出新碼）。失敗原因寫進 source_scans.error，不再只寫例外類名。agent_local_uid、ok、reason）。先查 jedi-agent-protocol 既有 kind 能不能承載；不能就停下回寫問首腦，不自己在協定套件加 kind。不夾帶在心跳。failed 的第三方元件手動掃描提供 POST .../refetch，呼叫 S-1 的套件服務。權限檢查在 app service 層走 common.authz（管理員或發起者，照既有下載報告的守門）；寫稽核。路由加進 FE api.js 的部分在 F-1 做。_ask／_receive 三種原因各回對應錯誤碼（突變：把分類合併回一個碼要紅）。refetch 對非 failed 回 409。common/code/error_code.py（登記型共用檔），本批其他卡不改它。feature/FR-172，不切 branch；顯式 git add <檔名>、禁 -am；只 add 自己改的檔。commit 不等令，push 由決策者做。修正待驗證。卡住也 commit 已完成部分並回寫卡在哪，狀態維持 In progress。