codex-dispatch

Files (1)

• SKILL.md

SKILL.md (first lines)

# Codex 派工機制

本 Skill 負責派工的執行機制。是否派工由 `instructions.md` §1.5 的路由規則判定，本 Skill 只處理指令、落點、等待、取證、續 session 與回收。

## 使用時機與入口選擇

主 Agent 依 F1 判準判定要派工後載入本 Skill。執行端角色依角色規則檔引用本 Skill 的共用作業節時，只讀取被引用的節。

| 情境 | 入口 | 必要輸入 | 提供方式 |
| --- | --- | --- | --- |
| 建立資源派遣單 | `scripts\New-DispatchOrder.ps1` | `Title`、`Role`、`TargetPath`、`TaskBody`、`Acceptance`、`Boundary`、`ReportPath`、`DispatchSlug`、`LineSlug`；`OutputPath` 選填 | 命令列參數；省略 `OutputPath` 時派遣單寫入來源工作樹 `handoff\dispatch-order-<dispatchSlug>.md`，即 `Dispatch` 讀取的位置，八個欄位定義見「派遣單契約」 |
| 首次啟動一筆派遣（正式入口） | `scripts\Invoke-CodexDispatch.ps1 -Operation Dispatch` | `source_root`、`dispatch_root`、`line_slug`、`dispatch_slug`、`write_mode`、`dispatch_kind`、至少一個 `target_path`、`prompt_path`、`task_type`、`session_mode`、`unit_kind`、`failure_receipt_path` | 只接受 `operation=Dispatch` 的 request 檔（UTF-8 無 BOM），以 `-RequestPath` 傳入；欄位表與範例見「Dispatch 正式入口」 |
| 同一 worktree 續行；換 worktree 續行；恢復或階段間檢查 | 同一 worktree 使用 `Start -ResumeThreadId`；換 worktree 使用 `Dispatch` 的 `session_mode=Continuation`；階段間檢查可分步呼叫 `Preflight`、`Prepare`、`Start` | 同一 worktree 的 Start 使用前輪 Dispatch result 記錄的 Preflight、Prepare 結果路徑及原 ScopePlan；換 worktree 使用新 `dispatchSlug`、重建 worktree 並承接父 ScopePlan | Start 參數來源見「續 session 與跨介面接手」；Dispatch 使用 request 檔；`prepare_artifacts` 只能經 request 檔傳入 |
| 執行結束或中斷後 | `Inspect`，接著 `Collect` | 事件流、stderr、last-message、Preflight 結果與報告路徑；中斷時另回收逐單位保全檔 | 命令列參數 |
| 回收完成且不再續行 | `Cleanup` | 保存清單、RunRecord、報告與 evidence 路徑 | 命令列參數或 request 檔 |
| 查詢派遣進度（唯讀） | `scripts\Get-DispatchProgress.ps1` | `WorkRoot`、`LineSlug`、`DispatchSlug` 選填；`-All` 顯示全部紀錄 | 直接執行，預設顯示未結束與最近 24 小時內結束的項目 |

`~/.ai-agents/templates/dispatch/` 提供派遣單、Request、failure receipt、result envelope、Developer 結案報告、`exceptions.md` 與 Reviewer 報告的範本。派遣單以 `New-DispatchOrder.ps1` 產生為正常路徑，範本供手動核對結構；報告範本的必要區段以 Collect 與 Cleanup 的驗證為準。

正常路徑使用的正式 operation 為 `Dispatch`、`Inspect`、`Collect` 與 `Cleanup`；`DiagnoseModelEnvironment` 只供使用者或維運者診斷。`Preflight`、`Prepare` 與 `Start` 是 `Dispatch` 內部的階段轉移，命令列保留這三個 operation 供續行、恢復與測試使用，新的一筆派遣一律從 `Dispatch` 進入。

