{"record":{"id":"88623235c7d92463","repo":"Hmbown/CodeWhale","slug":"attempt-finalization-status-must-be-terminal","errorCode":null,"errorMessage":"attempt finalization status must be terminal","messagePattern":"attempt finalization status must be terminal","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/tui/src/fleet/ledger.rs","lineNumber":975,"sourceCode":"        mut receipt: FleetReceipt,\n    ) -> Result<Option<FleetWorkerEvent>> {\n        if !matches!(\n            &payload,\n            FleetWorkerEventPayload::Completed { .. }\n                | FleetWorkerEventPayload::Failed { .. }\n                | FleetWorkerEventPayload::Cancelled { .. }\n        ) {\n            bail!(\"attempt finalization requires a terminal worker event\");\n        }\n        if final_status.is_some_and(|status| {\n            !matches!(\n                status,\n                FleetTaskLedgerStatus::Completed\n                    | FleetTaskLedgerStatus::Failed\n                    | FleetTaskLedgerStatus::Cancelled\n            )\n        }) {\n            bail!(\"attempt finalization status must be terminal\");\n        }\n        if receipt.run_id != *run_id || receipt.task_id != task_id || receipt.worker_id != worker_id\n        {\n            bail!(\"attempt receipt identity does not match its terminal event\");\n        }\n        if receipt\n            .attempt\n            .is_some_and(|attempt| attempt != expected_attempts)\n        {\n            bail!(\"attempt receipt generation does not match its lease\");\n        }\n        self.with_write_lock(|| {\n            let state = self.rebuild_state_unlocked()?;\n            let key = task_key(&run_id.0, task_id);\n            let Some(task) = state.tasks.get(&key) else {\n                return Ok(None);\n            };\n            if task.status != FleetTaskLedgerStatus::Leased","sourceCodeStart":957,"sourceCodeEnd":993,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/fleet/ledger.rs#L957-L993","documentation":"FleetLedger::finalize_task_attempt_if_leased accepts an optional final_status that is written into the TaskAttemptFinalized record. If final_status is Some but is not a terminal ledger status (Completed/Failed/Cancelled), the guard at crates/tui/src/fleet/ledger.rs:975 rejects the call: finalizing an attempt into a non-terminal status (e.g. Leased, Queued) would corrupt the ledger state machine. Passing None is allowed (keep the event-derived status).","triggerScenarios":"Calling finalize_task_attempt_if_leased with final_status set to a non-terminal value such as FleetTaskLedgerStatus::Leased, Queued, or Running; mapping a worker outcome to the wrong status variant; a stale enum copied from a progress-update path.","commonSituations":"Status-mapping tables written before the terminal-only rule; refactors that renamed or re-ordered FleetTaskLedgerStatus variants; supervisor code that finalizes with the task's current status instead of the terminal outcome.","solutions":["Pass final_status = None to keep the status derived from the terminal event itself.","Set final_status only to FleetTaskLedgerStatus::Completed, Failed, or Cancelled.","Fix the status-mapping function so it produces a terminal variant for finalize calls."],"exampleFix":"// before\nlet final_status = Some(FleetTaskLedgerStatus::Leased);\nledger.finalize_task_attempt_if_leased(&run_id, &w, &t, attempts, &ts, payload, final_status, receipt)?;\n// after\nlet final_status = Some(match outcome {\n    Outcome::Done => FleetTaskLedgerStatus::Completed,\n    Outcome::Err => FleetTaskLedgerStatus::Failed,\n    Outcome::Stopped => FleetTaskLedgerStatus::Cancelled,\n});\nledger.finalize_task_attempt_if_leased(&run_id, &w, &t, attempts, &ts, payload, final_status, receipt)?;","handlingStrategy":"validation","validationCode":"if let Some(s) = final_status {\n    assert!(matches!(s, FleetTaskLedgerStatus::Completed | FleetTaskLedgerStatus::Failed | FleetTaskLedgerStatus::Cancelled));\n}","typeGuard":"fn is_terminal_status(s: FleetTaskLedgerStatus) -> bool { matches!(s, FleetTaskLedgerStatus::Completed | FleetTaskLedgerStatus::Failed | FleetTaskLedgerStatus::Cancelled) }","tryCatchPattern":"if let Err(e) = finalize_result {\n    if e.to_string().contains(\"status must be terminal\") { /* fix the status mapping, non-retryable */ }\n}","preventionTips":["Prefer final_status = None and let the terminal event derive the status.","Centralize outcome->status mapping in one function that only yields terminal variants.","Update status-mapping code whenever FleetTaskLedgerStatus variants change."],"tags":["fleet","ledger","invalid-state"],"backgroundTag":"invalid-state-transition","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-22T06:17:15.046Z"}