Module scan 

Offline session scanners - stateless filesystem helpers that read transcripts from <config_dir>/projects/<project_key>/*.jsonl.

• list_sessions - lists sessions, either for one project or all.
• get_session_messages - reads the full transcript for one session.

Session metadata (list_sessions) comes from an internal head + tail lite read, so the fields it parses cost two 64 KiB reads whatever the transcript’s size. The worker tag is the exception and is read in full: it can sit anywhere in the file and the last one wins, so there is no window that settles it.

Structs

SessionTagCache

Carries the previous run’s tag scans into this one and collects what changed, so the whole catalog costs one store read up front and one store write at the end rather than a transaction per transcript.

SessionTagScan

What a tag scan learned about one transcript, and how far into it the answer is known to hold.

Enums

Workers

Which worker sessions a listing may carry.

Constants

SPAN_CAP_BYTES

SPAN_ROWS_PER_TURN

How many rows a page’s own turn count may ask for.

SPAN_STEP_BYTES

How many bytes of a transcript one paging pass reads before growing, and how wide a single window it takes may be.

Functions

get_session_messages

Read the full transcript for one session.

has_a_transcript_row

Whether a transcript row carries this frame.

list_sessions

List sessions. When directory is Some, scans that project dir; when None, scans every project directory under config_dir’s projects/ tree. A capped listing stats each candidate for its mtime, reads newest first on the tokio blocking pool (at most 16 at once), and stops once the rows the cap serves are in hand - a short batch is filled by the next, so the cap bounds the reads without shortening the listing. An uncapped listing (the boot scan) reads every candidate. workers decides which worker-tagged rows may appear, and it lands before the cap: a listing is never shortened by rows it would not have carried.

project_key_for_directory

Map a directory path to the CLI’s on-disk project key. Canonicalises the path first and then applies the CLI’s JS-style sanitisation hash. None defaults to "." (the process’s current working directory).

read_rows

Read the rows of session_id’s transcript that sit strictly before below, newest first, up to rows_wanted of them.

read_session_info_at

The one transcript at path, read for its title and clock.

should_exclude_worker_tag

True when info represents a worker session: one whose transcript carries a forge:worker:<label> tag.