request 欄位先依 parser 白名單驗證，再依 operation 套用欄位作用域。識別欄位為 `schema`、`operation`、`line_slug`、`dispatch_slug`。其他一般白名單欄位為 `profile`、`advisor_request_source`、`target_path`、`add_directory`、`search`、`codex_parent_option`、`literal_values`、`prepare_artifacts`、`result_path`、`preflight_result_path`。共用根目錄欄位（`commonRootFields`）為 `source_root`、`dispatch_root`、`caller_session_id`。

`Dispatch` 專用欄位（`dispatchOnlyFields`）完整清單為 `write_mode`、`dispatch_kind`、`prompt_path`、`task_type`、`session_mode`、`unit_kind`、`requested_unit`、`continue_from_scope_plan`、`background`、`required_identifier`、`failure_receipt_path`、`prepare_result_path`、`evidence_pack_path`、`advisor_consult_report_path`、`selected_requirement`。`Cleanup` 專用欄位（`cleanupOnlyFields`）為 `run_record_path`、`reviewer_report_path`、`report_path`、`evidence_path`。`Dispatch` 不接受 Cleanup 專用欄位，`Cleanup` 不接受 Dispatch 專用欄位；其他 operation 不接受共用根目錄、`result_path`、`preflight_result_path` 或兩組 operation 專用欄位。`source_root`、`result_path` 與 `preflight_result_path` 只在 `Dispatch` 與 `Cleanup` 合法。同一欄位在 request 檔與命令列不一致時以 `DispatchRequestMismatch` 停止。

Request 的 `operation` 以不區分大小寫的方式驗證，解析後使用正式 operation 名稱；命令列與 Request 的 operation 比對也不區分大小寫。結果的 `dispatch_request` 會保存 Request 檔路徑、SHA-256、位元組長度、正規化 operation、line／dispatch identity、欄位 presence，以及共用、Dispatch 與 Cleanup 欄位的正規化值。陣列欄位另保存筆數、SHA-256 與值；`literal_values` 另有獨立 SHA-256。

Start 將 Request 檔路徑、SHA-256 與 operation 綁定至 RunRecord。advisor Inspect 會重新讀取 evidence pack，核對 Start 記錄的 SHA-256 與檔案長度，並在結果中回報 evidence pack 路徑與 hash；來源變更或內容不符時停止驗收。

### Caller Session 身分與併行准入

`Dispatch`、`Preflight`、`Prepare`、`Start` 與 `Cleanup` 依序解析 caller Session ID：Request 的 `caller_session_id`、CLI `-CallerSessionId`、環境變數 `CLAUDE_CODE_SESSION_ID`、環境變數 `CODEX_THREAD_ID`。Request 的 `caller_session_id` 欄位只在 `Dispatch` 與 `Cleanup` 的 Request 有效，其他 operation 的 Request 帶此欄位時以 `DispatchRequestFieldNotAllowed` 拒絕，改由 CLI 或環境變數提供。Request 與 CLI 同時提供時採用 Request 值。四個來源皆無有效值時，以 `CallerSessionIdMissing` 在 Prepare／Start 副作用前停止；空值或超過長度上限時以 `CallerSessionIdInvalid` 停止。既有 Claude 呼叫端可繼續由 `CLAUDE_CODE_SESSION_ID` 提供身分，不需修改 Request。

RunRecord、PID 記錄、結果與 admission ledger 保存 caller Session fingerprint 及來源名稱，不複製原始 ID。Ledger 位於 source root 的 history 目錄，所有讀取、比較與原子替換都在同一個短暫獨占鎖內執行。Start 在鎖內重做 PID identity check，啟動 Codex、寫入 PID 記錄並登記 owner，避免兩個入口同時通過檢查後重複取得名額。

