Lat Dispatch

LAT Dispatch

Client 設定

可用 client、指令格式、解析優先序、內建預設、config.yaml 格式參見 references/clients.md。

內建 Subagent 路由與等待

• 每個委派階段先解析目標 client，再比較 Dispatch 宿主與目標模型家族；同宿主使用內建 subagent，跨宿主才使用外部 CLI client。
• 同宿主派發時讀取 references/native-subagents.md；跨宿主才讀取 references/clients.md 的 CLI 啟動、Monitor 與恢復章節。
• Codex 呼叫 GPT／Codex worker 時使用內建 spawn_agent，再以 wait_agent 直接等待完成通知或 mailbox 更新。
• Claude Code 呼叫 Claude worker 時使用內建 Agent；前景直接等完成，背景等待 completion notification 或使用 blocking TaskOutput。
• 內建 subagent 等待期間不得固定輪詢 subagent 狀態。等待明確逾時或異常時只做一次診斷；worker 仍在執行且無確認錯誤時，重新進入 blocking wait。
• 各 phase 的等待分流一致：內建 subagent 直接等待完成通知；外部 CLI 才啟動 Monitor。
• 內建 subagent 不啟動 CLI、zmx、PID file、Session JSONL Monitor。收到完成通知後仍依角色契約處理 Final Answer、review adjudication、executor ledger 與 QA evidence。
• 外部 CLI 的啟動、監控、恢復與錯誤處理維持 references/clients.md 的既有契約。

Available scripts

• scripts/monitor-session.sh — 監控 Codex／Claude 原始 Session JSONL 並提取最新 turn 的 Final Answer
• scripts/run-exec-client.sh — exec launcher：啟動 exec client、保存精確 PID、將 FD1／FD2 捕捉為帶 UTC capture time 的 runtime logs、等待退出並清理 PID file

預設流程

使用者啟動 LoopAgentTeams 時，自動執行，僅在 spec 階段需使用者確認（依 spec_review_flow）：

進度檢查清單 — 每次啟動 LoopAgentTeams 時建立追蹤，逐項完成後才進入下一階段：

- [ ] init：建立 `.lat/logs/` 與 `.lat/workspace/`，遷移舊全域 ledger
- [ ] spec：腦力激盪 → 草稿／確定 TASK_ID → 初始化 task workspace 與空 ledger → 審查（依 spec_review_flow）→ 使用者確認
- [ ] plan：產生計劃 → 審查迴圈 → 規格與計劃一起提交
- [ ] dispatch：驗證既有 `.lat/workspace/<TASK_ID>/` ledger → 附加 code task → 啟動 code_executor
- [ ] monitor：內建 subagent 等待完成通知／外部 CLI 監控原始 Session JSONL → 將 Final Answer 交給 Dispatch；executor 另確認 task ledger
- [ ] test：test_executor 寫+跑整合與 E2E 測試修到綠 → qa_executor 依 QA 清單寫驗收測試至 qa_e2e/ → 失敗回饋 test_executor 修，迴圈到全過或達上限
- [ ] report：`clean <TASK_ID>` 清理已完成的 task-scoped zmx sessions → 向使用者報告最終狀態

• 每個階段轉換以一句話報告進度。
• 不得推斷完成狀態。 只有實際執行該階段的檢查步驟後，才可勾選完成。
• 不得跳步。 除非使用者明確要求跳過特定步驟。

外部 CLI Monitor 完成契約

