{"record":{"id":"9a6619194e92bba5","repo":"Hmbown/CodeWhale","slug":"invalid-coordination-ledger-error","errorCode":null,"errorMessage":"Invalid coordination ledger: {error}","messagePattern":"Invalid coordination ledger: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/tui/src/tools/subagent/mod.rs","lineNumber":4675,"sourceCode":"                legacy\n            } else {\n                return Ok(());\n            }\n        };\n\n        let raw = read_subagent_state_file(&self.state_root, &path)?;\n        let state = serde_json::from_str::<PersistedSubAgentState>(&raw)?;\n        if state.schema_version != SUBAGENT_STATE_SCHEMA_VERSION {\n            return Err(anyhow!(\n                \"Unsupported sub-agent state schema {}\",\n                state.schema_version\n            ));\n        }\n\n        let mut coordination = state.coordination;\n        coordination\n            .validate_replay()\n            .map_err(|error| anyhow!(\"Invalid coordination ledger: {error}\"))?;\n        self.agents.clear();\n        self.worker_records.clear();\n        self.persist_sequence.store(\n            state.snapshot_sequence,\n            std::sync::atomic::Ordering::Relaxed,\n        );\n        self.coordination = coordination;\n        self.resume_targets = state.resume_targets;\n        for persisted in state.agents {\n            let nickname = persisted\n                .nickname\n                .filter(|name| generated_whale_name_base(&persisted.id, name).is_none());\n            let mut status = persisted.status;\n            if matches!(status, SubAgentStatus::Running) {\n                status = SubAgentStatus::Interrupted(SUBAGENT_RESTART_REASON.to_string());\n            }\n\n            let started_at = instant_from_duration(Duration::from_millis(persisted.duration_ms));","sourceCodeStart":4657,"sourceCodeEnd":4693,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/tools/subagent/mod.rs#L4657-L4693","documentation":"After deserializing a persisted sub-agent state snapshot, the coordination ledger inside it is validated with validate_replay() to ensure the recorded events form a consistent, replayable history. If validation fails, the snapshot's coordination data is corrupt or internally inconsistent, so loading is aborted with the validator's error attached.","triggerScenarios":"Restoring sub-agent state from a state file whose coordination entries are missing events, out of order, reference unknown agents, or were truncated by a crash mid-write.","commonSituations":"Power loss or kill -9 during a state persist; manual edits to the state JSON; copying an inconsistent state file between machines; disk corruption.","solutions":["Restore the state file from backup (or let Codewhale rebuild it by removing the corrupt state under state_root).","Read the embedded {error} detail to see which ledger invariant failed; if a single entry is corrupt, that snapshot cannot be partially loaded.","Re-run the workflow that produced the snapshot; live agents will be re-spawned.","Check disk health if corruption recurs across snapshots."],"exampleFix":"// before: loading a corrupt snapshot\nlet state = load_subagent_state(path)?;\n// after: fall back to a fresh session when the ledger is unrecoverable\nlet state = match load_subagent_state(path) {\n    Ok(s) => s,\n    Err(e) if e.to_string().contains(\"Invalid coordination ledger\") => fresh_state(),\n    Err(e) => return Err(e),\n};","handlingStrategy":"fallback","validationCode":"fn ledger_valid(raw: &str) -> bool {\n    serde_json::from_str::<PersistedSubAgentState>(raw).ok()\n        .map(|s| s.coordination.validate_replay().is_ok())\n        .unwrap_or(false)\n}","typeGuard":null,"tryCatchPattern":"let state = match load_subagent_state(path) {\n    Ok(s) => s,\n    Err(e) if e.to_string().contains(\"Invalid coordination ledger\") => {\n        warn!(\"corrupt ledger, rebuilding\");\n        backup_and_rebuild(path)\n    }\n    Err(e) => return Err(e),\n};","preventionTips":["Avoid killing the process during state persists (use graceful shutdown).","Never hand-edit persisted state JSON.","Take periodic backups of the state directory; check disk health if corruption repeats."],"tags":["state","validation","corruption"],"backgroundTag":"schema-validation-failed","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}