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，才能進入下一階段。