• 外部 CLI 執行監控時從本技能目錄呼叫 scripts/monitor-session.sh；不要在 prompt 或臨時 shell 中重寫監控迴圈。client 啟動與 session 定位方式見 references/clients.md。內建 subagent 不使用本節 Monitor。
• Codex 監控只傳 agent_id 時由腳本自動定位 JSONL；定位 STALL 時，Dispatch 擴大搜尋並人工確認後，以 --jsonl-path "$JSONL_PATH" 重啟 Monitor。
• Claude exec 與 TUI 都監控 Project transcript；最新人類 prompt 之後的 assistant text 加 stop_reason: "end_turn" 表示該 turn 完成，last-prompt 不得視為完成標記。
• Codex exec 與 TUI 都監控原生 Session JSONL；同一 turn 必須同時有 response_item 的 phase: "final_answer" 與 event_msg.payload.type: "task_complete" 或 "turn_complete"。
• COMPLETED 只代表最新 turn 已輸出 Final Answer 並結束，不代表 exec OS 程序已 EOF／退出或 exit code 為 0。
• Codex 最新 turn 已有 task_complete／turn_complete 卻沒有 Final Answer 時，Monitor 立即回報 INCOMPLETE；Dispatch 不得從 rollout 欄位猜測原因，須依 references/clients.md 先驗證帳號配額，再檢查 client 對應的診斷來源。
• Monitor 不建立、自訂或重新導向 exec log；四種 client 模式皆直接讀 CLI 原始 Session JSONL，並將 Final Answer 原文交給 Dispatch Agent。
• 監控來源的修改時間有變動表示仍有活動，超過該階段 stall 秒未變才回報 STALL。
• review 階段的內建值為 stall: 600、drift: 1800；同一 client turn 的初次 Monitor 與 re-arm 必須重用同一組已解析值。
• Claude Code Dispatch 呼叫 Monitor 時固定使用 timeout_ms: 3600000、persistent: true；生命週期由 bundled script 的終端事件控制。
• 單一 STALL 只觸發診斷，不授權 kill。exec 依 references/clients.md 使用啟動時保存的 PID；TUI 仍使用 zmx session handle。
• spec_reviewer、plan_writer 與非 self 的 plan_reviewer 不寫 task ledger；內建 subagent 以完成通知交回 Final Answer，外部 CLI 由 Monitor 交回 Final Answer。self plan_reviewer 不委派 agent，也不寫 task ledger。
• code_executor、test_executor、qa_executor 不論使用 exec 或 tui，都須寫 .lat/workspace/<TASK_ID>/results.yaml 並更新同目錄 tasks.yaml 的精確 agent_id 狀態。流程狀態以 ledger 為準，Final Answer 僅供摘要與診斷。
• ledger 出現結果不能單獨代表 turn 已完成；executor 還須收到內建 subagent 完成通知或外部 Monitor COMPLETED，才能進入下一階段。

審查裁決（Dispatch Independent Adjudication）

Reviewer 的 verdict 與 finding 都是待驗證主張，不是 phase 的最終權威。Dispatch 不得只閱讀 Reviewer Final Answer 或因其回覆 PASS／NEEDS_REVISION 就直接決定下一步。

作者送審前先自檢完整性、使用者已確認需求、QA 對應、placeholder 與內部矛盾。Reviewer 完成後，Dispatch 必須重新讀取目前文件、使用者決策、QA 清單，以及 finding 引用的程式碼、設定、測試或官方資料，逐項分類：

• ACCEPT：證據成立，交回原作者修正。
• REJECT：證據不成立，記錄具體駁回理由。
• USER_DECISION：涉及多解的產品或架構決策，暫停並詢問使用者。

Reviewer 回覆 PASS 時，Dispatch 仍須執行 focused gap scan，至少檢查需求範圍、已確認決策、QA 可測試性及高風險假設。PASS 後的 focused gap scan 不是改善清單；只有具體違反已確認需求／QA、可重現失敗、或對主 task 造成直接 regression 時，才重新開啟 review。措辭、格式、命名偏好、註解、文件潤飾、可選 refactor，以及與主 task 無直接關聯的微小改善，不建立 finding、不交回修正、不延長 phase。

Reviewer 的範圍以已確認的 Spec、Plan、使用者決策，以及派發時具名的實際風險為 界線。Finding 若無法指出對應需求，或沒有可重現的失敗／攻擊路徑，只能標為 optional hardening，不得阻擋 phase。Dispatch 應拒絕把假設性的極端情境升格為 新需求，除非它直接影響既有驗收項或已具名的安全邊界。

第一輪審查讀取完整目標。作者依 accepted findings 修正後，re-review 只提供前輪 findings、修正基準與該基準之後的增量 diff；Reviewer 只驗證 findings 是否修正及 增量是否造成直接 regression。只有增量顯示架構已重寫、基準不可信，或具體證據 指出未修改區域受影響時，才重新讀取完整目標，並在結果中說明原因。 Dispatch 啟動 re-review 前，必須將 <prior_findings>、<revision_base> 與 <incremental_diff> 解析為實際內容或可讀取的安全檔案路徑；不得保留 placeholder， 也不得只要求新的 Reviewer 自行尋找前輪結果。

同一審查鏈的 re-review 優先 resume 原 Reviewer Session，開始新的 review round 但 維持原 reviewer instance、model、effort 與 permission。只有原 Session 無法恢復、 需要改變 model／effort、修正已造成架構重寫或基準失效、Dispatch 已以證據判定原 Reviewer 不可靠，或使用者要求獨立 final review 時，才建立新的 Reviewer Session 與 instance。

