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.

Re-exports

use std::collections::HashMap; 🔒

use std::collections::HashSet; 🔒

use std::fs; 🔒

use std::io::BufRead; 🔒

use std::io::BufReader; 🔒

use std::io::Read; 🔒

use std::io::Seek; 🔒

use std::io::SeekFrom; 🔒

use std::path::Path; 🔒

use std::path::PathBuf; 🔒

use serde_json::Value; 🔒

use unicode_normalization::UnicodeNormalization; 🔒

use uuid::Uuid; 🔒

use forge_primitives::FORGE_WORKER_TAG_PREFIX; 🔒

use forge_primitives::SDKSessionInfo; 🔒

use forge_primitives::SessionHistory; 🔒

use forge_primitives::SessionMessage; 🔒

use forge_primitives::SessionMessageKind; 🔒

use forge_primitives::worker_tag; 🔒

use forge_sdk::projects_dir_for; 🔒

Structs

Block 🔒

One sidecar’s frames and the dispatch it ran as.

LiteSessionFile 🔒

Head / tail snapshot of a session file - enough to recover all SDKSessionInfo fields without a full scan. The tag field is populated by a separate streaming line-scan because tag rows can appear anywhere in the file (start-of-file at spawn, mid-file via /new re-tag) and the head + tail windows miss both cases on large transcripts.

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.

SidecarLink 🔒

A sidecar’s own meta: the dispatch its agent ran as, and the agent whose sidecar fired that dispatch.

Window 🔒

One window of a transcript file: the bytes read and the byte they start at.

Enums

Workers

Which worker sessions a listing may carry.

Constants

LIST_SESSIONS_MAX_CONCURRENT 🔒

Bounded-concurrency cap for list_sessions per-file lite reads.

LITE_READ_BUF_SIZE 🔒

Size of the head / tail byte buffer for lite metadata reads. The CLI constant - match exactly so the two implementations slice transcripts at the same boundary.

MAX_SANITIZED_LENGTH 🔒

ROWS_PAST_CUT 🔒

How many rows past a page’s own count a cut may step back over, so that it does not open on a result without its call.

SIDECAR_BUDGET_BYTES 🔒

