The ruleA session artifact is an append-only database file. External mutation can split live memory from durable replay.

Preserve the first failure.

  1. Stop promptingAnother turn can widen the memory and disk difference.
  2. Record evidenceCapture version, session ID, surface, profile, and the first persistence error.
  3. Stop cleanlyEnd the writer before touching the session directory.
  4. Copy offlineKeep the original read-only. Diagnose only disposable copies.

Route by surviving evidence.

ENOENTThe durable path disappeared.

Do not create an empty file. Restore the full prefix or rematerialize the complete live log from seq 0.

seq gapThe middle is not a torn tail.

Preserve the first missing sequence. Appending a new tail cannot repair committed middle loss.

tool sourceOne call has several identities.

Update the assistant call, execution event, and result identity together on a copy.

works until reloadMemory and replay disagree.

Capture visible output, stop the writer, then test the cold artifact without new turns.

Back up after quiescence.

stat /path/to/session.jsonl
sha256sum /path/to/session.jsonl
zstd -dc /path/to/session.jsonl.zstd > /recovery/session.decoded.jsonl

Cold recovery is intentionally narrow.

Recoverable boundaryFinal torn fragment

A never-fully-written physical tail may be discarded before replay.

Recoverable boundaryInterrupted final turn

Deterministic tool, step, and turn closers can balance a valid prefix.

Refused boundaryCommitted middle corruption

Sequence gaps, malformed messages, and inconsistent tool identities must not be silently accepted.

Inspect a copy, not the source.

jq -c . /recovery/session.jsonl > /dev/null
jq -r '[.seq // "header", .type] | @tsv' /recovery/session.jsonl

Check contiguous sequence numbers, non-empty message IDs, valid sources, and one consistent identity across each assistant tool call, execution, and result.

Primary evidence.

Keep the full recovery matrix.

The canonical runbook includes backup boundaries, validation invariants, reporting evidence, and source links.

Read the full runbook