Reviewer 為 report-only，不得直接修改 Spec／Plan。若有 accepted findings，原作者修正並再次自檢，再啟動下一 round Reviewer 與新的 Dispatch 裁決。Reviewer verdict 與 Dispatch adjudication 都完成後，phase 才能通過；若 Reviewer 回覆 NEEDS_REVISION 但所有 finding 均被 Dispatch 以證據 REJECT，focused gap scan 通過後仍可批准。

plan_reviewer.client: self 時沒有外部 Reviewer verdict 或額外 adjudication：Dispatch 直接依相同證據標準完整審查 Plan、產生 findings，並將修正交回原 plan_writer。Dispatch 在 self review 中不得直接修改 Plan。

暫停條件： 設計歧義需使用者決策、審查發現多解的重大問題、不可恢復的錯誤、執行結果 failed。

不暫停： 小修正（直接修正後繼續）、計劃缺漏（回饋再審）、503 錯誤（自動重試）、單帳號配額耗盡（自動切換）、測試失敗（executor 自行處理）。

指令

init

1. 在專案根目錄建立 .lat/（如不存在）。
2. 確保 .gitignore 排除 .lat/；若無則新增並提交。
3. 建立 logs/ 和 workspace/ 子目錄（如不存在）。不建立全域 .lat/tasks.yaml 或 .lat/results.yaml。
4. 若存在舊的全域 .lat/tasks.yaml 或 .lat/results.yaml，依 references/yaml-schema.md 的遷移流程按 task_id 分組；完整驗證後才用 trash-put 移除舊檔。

spec

審查流程（spec_review_flow）：

解析優先序同其他維度：使用者 prompt > .lat/config.yaml > 內建預設（ai-first）。

1. 使用 Superpowers 腦力激盪工作流，與使用者討論目標、範圍與交付內容。

2. 腦力激盪完成後，spec_writer 撰寫規格初稿；Spec 檔名（不含 .md）同時確定本輪 TASK_ID。

3. 驗證 TASK_ID 是安全 slug，建立 .lat/workspace/<TASK_ID>/ 與 prompts/，並將 tasks.yaml、results.yaml 初始化為 []。若 workspace 已存在，須解析並驗證兩個 ledger；不得清空、覆寫或刪除既有 task/result 歷史，缺少或損壞時暫停請求人工處理。初始化完成後才啟動 reviewer。

4. spec 須含「驗收清單（QA）」章節。每條 Q 以可觀察的使用者行為描述目標（不用實作字眼），A 寫解法與對應測試／證據。隨規格一起確認。

5. Dispatch/spec_writer 完成送審前自檢：確認需求範圍、使用者決策、QA 對應、placeholder 與內部矛盾。

6. 若 user-first： 暫停，向使用者呈現草稿全文，等待使用者同意。使用者可要求修改，修改後重新自檢，直到同意。

7. 依 spec_reviewer 的目標 client 與同宿主路由呼叫 report-only 審查（agent_id = spec_reviewer_<instance>_<task_id>，instance 從 1 起算）。Reviewer 不修改檔案；每個 finding 須提供 finding ID、嚴重度、主張、具體證據與建議。

   spec_reviewer prompt：

   [<agent_id>] Review the spec at <spec_file>. Do not modify the spec file. Stay bounded to the user-confirmed scope and named practical risks; label unsupported extra hardening as optional and non-blocking. Check completeness, ambiguity, missing edge cases, user-confirmed scope, and testability of every QA item. When current library, framework, SDK, API, CLI, or cloud-service documentation is needed, use the existing Context7 MCP; do not install a Context7 CLI or change permissions or other MCPs. Report VERDICT: PASS or NEEDS_REVISION. For every finding include a stable finding ID, severity, claim, concrete evidence with file/section references, and recommendation.
   

   spec_reviewer re-review prompt：

   [<agent_id>] Re-review the revised spec at <spec_file>. Do not modify the spec file. Prior findings: <prior_findings>. Revision base: <revision_base>. Incremental diff: <incremental_diff>. Verify only whether the prior findings are resolved and whether the incremental diff causes a direct regression. Reopen the full artifact only if the delta changes architecture or concrete evidence implicates an unaffected section, and explain why. Report VERDICT: PASS or NEEDS_REVISION. For every unresolved or new finding include a stable finding ID, severity, claim, concrete evidence with file/section references, and recommendation.
   