同一 caller Session 可同時持有一個 write admission 與最多兩個 readonly admission。Worktree write 期間可執行同線 readonly 派遣。路徑衝突比對要求至少一方為 direct-write 目標；與其他派遣的 direct-write 目標或 `--add-dir` 權限路徑相同或有父子路徑關係時，新的 admission 以 `DispatchAdmissionPathConflict` 拒絕。各派遣所屬線的 `<sourceRoot>\.local\ai-sessions\history\<lineSlug>` 目錄及其子路徑，只有在該 admission 的路徑為 `--add-dir` 時才排除於衝突比對外；direct-write 即使位於該處，仍與其他派遣的 direct-write 目標或 `--add-dir` 路徑進行父子重疊比對。`--add-dir` 對 `--add-dir` 可並行。第二個 write 以 `DispatchAdmissionWriteLimit` 拒絕，第三個 readonly 以 `DispatchAdmissionReadonlyLimit` 拒絕。`Inspect`（含 `-WaitForCompletion`）屬回收操作，不申請新的 admission，因此不受上述名額與路徑衝突限制。`Prepare`、`Start`、`Collect -ApplyCollectedChanges` 與 `Cleanup` 照常檢查。Ledger owner 身分無法確認時，新的 admission 與 Cleanup 皆以 `DispatchAdmissionOwnerUnknown` 拒絕。

`Cleanup` 以 ledger 的 caller fingerprint、line 與 dispatch 驗證 owner；提供 RunRecord 時另比對 RunRecord 的 caller fingerprint。Owner 不相符時預設以 `DispatchAdmissionOwnerMismatch` 拒絕並保留 worktree；歷史已結束派遣可依「已結束歷史派遣的 Cleanup 接手」明示例外。Workflow worktree 的 `Collect` 通過既有驗收後，可額外指定 `-ApplyCollectedChanges` 套用變更；套用前會在 source root 鎖內比對每個目標路徑的 baseline fingerprint，漂移時以 `DispatchSourceDrift` 停止並保留 worktree。為避免 dispatch worktree 依 `.gitattributes` 檢出的行尾與來源工作樹不同而誤報漂移，`Preflight` 在 `Apply-SourceCarryIn` 之後、建立 baseline 之前，對 dispatch worktree 內 Git 追蹤清單及尚未加入 index 的未追蹤清單所列項目，若來源工作樹同一路徑存在一般檔案且位元組長度不同，以來源的原始位元組覆寫目的檔。Windows 流程以不跟隨 reparse point 的方式開啟來源與目的檔案，確認 handle 類型與最終路徑分別符合正規化根目錄加相對路徑；目的檔為唯讀時，通過驗證後以 `FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_FLAG_OPEN_REPARSE_POINT` 開啟目的屬性 handle，透過 `SetFileInformationByHandle(FileBasicInfo)` 只改動屬性欄位清除 `ReadOnly`，並以 `ReOpenFile` 取得寫入 handle。目的檔 handle 的 `NumberOfLinks` 大於 1 時一律以 hard link 別名拒絕；串流寫入失敗時，16 MiB 以內的目的檔會在同一 handle 回復原始位元組與長度，較大目的檔不先截斷，失敗可能留下部分覆寫內容；若失敗發生於最後的長度設定或 flush 後，檔案長度可能已是來源長度。流程在 `finally` 透過同一個已驗證的屬性 handle 還原原始屬性，目錄被 junction 置換時拒絕操作。非 Windows 遇到長度不同且需要覆寫的檔案時，會在寫入前以明確指出僅支援 Windows 的錯誤拒絕；長度相同時略過同步並保留原始 SHA-256 比對，位元組不同會判定漂移。機密檔名樣式及來源不存在的路徑會略過，處理清單包含 `git ls-files` 追蹤檔案與尚未加入 dispatch index 的未追蹤檔案。同步後 baseline 記錄與來源一致的起點，`Preflight` 後來源任何位元組變化（包含只有行尾變化）都由原始 SHA-256 比對判定為漂移。Direct-write 已直接修改 source root，使用 `-ApplyCollectedChanges` 時以 `DispatchCollectApplyDirectWriteNotApplicable` 拒絕。

## 已結束歷史派遣的 Cleanup 接手

嚴格 owner 檢查回報 `DispatchAdmissionOwnerMismatch` 或 `DispatchAdmissionOwnerUnverifiable` 時，主 Agent 可明示接手。