How many bytes of sidecar frames one resume reads in total. A session can hold hundreds of sidecars and most of them are older than the window the conversation is cut to, so the read is bounded rather than whole (#1763).

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.

START_REASONS 🔒

The removal reasons that mean the CLI TOOK the prompt, read off this machine’s transcripts: absorbed_mid_turn (pressed into the running turn), delivered_to_agent (handed over at its boundary), and the empty reason on rows written before the field existed. Any other reason did not start the prompt and draws no row.

SYSTEM_ROWS_DRAWN_ELSEWHERE 🔒

The system subtypes whose row is not the conversation’s: the task lifecycle lands on its call’s row, the background-task and command lists feed their own surfaces, the handshake is not content, and a hook run draws from its attachment row. The client filters the same list (its own SYSTEM_DRAWN_ELSEWHERE), because the read and the live path are one obligation - a subtype added here belongs there, and the other way round.

UNREAD_TRANSCRIPT_COUNT_NOTE 🔒

Tail shared by every get_session_messages bail. The compaction count these paths return is unknown rather than zero, and the Projects-pane row hides at zero, so “count says 0 on a session I know compacted” has no triage path unless each bail is greppable.

UNSERVED_ROWS 🔒

Top-level rows the read does not serve, of two kinds: the transcript’s own bookkeeping, which the CLI writes to disk and never streams, and the wire types that live only on the stream and have no durable row.

Functions

already_kept 🔒

Whether this read has already kept a row under uuid.

answered_dispatches 🔒

The calls row answers.

answers_dispatch 🔒

Whether row is the tool result answering dispatch.

block_field 🔒

The field of every content block of kind in row.

canonicalize_path 🔒

Resolve a directory to its realpath and apply NFC normalisation. Wraps the CLI’s _canonicalize_path (falls back to the input, NFC-normalised, when the path can’t be canonicalised: most commonly because it doesn’t exist). NFC is essential on filesystems that don’t auto-normalise (Linux ext4, Windows NTFS) so decomposed inputs still hash to the CLI’s on-disk project-key layout.

carries_a_result 🔒

Whether a row carries a tool result: the kind of row a cut may not land on, because the call it answers sits just above it in the page below.

compact_boundary_frame 🔒

The boundary row in the shape the wire sends.

emit_block 🔒

Append one block, with each child block inserted after the row that carries its dispatch.

emit_sidecar_tree 🔒

One owner’s blocks, flattened in the order the work ran: a block emits at the row naming its dispatch, and a block no other names - its parent body was past the budget - follows the roots.

extract_command_name 🔒

Extract <command-name>CMD</command-name> when present.

extract_first_prompt_from_head 🔒

Extract the first meaningful user prompt from a JSONL head chunk. Skips tool_result, isMeta, isCompactSummary, slash-command messages (with command-name fallback), and the fixed-prefix skip patterns the CLI’s _SKIP_FIRST_PROMPT_PATTERN matches. Truncates to 200 chars with an ellipsis.

extract_json_string_field 🔒

Extract the first occurrence of a JSON string field ("key":"value" or "key": "value"). Scans bytes directly to survive partial tail reads; unescapes via serde_json only when the value contains a backslash. Returns None when the field is absent or unterminated.

extract_last_json_string_field 🔒

Like extract_json_string_field but returns the LAST occurrence.

find_bytes 🔒

Find the first byte offset where needle begins in haystack.

fold_subagent_sidecars 🔒

Insert each dispatch’s sidecar frames under the first row its chain answers. Appending them at the end would put them at the newest edge of the resumed window, ahead of the main rows.

get_session_messages

Read the full transcript for one session.

has_a_transcript_row

Whether a transcript row carries this frame.

hook_outcome 🔒

The outcome the live frame reports for one persisted run record.

hook_output 🔒

What one persisted hook run printed, as a hook_response frame carries it.

is_hook_attachment 🔒

Whether an attachment row records a hook run the live stream forwards.

is_queued_attachment_row 🔒

Whether a transcript line is the attachment the CLI writes for a prompt queued mid-turn.

is_valid_uuid 🔒

True if s is a canonical 8-4-4-4-12 hyphenated UUID. The length guard rejects the hyphenless / braced / URN forms that Uuid::try_parse otherwise accepts - session ids on disk are always the hyphenated form the CLI emits.

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.

live_hook_event 🔒

The hook events whose runs the live stream forwards, and therefore the only ones a read serves as rows.

messages_from_rows 🔒

The rows a transcript’s messages convert to, typed as the wire sends them and stamped with session_id.

missing_boundary_facts 🔒

Which of the facts the kept boundary frame reads the row did not yield - the trigger, and the counts either side of the cut.

owning_dispatch 🔒

The dispatch whose row a sidecar’s frames belong under: the first dispatch in its chain the transcript answers.

parse_rfc3339_ms 🔒

Parse the CLI’s RFC-3339 timestamp (e.g. 2026-04-22T04:15:27.123Z) into Unix epoch milliseconds. Sub-millisecond precision is truncated.

parse_session_info_from_lite 🔒

Build an SDKSessionInfo from a lite head/tail read. Skips sidechain transcripts and metadata-only sessions (no summary after all fallbacks).

parse_session_messages 🔒

project_dir_for 🔒

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).

queue_remove_row 🔒

The queue-operation remove line as the queued prompt’s row, or None for any other line.

queue_row_id 🔒

The row’s id, minted from the one line an anchored read can reproduce.

queued_prompt_text 🔒

The prompt words an attachment row’s synthesised message carries.

queued_start_row 🔒

The row a remove line draws, taking the attachment that named the press if one is waiting.

read_rows

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

read_rows_with 🔒

read_rows with the page’s own budget in the caller’s hands, so the growth, the cap and the search bound can be driven by a test without a transcript of the size the production budget is written for.