8. 內建 subagent 直接等待完成通知；外部 CLI 才依 references/clients.md 監控原始 Session JSONL。收到 Final Answer 後，Dispatch 依「審查裁決」逐項驗證 finding，並在 Reviewer PASS 時執行 focused gap scan。

9. ACCEPT findings 由 Dispatch/spec_writer 修正後重新執行送審前自檢，再解析 re-review prompt 的三個增量 placeholder；下一 review round 優先恢復原 spec_reviewer Session 並維持原 reviewer instance，只有符合「審查裁決」的 fresh Session 條件時才建立下一個 instance。REJECT 記錄證據後不採用；USER_DECISION 暫停詢問使用者。

10. 迴圈直到 Reviewer verdict 與 Dispatch adjudication 都允許通過。不將審查或裁決工作寫入 tasks.yaml。

11. 向使用者呈現最終規格，等待確認後視為規格核准。

12. 中斷時依 references/clients.md 的中斷防護與 Session 恢復流程處理。

plan

1. 規格核准後才開始。

2. 使用 Superpowers 撰寫計劃工作流，依 plan_writer 的目標 client 與同宿主路由產生實作計劃（agent_id = plan_writer_<instance>_<task_id>）。instance 是邏輯 Agent 實例序號：首次指派為 1；恢復同一 Writer Session 修改時維持原 instance；只有原 Session 無法恢復或 Dispatch 明確改派新的 plan_writer Session 時，才以既有最大 Writer instance 加 1。Writer instance 與 plan_reviewer 的 review round 各自獨立。

   plan_writer prompt：

   [<agent_id>] Read the approved spec at <spec_file>. Write an implementation plan that covers all requirements and maps each QA acceptance item to concrete integration/E2E test targets and qa_executor verification methods. When current library, framework, SDK, API, CLI, or cloud-service documentation is needed, use the existing Context7 MCP; do not install a Context7 CLI or change permissions or other MCPs. Write test targets in English. Save the plan to <plan_file>. Before finishing, self-check scope coverage, QA mappings, placeholders, contradictions, and executable commands.
   

3. 計劃須將 spec 的每一條 QA 驗收項對應到具體的整合／E2E 測試目標，以及 qa_executor 的驗收方式。測試目標以英文撰寫。

4. 內建完成通知或外部 Monitor 回傳 writer Final Answer 後，Dispatch 確認原 plan_writer 已完成送審前自檢，再依解析出的 plan_reviewer.client 分流：

   • plan_reviewer.client 為 self：Dispatch 完整審查 approved Spec、Plan、使用者決策、QA 對應、相關程式碼、順序、依賴、失敗處理與命令可執行性。self 模式不建立 plan_reviewer Agent ID、prompt file、PID、Session 或 Monitor；Dispatch 不得直接修改 Plan。每個 finding 仍須提供穩定 finding ID、嚴重度、主張、具體證據與建議。
   • 使用者覆蓋為外部 client：啟動 report-only plan_reviewer（agent_id = plan_reviewer_<instance>_<task_id>，instance 從 1 起算）。Reviewer 不修改檔案；每個 finding 使用相同格式。

   外部 plan_reviewer prompt：

   [<agent_id>] Review <plan_file> against the approved spec at <spec_file>. Do not modify the plan file. Stay bounded to the approved spec, user decisions, and named practical risks; label unsupported extra hardening as optional and non-blocking. Check complete requirement coverage, every QA-to-test mapping, sequencing, dependencies, rollback or failure handling where relevant, and command executability. When current library, framework, SDK, API, CLI, or cloud-service documentation is needed, use the existing Context7 MCP; do not install a Context7 CLI or change permissions or other MCPs. Report VERDICT: PASS or NEEDS_REVISION. For every finding include a stable finding ID, severity, claim, concrete evidence with file/section references, and recommendation.
   

   外部 plan_reviewer re-review prompt：

   [<agent_id>] Re-review the revised plan at <plan_file> against the approved spec at <spec_file>. Do not modify the plan file. Prior findings: <prior_findings>. Revision base: <revision_base>. Incremental diff: <incremental_diff>. Verify only whether the prior findings are resolved and whether the incremental diff causes a direct regression. Reopen the full artifact only if the delta changes architecture or concrete evidence implicates an unaffected section, and explain why. Report VERDICT: PASS or NEEDS_REVISION. For every unresolved or new finding include a stable finding ID, severity, claim, concrete evidence with file/section references, and recommendation.
   

