{"record":{"id":"cdc44746b0b5b612","repo":"Hmbown/CodeWhale","slug":"attempt-finalization-requires-a-terminal-worker-event","errorCode":null,"errorMessage":"attempt finalization requires a terminal worker event","messagePattern":"attempt finalization requires a terminal worker event","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/tui/src/fleet/ledger.rs","lineNumber":965,"sourceCode":"    #[allow(clippy::too_many_arguments)]\n    pub fn finalize_task_attempt_if_leased(\n        &self,\n        run_id: &FleetRunId,\n        worker_id: &str,\n        task_id: &str,\n        expected_attempts: u32,\n        timestamp: &str,\n        payload: FleetWorkerEventPayload,\n        final_status: Option<FleetTaskLedgerStatus>,\n        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)","sourceCodeStart":947,"sourceCodeEnd":983,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/fleet/ledger.rs#L947-L983","documentation":"FleetLedger::finalize_task_attempt_if_ledger finalizes one exact process attempt and its receipt in a single JSONL record. The first guard (crates/tui/src/fleet/ledger.rs:965) requires the payload passed to be a terminal worker event (Completed/Failed/Cancelled); finalizing an attempt on a non-terminal payload is rejected before any lock is taken. This keeps receipt evidence pinned to an actual terminal transition.","triggerScenarios":"Calling finalize_task_attempt_if_leased with a non-terminal FleetWorkerEventPayload (Progress, UsageReport, Heartbeat) — typically from a verifier or supervisor path that computes the receipt before selecting the terminal event variant.","commonSituations":"A worker wrapper that emits generic events into the finalize call; a restart-race handler that re-finalizes with a reused (non-terminal) payload; code shared between progress-append and finalize paths that forgot to branch.","solutions":["Pass only Completed, Failed, or Cancelled payloads to finalize_task_attempt_if_leased.","Append progress events via append_event_if_lease_unchanged and reserve finalize_task_attempt_if_leased for the terminal transition.","Select the payload based on the outcome status before constructing the finalize call."],"exampleFix":"// before\nlet payload = FleetWorkerEventPayload::Progress { .. };\nledger.finalize_task_attempt_if_leased(&run_id, &w, &t, attempts, &ts, payload, Some(status), receipt)?;\n// after\nlet payload = match status {\n    FleetTaskLedgerStatus::Completed => FleetWorkerEventPayload::Completed { .. },\n    FleetTaskLedgerStatus::Failed => FleetWorkerEventPayload::Failed { .. },\n    _ => FleetWorkerEventPayload::Cancelled { .. },\n};\nledger.finalize_task_attempt_if_leased(&run_id, &w, &t, attempts, &ts, payload, Some(status), receipt)?;","handlingStrategy":"validation","validationCode":"assert!(is_terminal_payload(&payload), \"finalize requires a terminal worker event\");","typeGuard":null,"tryCatchPattern":"if let Err(e) = ledger.finalize_task_attempt_if_leased(...) {\n    if e.to_string().contains(\"requires a terminal worker event\") { /* fix payload selection, do not retry blindly */ }\n    return Err(e.into());\n}","preventionTips":["Construct finalize payloads from an exhaustive match over outcome status so only terminal variants can be produced.","Do not share a payload variable between progress-append and finalize paths.","Cover the finalize path with a unit test asserting non-terminal payloads are rejected."],"tags":["fleet","ledger","invalid-argument"],"backgroundTag":"invalid-argument-value","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"}