Module session_io

Expand description

Read/write/append snapshot state for the agent:<defId>:current zone, including the global-mirror normalization + one-shot heal.

Constants§

OUTPUT_FILE: Raw NDJSON stream for crash-recovery replay.
SNAPSHOT_FILE: Full UI snapshot (JSON). Frontend reads this on pane mount.
TSIDX_FILE: Receive-time sidecar for output: one NDJSON {"off":<byte offset of the appended batch>,"ms":<unix ms>} record per append batch. A pure addition — output’s own format and every existing parser are untouched; a missing or corrupt sidecar degrades reads to “no stamps” (today’s behavior). Gives replayed transcript nodes real timestamps (hover peek after restore, day separators). Spec: SPEC_AGENT_PANE_SESSION_SCOPED_SCROLLBACK_AND_AGENT_HISTORY_VIEW_2026_08_09.md §4.4.

append_session_output: Append line (with a trailing newline added if not present) to output in agent:<defId>:current. Creates the file if missing.
heal_global_snapshot_source_block_ids: One-shot heal for global snapshots poisoned before the normalize-on-mirror fix (a channel-local sourceBlockId was mirrored into agent:<defId>:current, breaking cross-channel opens). For each def_id, rewrite its global snapshot’s sourceBlockId to “” iff it isn’t already. Idempotent and cheap (one small JSON per agent); returns the number healed. Best-effort per agent.
normalize_snapshot_for_global: Strip sourceBlockId to “” for the GLOBAL (cross-channel) snapshot mirror.
read_session_state: Read output.state.json from agent:<defId>:current. Returns Ok((None, None)) when the zone doesn’t exist — that’s the “fresh agent, nothing to restore” path and is NOT an error.
read_snapshot_from 🔒: Read output.state.json from zone in store. Ok(None) when absent.
write_session_state: Write content to output.state.json in agent:<defId>:current. Idempotent — creates the file if missing, overwrites otherwise.