5. self 模式由 Dispatch 直接決定 PASS、NEEDS_REVISION 或 USER_DECISION。非 self 模式依同宿主路由等待內建完成通知，或依 references/clients.md 監控外部 reviewer 原始 Session JSONL；再由 Dispatch 依「審查裁決」驗證 finding，並在 Reviewer PASS 時執行 focused gap scan。

6. 需要修正的 findings 交回原 plan_writer Session 並維持原 instance；若無法恢復或 Dispatch 明確改派，才啟動新的 plan_writer Session 並將 instance 加 1。writer 修正後重新送審前自檢：self 模式由 Dispatch 再次完整審查；外部模式解析 re-review prompt 的三個增量 placeholder，下一 review round 優先恢復原 plan_reviewer Session 並維持原 reviewer instance，只有符合「審查裁決」的 fresh Session 條件時才建立下一個 instance。USER_DECISION 暫停詢問使用者。

7. 迴圈直到 self Dispatch review 通過，或外部 Reviewer verdict 與 Dispatch adjudication 都允許通過。不將計劃撰寫、審查或裁決工作寫入 tasks.yaml。

8. 中斷時依 references/clients.md 的中斷防護與 Session 恢復流程處理。

9. 規格與計劃皆核准後一起提交：

   git commit -m "docs: add <feature-name> spec and implementation plan"
   

dispatch

1. 確認計劃已通過完整審查迴圈（不是僅存在或看似完成）。

2. 建立一個摘要任務指向計劃檔案，不拆分為多個細粒度任務。

3. 驗證既有 .lat/workspace/<TASK_ID>/、tasks.yaml 與 results.yaml 均存在且可解析，並確認 task/result 內的 task_id 都匹配目錄名稱；缺少或損壞時暫停，不得自行重建或重設。確認 code_executor_1_<task_id> 尚未存在後，附加 code task 至 tasks.yaml，欄位順序與格式參見 references/yaml-schema.md。

   • task_id：Spec 檔名（不含 .md），如 2026-07-09-user-api-spec
   • agent_id：code_executor_1_<task_id>
   • goal：一句話描述完整實作範圍
   • context.plan_file、context.spec_file、context.related_files
   • constraints：保留計劃與使用者的實作約束
   • created_by：目前 agent 的識別名稱

4. 依解析出的 code_executor client 與同宿主路由啟動執行：同宿主使用內建 subagent，跨宿主按 references/clients.md 的 CLI 指令格式啟動。

   lat-code prompt：

   [<agent_id>] You are the lat-code executor for TASK_ID '<task_id>'. Read .lat/workspace/<task_id>/tasks.yaml and process only the exact pending task whose agent_id is '<agent_id>', following the lat-code skill. Use sub-agents to parallelize independent development work when beneficial. Upsert the result into .lat/workspace/<task_id>/results.yaml, update the same task entry to its final status without deleting it, then exit.
   

5. 內建 subagent 直接等待完成通知；外部 CLI 才依 references/clients.md 啟動 Monitor 並等待 COMPLETED。取得 Final Answer 後，Dispatch 再讀取 .lat/workspace/<TASK_ID>/results.yaml 中精確匹配 task_id、agent_id 的結果，並與 tasks.yaml.status 交叉確認後決定是否進入 test。外部 CLI 的 monitor.enabled: false 或使用者說「不要監控」時跳過監控，直接告知使用者手動檢查。

6. 錯誤處理依 references/clients.md 的錯誤處理章節。

7. tui client 時告知使用者可用指令：zmx attach <session>（即時檢視）、zmx list（所有工作階段）、Ctrl+\（脫離 attach 不終止）。

test

1. 確認 .lat/workspace/<TASK_ID>/ 中 code_executor 的 task 與 result 狀態皆為 completed。

2. 依 test_executor 的目標 client 與同宿主路由啟動測試 agent；只有外部 TUI client 建立 zmx session。

   首次 test_executor prompt（agent_id = test_executor_1_<task_id>）：

   [<agent_id>] Read the spec at <spec_file> and the test targets in <plan_file>. Following the three-tier-testing skill, write and run integration tests and E2E tests for the implemented code. If a test exposes a product defect, fix the implementation code rather than weakening the tests, then re-run the affected tests until they pass. Use sub-agents to parallelize independent test writing when beneficial. Do not write or modify unit tests. During the fix loop, run only the failing tests and the smallest covering tests for changed behavior; do not repeatedly run whole tiers. Once the covering set is green, finish without a full regression because Dispatch runs that gate once after QA passes. E2E tests go in the project's E2E test directory (tests/e2e/ or <frontend>/tests/e2e/). When finished, upsert your result into .lat/workspace/<task_id>/results.yaml and update your exact entry in .lat/workspace/<task_id>/tasks.yaml to the same final status following the yaml-schema — task_id is '<task_id>', agent_id is '<agent_id>'.
   

