Freshness verdicts on read responses

File-scoped reads carry an effective_freshness block: the server's own statement of how current the bytes it served are. Reading it correctly prevents the two classic mistakes — treating stale bytes as current, and re-fetching state that was already verified fresh.

The fields that matter

verdict — the summary judgment. safe_to_edit means a check ran and came back clean. refresh_recommended means the server could not confirm currency; run refresh_index (or re-read) before editing.
source_used — where the bytes came from: canonical (committed, indexed git state) or working_tree (your uploaded overlay).
canonical_status — whether the canonical index is current or behind your repository's head. behind after a fresh push is normal for a short window; refresh_index forces the catch-up.
overlay_status — whether an overlay covers this file (covers_file), does not apply (not_applicable), or is missing where it should exist.
pending_edits_count — how many locally-dirty files the server knows about repo-wide, and how many are relevant to this file.

The assessment states

The nested assessment block says whether a per-file check actually ran. This is the authoritative field; it overrides any legacy field it disagrees with.

state: verified — a check ran; the reason names what it proved (for example clean_at_indexed_head, overlay_covers_file, or index_behind_local_head).
state: not_assessed — NO check ran. This is not a statement that the file is safe; it means the call shape did not permit a per-file check (for example, no file path was given).
state: unavailable — a check was attempted but could not complete; treat as unverified.

The one rule

Only verified + safe_to_edit means "edit on these bytes without re-reading". Everything else names its own next step — follow it rather than inventing one.