zeroclaw-labs/zeroclaw · error
JSONL archive changed during filesystem handoff
Error message
JSONL archive changed during filesystem handoff
What it means
Consistency guard in archive_staged_jsonl during the JSONL-to-SQLite migration handoff: after hard-linking the staged file to its .migrated archive name, the archive's source fingerprint no longer matches the expected (hash, length) pair captured when the file was staged. Something modified the file across the filesystem handoff, so the no-clobber archive is treated as corrupted and the migration aborts rather than trusting it.
Solutions
- Do not modify the JSONL session file while migration is running; stop writers and retry the handoff.
Defensive patterns
Strategy: validation
When it happens
Trigger: Thrown at crates/zeroclaw-infra/src/session_sqlite.rs:270 when the library encounters an invalid state.
Common situations: See trigger scenarios.
AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23).
Data as JSON: /api/errors/883eccacf4db0e12.
Report an issue: GitHub.
Appendix: source
Thrown at crates/zeroclaw-infra/src/session_sqlite.rs:270
fn archive_staged_jsonl(
staged_path: &Path,
migrated_path: &Path,
expected: &(String, i64),
) -> Result<()> {
std::fs::hard_link(staged_path, migrated_path).with_context(|| {
format!(
"Failed to create no-clobber JSONL archive {}",
migrated_path.display()
)
})?;
Self::sync_parent_directory(migrated_path)?;
let archive_name = migrated_path
.file_name()
.and_then(|name| name.to_str())
.unwrap_or("archive");
if &Self::source_fingerprint(migrated_path, archive_name)? != expected {
let _ = std::fs::remove_file(migrated_path);
bail!("JSONL archive changed during filesystem handoff");
}
std::fs::remove_file(staged_path).with_context(|| {
format!(
"Failed to remove staged JSONL source {}",
staged_path.display()
)
})?;
Self::sync_parent_directory(staged_path)?;
Ok(())
}
fn sync_parent_directory(path: &Path) -> Result<()> {
#[cfg(unix)]
{
let parent = path
.parent()
.filter(|parent| !parent.as_os_str().is_empty())
.unwrap_or_else(|| Path::new("."));View on GitHub (pinned to 88bb9c8533)