3. 先將 test task 以 status: running 附加到該 task ledger；內建 subagent 直接等待完成通知，外部 CLI 才依 references/clients.md 監控。接收 Final Answer 後，以 tasks/results 中精確匹配的狀態判斷成功、部分完成或失敗。

4. test_executor 全部通過後，將 qa task 以 status: running 附加到同一 ledger，再依 qa_executor 的目標 client 與同宿主路由啟動獨立驗收（agent_id = qa_executor_<instance>_<task_id>；首次 instance 為 1，每次修正後重新驗收時啟動新的 Agent Session 並增加 instance）。

   qa_executor prompt：

   [<agent_id>] Read the spec at <spec_file> and its acceptance checklist (QA). Following the three-tier-testing skill, launch and drive the real application as a user would, and verify each acceptance item by observing actual behavior — do NOT rely on the existing test suite. Use sub-agents to parallelize independent checklist items when beneficial. For every checklist item, write an E2E test in tests/qa_e2e/ (or <frontend>/tests/qa_e2e/) that encodes the acceptance criterion, run it against the real application, and record the result. Do not modify implementation code or existing test files. Write your results to .lat/workspace/<task_id>/qa-results.md — report each item as PASS or FAIL with evidence (command + output/log/screenshot); for FAIL include expected versus observed. Also upsert your result into .lat/workspace/<task_id>/results.yaml and update your exact tasks.yaml entry to the same final status — task_id is '<task_id>', agent_id is '<agent_id>'.
   

5. 讀取 .lat/workspace/<task_id>/qa-results.md，將每個未通過項目分類為 PRODUCT_FAILURE、QA_INVALID、TOOL_OR_ENVIRONMENT_FAILURE，並依 references/clients.md 決定下一輪 QA effort：

   • 全部 PASS → 進入步驟 8 的完整回歸 gate。
   • QA_INVALID → 先將新的 qa task 以 status: running 附加到 ledger，再啟動新的 qa_executor Agent Session 修正驗收方法（agent_id = qa_executor_<instance>_<task_id>，instance 使用該 phase 的下一個序號）；若同輪另有 PRODUCT_FAILURE，待重新建立可信驗收結果後再處理。
   • PRODUCT_FAILURE → 啟動新的 test_executor Agent Session 修正實作（agent_id = test_executor_<instance>_<task_id>，instance 使用該 phase 的下一個序號）。
   • TOOL_OR_ENVIRONMENT_FAILURE → 不啟動 test_executor；依「Sub-Agent 異常診斷」修復或以相同 effort 重試，取得有效驗收結果後重新分類。

   QA_INVALID 修正輪 qa_executor prompt：

   [<agent_id>] Previous QA execution was classified as QA_INVALID. Read the spec at <spec_file>, its acceptance checklist, and .lat/workspace/<task_id>/qa-results.md. Correct only the affected acceptance tests under tests/qa_e2e/ (or <frontend>/tests/qa_e2e/) and re-run them against the real application until each affected item has consistent PASS or FAIL evidence. Do not modify implementation code or tests outside the QA acceptance directory. Update .lat/workspace/<task_id>/qa-results.md with command and output/log/screenshot evidence, then upsert your result into .lat/workspace/<task_id>/results.yaml and update your exact tasks.yaml entry to the same final status — task_id is '<task_id>', agent_id is '<agent_id>'.
   

   修正輪 test_executor prompt：

   [<agent_id>] Acceptance verification failed. Read the spec at <spec_file> for requirements context, and read .lat/workspace/<task_id>/qa-results.md for the failed items and evidence. Fix the implementation code so the real application satisfies these items. Re-run only the failing QA tests and the smallest covering tests for the changed behavior; do not run a whole-tier regression. Do not modify test files in tests/qa_e2e/. When finished, upsert your result into .lat/workspace/<task_id>/results.yaml and update your exact tasks.yaml entry to the same final status — task_id is '<task_id>', agent_id is '<agent_id>'.
   

6. qa_executor 同樣必須由內建完成通知或外部 Monitor 接收 Final Answer；驗收狀態以該 task directory 的 tasks/results ledger 與 qa-results.md 為準。QA_INVALID 修正輪完成後回到步驟 5 重新分類；test_executor 修完後回到步驟 4（qa_executor 重新驗收）。