read_session_info 🔒

read_session_info_at

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

read_session_info_with 🔒

read_session_lite 🔒

Open a session file, stat it, read at most LITE_READ_BUF_SIZE bytes from the head and the same from the tail. For files smaller than the buffer, tail == head (single read). Returns None on any I/O error or for empty files.

read_session_messages 🔒

read_session_messages_main_thread 🔒

get_session_messages over the session’s own rows only: no sub-agent sidecars are opened or folded. The handoff brief takes this one, so it neither pays for the sidecar parse nor carries frames it does not read. A page read does not: a dispatch row draws its sidecar frames (#1763).

resolve_anchor 🔒

Where a read’s window ends for a named anchor: the byte its row starts at, seeking when the cursor carries a byte and searching from the file’s end when it does not.

row_at 🔒

The row that starts at at, for the anchored read’s verify.

sanitize_path 🔒

Sanitise a path the same way the claude CLI does - non-alphanumerics become hyphens, and overlong paths are truncated with a base-36 hash suffix (matching JS’s String.prototype.hashCode trick).

sanitize_path_public 🔒

Crate-internal re-export of the path sanitiser - other modules need it to derive the same on-disk project-key layout the CLI uses. Not part of the public API; downstream consumers should call project_key_for_directory instead.

scan_tag_from 🔒

Return the value of the LAST {"type":"tag"} row’s "tag" field. Empty strings are filtered. None when no tag row is present or any read errors out.

session_in_row 🔒

The session a transcript row belongs to. The wire spells it session_id; a row the CLI wrote spells it sessionId.

session_row 🔒

One line of a transcript as its row, or None for a line that is not one.

session_transcript 🔒

The file a session id reads from: its project’s directory when the caller places it, the first copy named after it otherwise.

should_exclude_worker_tag

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

should_skip_first_prompt 🔒

Fixed-prefix counterpart to the CLI’s _SKIP_FIRST_PROMPT_PATTERN.

simple_hash 🔒

32-bit integer hash to base-36, matching the CLI’s directory naming.

subagent_sidecars 🔒

The frames a session’s sub-agent sidecars hold, with each sidecar’s own dispatch and every meta’s chain link. The links are read for all sidecars, not only the ones inside the budget; the fold stamps the rows themselves.

subagent_sidecars_with_budget 🔒

subagent_sidecars with the read budget given, so the cap is drivable at a size a test can build.

synthesize_hook_frame 🔒

One persisted hook run as the live frame the chat folds.

synthesize_queued_command_message 🔒

Build a {"role":"user","content":[{queued_command}]} envelope from a JSONL attachment row’s attachment field. Used during session replay to surface mid-turn queued inputs that claude persisted as type:"attachment" rows (which the scanner would otherwise skip).

tag_and_project_of 🔒

The last tag AND the project its row names, with the same cache and read-error behaviour as tag_of. A worker resume uses the project to tell this project’s session from another project’s in a directory both compose to.

tag_of 🔒

The last tag path’s transcript carries, with the read error read_session_lite turns into “untagged” handed back as one: a caller that has to tell an unreadable transcript from an untagged one cannot use the lite read.

tool_use_ids 🔒

The calls made in row.

transcript_row 🔒

One transcript row as the session’s message, or None for a row that is not one. The flag says the row is a compaction boundary, which the read counts.

try_read_dir 🔒

Open dir for directory iteration. NotFound is the expected case for the catalog’s projects/ tree on a fresh forge install and is silent; real I/O failures (perm denied, broken FS) log at warn so the user gets a triage signal rather than silently empty catalog reads.

unescape_json_string 🔒

Unescape a JSON string value. No-op when there are no backslashes.

window_ending 🔒

Read up to take bytes ending at end, and the byte before the window as well.

window_rows 🔒

The rows a window holds, each with the byte it starts at.

wire_session_frame 🔒

A kept row carrying the session under the spelling the live frame sends.

Type Aliases

SidecarRead 🔒

The sidecar bodies the budget admitted, and every meta’s chain link.