Module session_archive 

Session archival and cleanup (Phase 3.3 — ultra-long-sessions).

Responsibilities:

1. Periodic sweep: archive sessions inactive for inactive_days days by compressing their FileStore “output” file to archive_dir/<block_id>.jsonl.gz and freeing the FileStore entry.
2. Storage cap: after archiving, prune oldest .gz files until total archive disk usage is below max_total_bytes (default 2 GB).

The sweep archives through the same archive_session_output the RPC handlers in server/app_api/session.rs call; those handlers also use restore_session_output and read_session_output from this module.

Structs

SessionArchiver

Periodic session archival + storage cap enforcement.

SessionArchiverStats

Statistics from a single sweep run.

Constants

META_SESSION_ARCHIVED_AT

Unix ms when the session was last archived.

META_SESSION_ARCHIVED_BYTES

Byte count before compression (original output size).

META_SESSION_ARCHIVE_PATH

Absolute path to the .jsonl.gz archive file.

OUTPUT_FILENAME 🔒

FileStore filename for session output.

TSIDX_FILENAME 🔒

Receive-time sidecar (see agent_session::TSIDX_FILE) — archived, deleted, and restored in lockstep with output (codex P2 on PR #2508): leaving it behind would mis-time a fresh session’s lines (new output restarts at offset 0 under stale entries), and dropping it from the archive loses the timestamps the sidecar exists to preserve.

Functions

archive_session_output

Archive the FileStore “output” file for block_id:

bytecount_lines 🔒

Count non-empty lines in a byte buffer.

default_archive_dir

Returns ~/.agentmux/archives/, or None if the home directory cannot be determined.

ensure_archive_dir 🔒

Ensure the archive directory exists.

read_gz 🔒

Decompress a .gz file and return raw bytes.

read_session_output

Read the raw session output bytes, whether from FileStore (live) or archive. Returns (bytes, line_count).

restore_session_output

Restore an archived session back into FileStore:

write_gz 🔒

Compress data with gzip and write to dest_path.