7. 迴圈直到 qa_executor 全部 PASS，或達到重試上限（test.max_retries / test.max_retries_per_task）。超過上限時暫停，向使用者報告失敗細節與證據。

8. QA 全部 PASS 後，Dispatch 依 Plan 中已定義的驗證命令執行一次完整回歸。完整回歸只在此 gate 執行一次；若失敗，記錄精確失敗後建立下一個 test_executor 修正，且該修正輪同樣計入 test.max_retries 與 test.max_retries_per_task。修正期間仍只跑 covering tests，下一次 QA 通過後才再執行一次完整回歸。

9. tui client 時告知使用者可用指令：zmx attach <session>（即時檢視）、zmx list（所有工作階段）、Ctrl+\（脫離 attach 不終止）。

10. 中斷時依 references/clients.md 的中斷防護與 Session 恢復流程處理。

report

1. 先執行 clean <TASK_ID>，依 clean 契約清理目前 task 已完成的 zmx sessions；無法安全清理者保留並記入報告。
2. 完成 cleanup 後向使用者報告最終狀態：需求摘要、交付內容、git diff 變更範圍、逐條 QA 驗收項的結果與證據（指令 + 輸出）、測試結果、變更檔案清單，以及保留的 zmx session 與原因。

status

1. 掃描 .lat/workspace/<TASK_ID>/；task directory 不存在表示沒有該任務，既有 workspace 的 tasks.yaml／results.yaml 內容為 [] 視為正常空 ledger，任一 ledger 遺失、空字串或無法解析則回報狀態損壞，不得自行重建或重設。
2. 依 task_id 摘要 pending、running、completed、failed、partial 與結果歷史。
3. 執行 zmx list，顯示 cx- / cc- 工作階段狀態。

clean

1. 不重設或刪除任何 task directory 的 tasks.yaml、results.yaml 或 qa-results.md。
2. clean <TASK_ID> 先驗證 TASK_ID 與既有 workspace，再讀取 .lat/workspace/<TASK_ID>/runtime/*.zmx-session。每個 regular file 必須只有一行、符合 [A-Za-z0-9._-]+ 且以 cx- 或 cc- 開頭；格式不符即保留並回報。
3. 將保存的名稱與 zmx list --short 做精確匹配。只有對應 Agent 已有內建完成通知或外部 Monitor COMPLETED，且 executor 的 tasks/results（如適用）已是終端狀態時，才執行 zmx kill "$SESSION_NAME"。不得依 TASK_ID、agent_id 或名稱片段猜測未保存的 session，不得使用 --force，也不得把 session 消失視為 phase 完成證據；證據不足或精確名稱不存在時保留並回報。
4. 以 trash-put 清理 .lat/workspace/*/prompts/ 中超過 prompts.retention_days（預設 7）天的暫存 prompt。
5. 以 trash-put 清理 .lat/logs/ 中超過 logs.retention_days（預設 60）天的檔案；runtime logs 只能在對應 exec 已不在執行時清除——${PID_FILE}.lock ownership lock 存在時跳過該 agent_id 的 logs，保留並回報，不得自動判定或清除 stale lock；無 lock 時，.lat/workspace/<TASK_ID>/runtime/<agent_id>.pid 仍有有效 PID（kill -0 存活）也跳過。PID file 遺失表示 exec 已結束、可清；PID 格式錯誤時不得以 pgrep 猜測，保留該組 logs 並回報。

purge

只有使用者明確指定 purge <TASK_ID> 時才進入此流程。驗證 TASK_ID 後，先檢查該 task 的全部 runtime ownership：任何 ${PID_FILE}.lock ownership lock 存在、任何 PID file 仍有有效 PID（kill -0 存活），或任何 PID 格式錯誤時，一律保留 .lat/workspace/<TASK_ID>/ 與 .lat/logs/<TASK_ID>/，回報後停止 purge；不得自動判定或清除 stale lock，也不得以 pgrep 猜測程序。只有沒有 ownership lock，且所有 PID file 都遺失或記錄的程序已不存在時，才可用 trash-put 刪除上述兩個 task 目錄。一般 clean 永不刪除 task ledger。

Sub-Agent 異常診斷

任何 phase 的 sub-agent（spec_reviewer、plan_writer、外部 plan_reviewer、code_executor、test_executor、qa_executor）回報工具相關錯誤時，適用本流程。

核心原則