```powershell
pwsh -NoProfile -File .\scripts\Invoke-CodexDispatch.ps1 -Operation Cleanup -RequestPath <既有CleanupRequest> -TakeoverOwner
```

保留真實 `CallerSessionId` 與既有 Request 欄位。`TakeoverOwner` 僅適用於 Cleanup，其他 operation 回報 `CleanupTakeoverOperationInvalid`。相同 owner 仍走原流程，`owner_takeover.used=false`。

接手在來源 admission lock 內驗證全部 RunRecord 的 identity、hash 與續行鏈。已啟動 run 須有最後 `turn.completed` 或 `turn.failed`，以及同 run 的已知退出 sidecar；舊 run 僅接受通過 identity/hash 驗證且退出來源可信的 Inspect。未啟動 run 須通過 `unstarted-sandbox` 與既有未啟動證明。prepared、unknown、缺少可信終態或只有程序不存在時，保留 worktree。

PID 三鍵、程序樹與 ledger 稽核須確認程序已結束或原 PID 已重用。程序查詢被拒、仍有 root/child 或身分不明時維持拒絕。報告與全部 evidence 依位元組保存、長度及 SHA-256 回讀後，在 `<sourceRoot>\.local\ai-sessions\history\<lineSlug>\cleanup-takeover-<dispatchSlug>-<attemptGuid>.json` 原子保存接手者、原 owner、UTC 時間、終態及程序證據、保存清單與 hash。

稽核依序為 `validated`、`preserved`、`completed`，失敗盡力記 `failed`。移除前重驗 run 集合、證據 hash、PID 與 inventory，漂移或保存／稽核失敗均保留 worktree。移除後稽核更新失敗回報 `CleanupTakeoverAuditFinalizeFailed` 與 `worktree_removed=true`，以 preserved 稽核及 cleanup-result 恢復。`cleanup-result.owner_takeover` 保存是否使用接手、稽核路徑及 SHA-256；歷史 owner fingerprint 維持原值。每次重試重新驗證，舊稽核只作證據。

## 最短正常路徑

一筆派遣依下列順序推進。每一步的產物是下一步的輸入，上一步未成功時不進入下一步。

| 步驟 | 動作 | 產物 | 下游接收者 |
| --- | --- | --- | --- |
| 1 | 產生派遣單（資源派遣），或確認 `design.md` 已通過 Design 驗收（Workflow） | 派遣單或 `design.md` | Prompt 與 Codex 執行端 |
| 2 | `Preflight` 驗證 LineContext、PID 與寫入面，決定 `executionRoot` | Preflight 結果 JSON | Prepare、Start、Collect |
| 3 | `Prepare` 將交接檔複製到 `executionRoot` 並比對 SHA-256 | `-PrepareResultPath` 寫出的 `ai-sessions.prepare.v1` 文件；`-ResultPath` 只寫 CLI envelope | Start 只接受 `ai-sessions.prepare.v1` 文件 |
| 4 | `Start` 建立 ScopePlan，背景啟動 Codex | Start 結果、事件流、stderr、last-message、thread id、PID 記錄 | 主 Agent 的等待與 Inspect |
| 5 | 等待完成通知，依「完成判定與三出口」判定出口 | 出口判定 | Inspect |
| 6 | `Inspect` 解析事件流與 last-message | `success`、`outputValid`、usage、model evidence | RecoveryPrecheck 與回收三態 |
| 7 | `RecoveryPrecheck` 通過後，`Collect` 核對成果與報告，主 Agent 判定回收三態 | Collect 結果與三態判定 | 續行、升級或同步 |
| 8 | 同步報告與核准交接產物，再執行 `Cleanup` | 保存驗證結果 | 結案報告 |