• 不信 sub-agent 的自我診斷。 Sub-agent 回報「沒有權限」「沒有此工具」「工具不可用」時，視為待驗證，不視為事實。常見原因是工具呼叫參數錯誤，sub-agent 誤判為權限問題。
• 不代做。 Dispatch 絕對不接手 sub-agent 的任務。即使 sub-agent 看起來卡住，也只能診斷與通知，不可自行執行該 phase 的工作內容。

診斷流程

先依派發路由選擇下列流程，不得把外部 CLI 的 JSONL、PID、zmx 或 resume 契約套用到內建 subagent。

內建 subagent 診斷

1. **驗派發：**確認內建工具參數、model、effort、permission、canonical agent_id 與 prompt 正確；runtime handle 依 references/native-subagents.md 另行保存。
2. **查原生結果：**Codex 讀取 wait_agent／mailbox 回傳與保存的 runtime agent ID／path；Claude Code 讀取 Agent result／task notification 與保存的 runtime agentId。只在等待明確逾時或異常時查一次狀態，不固定輪詢。
3. **通知原 agent：**Codex 依 agent 是否仍在執行使用 send_message／followup_task；Claude Code 以 Agent 的 resume: <runtime_agent_id> 延續原 subagent。訊息須包含實際錯誤、原因與修正方向。
4. **缺少 Final Answer：**內建 subagent 已結束但沒有可用 Final Answer 時，不得視為完成，也不得改查外部 CLI JSONL。先用保存的 runtime handle 與原生結果診斷；能續傳時要求同一 subagent 補交結果，不能續傳時暫停並報告原生錯誤證據。

外部 CLI sub-agent 診斷

1. 驗指令 → 確認 Dispatch 下的啟動指令正確
2. 查 Session → 讀取 sub-agent 的原始 Session JSONL，找到實際錯誤訊息
3. 通知    → 把真正的錯誤原因告訴 sub-agent，讓它自行修正

外部步驟 1 — 驗指令： 確認啟動指令的 permission / sandbox flag、model、prompt 格式皆正確。若指令本身有誤，修正後重新啟動 sub-agent。

外部步驟 2 — 查 Session： .lat/logs/ 不是完成或診斷的主要來源。必須直接讀取主機上 CLI 工具的完整原始 Session JSONL。

每個 phase 的啟動 prompt 皆以 [<agent_id>] 開頭（如 [test_executor_1_2026-07-09-user-api-spec]），因此可用 agent_id 在 session 目錄中精確定位對應的 session 檔案。

定位 session 檔案：

• Codex： 依 references/clients.md「Session 恢復」中的嚴格候選流程，只接受 user prompt 以 [<agent_id>] 開頭的本地與 UTC 今天／前一天 JSONL，再人工確認唯一檔案；不得使用只搜尋 agent ID 子字串的 grep ... | head -1。

• Claude Code： session 索引在 ~/.claude/sessions/<pid>.json，內含 name（即 agent_id）與 sessionId。

  AGENT_ID="<agent_id>"
  jq -r --arg name "$AGENT_ID" 'select(.name == $name) | .sessionId' ~/.claude/sessions/*.json
  

  人工確認唯一的 sessionId 後，讀取對應的 JSONL：

  ~/.claude/projects/<project-slug>/<sessionId>.jsonl
  

  <project-slug> 為工作目錄路徑以 - 取代 /（如 /home/swy/myapp → -home-swy-myapp）。

在 JSONL 中搜尋工具呼叫錯誤：

grep -i "error\|failed\|permission\|denied\|invalid" <session-jsonl>

找到實際錯誤訊息後，判斷真正原因（參數格式錯誤、schema 不符、真的權限不足等）。

外部步驟 3 — 通知 sub-agent： 依 client 類型通知：

• tui → 先用檔案編輯 API 將訊息寫入安全的 MESSAGE_PATH，再執行 zmx send <session> "$(cat -- "$MESSAGE_PATH")$(printf '\r')"
• exec → 依 references/clients.md 的 Session 恢復流程 resume，在 prompt 中帶入問題描述

通知內容須包含：實際錯誤訊息、錯誤原因、修正方向。

重試上限

同一 sub-agent 因同類工具錯誤被通知 3 次後仍未解決，暫停該 phase，向使用者報告：

• sub-agent 的角色與 agent_id
• 實際錯誤訊息
• 已嘗試的修正指引
• 建議的人工處理方式

注意事項

• Client 指令格式、監控、錯誤處理、Session 恢復參見 references/clients.md。
• 佇列檔案規則參見 references/yaml-schema.md。