`Dispatch` 串接步驟 2 至 6。預設同步等待 Codex 結束後執行 Inspect，回傳 `completed` 或 `failed`；Request 設 `background: true` 時先回傳 `status=started`，只代表 Codex 已啟動，再以 `Inspect -WaitForCompletion` 等待。步驟 7 與 8 的回收判定由主 Agent 執行，派遣不再需要在 Session 內另寫 runner。

### Dispatch 正式入口

- 單位自動產生：Workflow 依 `design.md`「實作任務清單」章（`## ` 開頭且含「實作任務清單」的章節）內的 `### Phase N` 或 `#### Phase N` 標題順序產生 `requested_unit`，找不到該章時才解析全文件；章內同編號連續小節合併為一個單位，非連續重複拒絕；資源派遣依 `<sourceRoot>\.local\ai-sessions\handoff\dispatch-order-<dispatchSlug>.md` 第 3 欄產生，Request 的 `target_path` 必須與該欄完全相符。明確提供的 `requested_unit` 必須是來源清單的有序子集合。來源與 Request 不一致時，入口在 Preflight、Prepare、worktree 建立與 Codex 啟動前拒絕，回傳 `operation: DispatchRequest`、`process_started: false` 與 `detail.differences`。Request 欄位驗證錯誤的 detail 只列欄位名稱、預期格式與輸入長度，不回顯原始輸入值。
- 派遣單目標路徑：第 3 欄若填入含 `dispatchSlug` 的 worktree 絕對路徑，改用新的 `dispatchSlug` 時需同步更新目標路徑並重產派遣單。目標位於 `sourceRoot` 且所選 sandbox 能直接讀取時，建議填穩定的 `sourceRoot` 絕對路徑。`targetsOutsideRepository` 只涵蓋 `sourceRoot` 內、位於 repository 外或被 gitignore 排除的路徑；`target_path` 一律必須位於 `sourceRoot` 內，超出時 Preflight 以 `DispatchOutputBoundary` 拒絕。此建議不改變 Request `target_path` 必須與第 3 欄完全相符的條件。
- 外部資料：唯讀取證需要讀取 `sourceRoot` 以外的路徑時，以 `sourceRoot` 內的題目檔為第 3 欄目標並使用 `readonly`，外部路徑以絕對路徑逐一列在第 4 欄。read-only sandbox 可讀取這些路徑，但它們不進入 `target_path` 與 ScopePlan，派遣報告須逐條列出實際讀取的外部路徑。不以 `write` 或 direct-write 承接唯讀取證。
- Prepare 自動帶入：同線 `line.json`、`requirement-summary.md`；`dispatch_kind=resource` 且 `write_mode=readonly` 的派遣在同線沒有 `requirement-summary.md` 時略過摘要，其他派遣缺摘要時拒絕。Workflow 另帶入 `design.md`，資源派遣在第 4 欄提及 `design.md` 時帶入，並把派遣單複製到 dispatch worktree 的同線 handoff。`prepare_artifacts` 只用於追加其他檔案。
- 輸出路徑安全：`result_path` 與 `preflight_result_path` 必須位於 SourceRoot 或 ExecutionRoot，root、既有各層目錄與寫入目標任一層為 reparse point 時拒絕；未指定時輸出到 ExecutionRoot 同線 history。需要 worktree 清除後仍可從來源工作樹取用時，明確指定 `<sourceRoot>\.local\ai-sessions\history\<lineSlug>\` 下的路徑。`prepare_result_path` 的目的地限於 ExecutionRoot 的同線 handoff、report 或 history line root，且不得與 target path 重疊；未指定時輸出到 ExecutionRoot 同線 history。目錄建立後、實際寫入前會再次核對路徑。
- direct-write：Preflight 判定不建 worktree（`worktreeCreated=false`）時，Prepare 使用 Preflight 的 `executionRoot`（即 `sourceRoot`）作為 DispatchRoot，Request 的 `dispatch_root` 只用於路徑驗證；只寫同線 handoff 的資源派遣可直接使用正式入口。
- 可省略欄位：`profile`（預設 `default`）、`requested_unit`、`prepare_artifacts`、`background`（預設 `false`）、`required_identifier`（Workflow 預設 `design.md`，資源派遣預設第一個 target 的檔名；advisor-consult 沒有 target 時預設 evidence pack 檔名，Start 注入與 Inspect 比對使用同一個值）、`selected_requirement`（本輪選定需求，傳給 Workflow Collect）與各階段結果路徑。Request 帶 `quota_before_path` 或 `quota_after_path` 時以欄位不允許拒絕。
- 輸出欄位：`status`（`started`、`completed`、`failed`）、`completed_stages`、`failed_stage`、`error_code`、`error`、`process_started`、`process_exit_code`、`termination_reason`、`inspect_status`、`inspect_success`、`requested_units`、`result_path`、`result_sha256`、`inspect_result_path`。`Collect` 的參數取自這些欄位。所有 operation 的 JSON stdout 固定使用 UTF-8（無 BOM），不依 PowerShell host 的預設主控台編碼。

背景派遣的等待命令如下。`-WaitForCompletion` 等待 sidecar 確認 Codex 行程結束，再以事件流 terminal event 決定結果，沒有固定逾時。`-WaitForCompletion` 只接受 `Dispatch` 產生的 result（需含 `result_sha256`）；逐一呼叫 Preflight、Prepare、Start 的分步入口不能用它等待，改由執行環境的背景完成通知接手後呼叫 `Inspect`。

```powershell
.\scripts\Invoke-CodexDispatch.ps1 -Operation Inspect -DispatchResultPath <result_path> `
  -SourceRoot <source_root> -ExecutionRoot <execution_root> -LineSlug <line_slug> -DispatchSlug <dispatch_slug> `
  -TargetPath <target_path> -RequiredIdentifier <required_identifier> -WriteMode <write_mode> -WaitForCompletion
```

## 失敗與恢復導引

| 失敗形狀 | 恢復方式 | 詳細節 |
| --- | --- | --- |
| 事件流以 usage-limit 結束（服務端拒絕） | 不重試同一派遣；等待重設，或依「主 Agent 的帳號切換決策」以手動查詢的額度選另一帳號冷啟動 | 額度與範圍契約 |
| admission 或 Start 準備階段失敗、Codex 程序未啟動 | 修正輸入後可用同一個 `dispatchSlug` 重新冷啟動。腳本會清除該次失敗嘗試建立的 ScopePlan hash 紀錄，`failure receipt` 與 `launch-failed` RunRecord 保留供稽核；已啟動成功者的 hash、ledger 與 owner 不受影響。若 `Cleanup` 缺少 Preflight，未啟動證明還要求 dispatch worktree 的 `.local\ai-sessions\history` 下不存在 `codex-exec-*.jsonl` 與 `codex-thread-<dispatchSlug>.txt`；任一檔案存在時以 `CleanupPreflightResultRequired` 拒絕並保留 worktree。該次嘗試已建立 dispatch worktree 時，Preflight 會因 dispatchRoot 已被占用而拒絕，此時改用新的 `dispatchSlug`；Prepare 結果檔已存在而發生 `PrepareResultCollision` 時，改用新的結果路徑或新的 `dispatchSlug` | 續 session 與跨介面接手 |
| 續行被拒 | 以 `git -C <舊 dispatchRoot> diff HEAD` 與未追蹤檔案清單轉移成果，以新的 `dispatchSlug` 冷啟動 | Codex 進程 PID 與並行檢查 |
| 事件流在最後訊息前中斷，沒有 `turn.completed` 或 `turn.failed` | 先執行 `Inspect` 與 `Collect` 取回中斷保全檔；只交付已確認單位與其證據，其餘 selected units 保持未完成 | InterruptionSafeguard |
| 事件流以 `turn.failed` 結束或 exit code 非零 | 依 C 出口取失敗原因。若事件流以 `turn.failed` 結束且結案報告不存在，`Inspect` 與 `Collect` 回報 `recoverable_artifacts_present` 及 `recoverable_artifact_files`，供主 Agent 檢視相對 `baseSha` 的 worktree 變更並決定是否以新 `dispatchSlug` 冷啟動；欄位不改變失敗判定 | 完成判定與三出口 |
| 派遣 target_path 符合機密檔名樣式 | `Preflight` 以 `PreflightSecretTargetRejected` 列出路徑並在建立 worktree 前停止 | Git 前置探針與 worktree 生命週期 |
| Prepare 失敗且 `PrepareFailed` 文件再次寫入失敗 | 由 operation result 的 `prepareResultWriteFailure.code=PrepareResultWriteFailed` 與 `prepareResultWriteFailure.path` 取得錯誤碼與目標路徑；`prepareResultSha256=null`，不將該路徑視為已成功保存的 Prepare 文件，修正寫入條件後重新 Prepare | 腳本介面與執行前提 |
| 結案訊息缺少識別字 | 標記 `PromptNotDelivered`，修正啟動方式後重新派遣 | RecoveryPrecheck |

### 四種阻塞形狀的產物與交接

派工受阻時，先判定屬於下列哪一種形狀，再依對應的產物語意與交接方式處理。腳本已承擔的部分不改由人工步驟補做。

| 阻塞形狀 | 產物語意 | 操作交接 | 詳細節 |
| --- | --- | --- | --- |
| 入口不對稱 | `Dispatch` 是新派遣的唯一正式入口；Request 檔與命令列的同名欄位語意與驗證相同，兩邊不一致時以 `DispatchRequestMismatch` 拒絕 | 新的一筆派遣一律從 `Dispatch` 進入；`Preflight`、`Prepare`、`Start` 的分步入口只用於續行、恢復與測試 | 使用時機與入口選擇、Dispatch 正式入口 |
| 失敗重試污染 | 程序未啟動的失敗嘗試留下 `failure receipt` 與 `launch-failed` RunRecord 供稽核，該次建立的 ScopePlan hash 會被清除 | 程序未啟動且未留下 dispatch worktree 時以同一個 `dispatchSlug` 重試，已留下 worktree 時改用新的 `dispatchSlug`；程序已啟動的派遣改走續行，或以新 `dispatchSlug` 冷啟動並轉移成果 | 失敗與恢復導引、續 session 與跨介面接手 |
| 外部狀態恢復 | 服務端以 usage-limit 拒絕時不重試；中斷時以中斷保全檔記錄已確認單位與證據位置 | 主 Agent 需要額度數值時以 `Get-CodexQuota.ps1` 手動查詢，advisor 啟動由使用者授權；中斷後先 `Inspect`、`Collect` 取回中斷保全檔，只交付已確認單位 | 額度與範圍契約、InterruptionSafeguard、advisor 授權請求 |
| 同名參數語意 | `-ResultPath` 只寫 CLI envelope；`-PrepareResultPath` 寫 `ai-sessions.prepare.v1` 文件；每個產物只有一個寫入者 | `Start` 只接受 `ai-sessions.prepare.v1` 文件；`Collect` 的參數取自 `Dispatch` 輸出欄位，不自行拼湊路徑 | 最短正常路徑、Dispatch 正式入口 |

`ScopePlan` hash 紀錄寫入 `<sourceRoot>\.local\ai-sessions\history\<lineSlug>\scope-plan-hash-<dispatchSlug>.json`，不同線可使用相同 `dispatchSlug`。讀取時若同線路徑不存在，才檢查舊版 history 根目錄的 `scope-plan-hash-<dispatchSlug>.json`；只有舊紀錄的 `line_slug`，或其 `root_run_id` 對應 RunRecord 的所屬線，與目前 `lineSlug` 相同時才沿用。其他線的舊紀錄不阻擋目前派遣，也不會被改寫或刪除。同一線內仍須使用不同 `dispatchSlug` 識別不同派遣。

## 額度與範圍契約

From CloudyWing/ai-dotfiles, MIT.

More from CloudyWing/ai-dotfiles