agent_sessions 0.3.0 → 0.3.1

data/doc/Agent/Sessions/Audit/Finding.md

@@ -0,0 +1,27 @@
+# Class Agent::Sessions::Audit::Finding <a id="class-Agent-Sessions-Audit-Finding"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/audit.rb |
+
+## Attributes
+### `agent` [R] <a id="attribute-i-agent"></a> <a id="agent-instance_method"></a>
+Returns the value of attribute agent
+- **@return** [Object] the current value of agent
+
+### `bytes` [R] <a id="attribute-i-bytes"></a> <a id="bytes-instance_method"></a>
+Returns the value of attribute bytes
+- **@return** [Object] the current value of bytes
+
+### `kind` [R] <a id="attribute-i-kind"></a> <a id="kind-instance_method"></a>
+Returns the value of attribute kind
+- **@return** [Object] the current value of kind
+
+### `path` [R] <a id="attribute-i-path"></a> <a id="path-instance_method"></a>
+Returns the value of attribute path
+- **@return** [Object] the current value of path
+
+### `synced_to` [R] <a id="attribute-i-synced_to"></a> <a id="synced_to-instance_method"></a>
+Returns the value of attribute synced_to
+- **@return** [Object] the current value of synced_to

data/doc/Agent/Sessions/Audit.md

@@ -0,0 +1,21 @@
+# Class Agent::Sessions::Audit <a id="class-Agent-Sessions-Audit"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Includes** | [Agent::Sessions::HomeExpansion](HomeExpansion.md) |
+| **Defined in** | lib/agent/sessions/audit.rb |
+
+Answers: are these plaintext transcripts inside anything that syncs? Needs
+only Layer 1. Time Machine exclusion status is a planned addition.
+
+## Constants
+### `SYNC_ROOTS` <a id="constant-SYNC_ROOTS"></a> <a id="SYNC_ROOTS-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `initialize(stores, env: ENV)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Audit] a new instance of Audit
+
+### `report()` <a id="method-i-report"></a> <a id="report-instance_method"></a>
+Not documented.

data/doc/Agent/Sessions/CLI.md

@@ -0,0 +1,36 @@
+# Class Agent::Sessions::CLI <a id="class-Agent-Sessions-CLI"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/agent/sessions/cli.rb |
+
+## Constants
+### `GROUP_COLUMN_MAX` <a id="constant-GROUP_COLUMN_MAX"></a> <a id="GROUP_COLUMN_MAX-constant"></a>
+Group names in `du --by project` are the same shape of problem one cap wider:
+a real project path on this machine ran 169 characters, wrapping every row
+across three lines on an 80-column terminal (list's own id column tops out at
+72 total). Wider than ID_COLUMN_MAX because a path's head (which user, which
+drive) and tail (the actual project directory) are both worth keeping, and
+both need more room than a bare uuid does.
+
+### `ID_COLUMN_MAX` <a id="constant-ID_COLUMN_MAX"></a> <a id="ID_COLUMN_MAX-constant"></a>
+Cap the id column. Cursor's ids are two nested uuids joined by "/" (36 + 1 +
+36 = 73 chars) where every other agent needs a bare uuid (36) or less, so one
+Cursor row makes the global id_width 73 — padding every other row with ~35
+spaces and pushing the line past 100 chars, which wraps on an 80-column
+terminal. Elide the middle and keep both ends, since the ends are what a human
+matches against a directory name.
+
+### `SINCE_UNITS` <a id="constant-SINCE_UNITS"></a> <a id="SINCE_UNITS-constant"></a>
+Not documented.
+
+### `STATUS_MARKS` <a id="constant-STATUS_MARKS"></a> <a id="STATUS_MARKS-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `initialize(argv, env: ENV, stdout: $stdout, stderr: $stderr, now: Time.now)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [CLI] a new instance of CLI
+
+### `run()` <a id="method-i-run"></a> <a id="run-instance_method"></a>
+Not documented.

data/doc/Agent/Sessions/Check.md

@@ -0,0 +1,27 @@
+# Class Agent::Sessions::Check <a id="class-Agent-Sessions-Check"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/check.rb |
+
+## Attributes
+### `agent` [R] <a id="attribute-i-agent"></a> <a id="agent-instance_method"></a>
+Returns the value of attribute agent
+- **@return** [Object] the current value of agent
+
+### `claim` [R] <a id="attribute-i-claim"></a> <a id="claim-instance_method"></a>
+Returns the value of attribute claim
+- **@return** [Object] the current value of claim
+
+### `detail` [R] <a id="attribute-i-detail"></a> <a id="detail-instance_method"></a>
+Returns the value of attribute detail
+- **@return** [Object] the current value of detail
+
+### `status` [R] <a id="attribute-i-status"></a> <a id="status-instance_method"></a>
+Returns the value of attribute status
+- **@return** [Object] the current value of status
+
+## Public Instance Methods
+### `pass?()` <a id="method-i-pass-3F"></a> <a id="pass?-instance_method"></a>
+- **@return** [Boolean]

data/doc/Agent/Sessions/Compaction.md

@@ -0,0 +1,23 @@
+# Class Agent::Sessions::Compaction <a id="class-Agent-Sessions-Compaction"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/compaction.rb |
+
+A point where the agent replaced earlier turns with a summary. Not a message:
+its own payload restates turns already yielded, so anyone counting would count
+them twice. replaced_count is how many turns it stood in for.
+
+## Attributes
+### `at` [R] <a id="attribute-i-at"></a> <a id="at-instance_method"></a>
+Returns the value of attribute at
+- **@return** [Object] the current value of at
+
+### `raw` [R] <a id="attribute-i-raw"></a> <a id="raw-instance_method"></a>
+Returns the value of attribute raw
+- **@return** [Object] the current value of raw
+
+### `replaced_count` [R] <a id="attribute-i-replaced_count"></a> <a id="replaced_count-instance_method"></a>
+Returns the value of attribute replaced_count
+- **@return** [Object] the current value of replaced_count

data/doc/Agent/Sessions/EnvOverride.md

@@ -0,0 +1,19 @@
+# Class Agent::Sessions::EnvOverride <a id="class-Agent-Sessions-EnvOverride"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/env_override.rb |
+
+## Attributes
+### `name` [R] <a id="attribute-i-name"></a> <a id="name-instance_method"></a>
+Returns the value of attribute name
+- **@return** [Object] the current value of name
+
+### `value` [R] <a id="attribute-i-value"></a> <a id="value-instance_method"></a>
+Returns the value of attribute value
+- **@return** [Object] the current value of value
+
+## Public Instance Methods
+### `active?()` <a id="method-i-active-3F"></a> <a id="active?-instance_method"></a>
+- **@return** [Boolean]

data/doc/Agent/Sessions/Error.md

@@ -0,0 +1,6 @@
+# Class Agent::Sessions::Error <a id="class-Agent-Sessions-Error"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | StandardError |
+| **Defined in** | lib/agent/sessions/error.rb |

data/doc/Agent/Sessions/HomeExpansion.md

@@ -0,0 +1,11 @@
+# Module Agent::Sessions::HomeExpansion <a id="module-Agent-Sessions-HomeExpansion"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/agent/sessions/home_expansion.rb |
+
+Shared path expansion for Adapters::Base and Audit. Expands "~" against the
+injected env so callers can resolve paths for a machine that is not their own;
+joins relative paths (including "~user"-looking strings that are not a real
+shell lookup here) under that same home; and treats an explicitly empty HOME
+the same as an absent one.

data/doc/Agent/Sessions/Location.md

@@ -0,0 +1,60 @@
+# Class Agent::Sessions::Location <a id="class-Agent-Sessions-Location"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/location.rb |
+
+One resolved layer of an agent's store.
+
+A location is one of three shapes, and `files` answers each differently:
+
+    glob         a directory plus a pattern       -> the pattern's matches
+    single_file  one file (a `path:` store)       -> itself, if it is there
+    directory    a directory with no known shape  -> nothing, and enumerable? is false
+
+The third shape is a store whose internal layout this gem has not learned yet
+(opencode's pre-1.2.0 storage/ tree, Cursor's acp-sessions/). It returns [] so
+a caller sweeping every layer does not blow up, and answers enumerable? false
+so that caller can tell "nothing here to enumerate" apart from "enumerated,
+found none".
+
+single_file comes from the adapter's store DSL: <code>path:</code> means one
+file, <code>dir:</code> means a directory. Resolution used to discard that
+distinction, which made a Layer 2 enumerator written as
+layers.flat_map(&:files) silently skip history.jsonl, session_index.jsonl and
+secrets.json — a missing-session bug, not a visible error.
+
+## Attributes
+### `format` [R] <a id="attribute-i-format"></a> <a id="format-instance_method"></a>
+Returns the value of attribute format
+- **@return** [Object] the current value of format
+
+### `glob` [R] <a id="attribute-i-glob"></a> <a id="glob-instance_method"></a>
+Returns the value of attribute glob
+- **@return** [Object] the current value of glob
+
+### `kind` [R] <a id="attribute-i-kind"></a> <a id="kind-instance_method"></a>
+Returns the value of attribute kind
+- **@return** [Object] the current value of kind
+
+### `path` [R] <a id="attribute-i-path"></a> <a id="path-instance_method"></a>
+Returns the value of attribute path
+- **@return** [Object] the current value of path
+
+### `single_file` [R] <a id="attribute-i-single_file"></a> <a id="single_file-instance_method"></a>
+Returns the value of attribute single_file
+- **@return** [Object] the current value of single_file
+
+## Public Instance Methods
+### `enumerable?()` <a id="method-i-enumerable-3F"></a> <a id="enumerable?-instance_method"></a>
+- **@return** [Boolean]
+
+### `exists?()` <a id="method-i-exists-3F"></a> <a id="exists?-instance_method"></a>
+- **@return** [Boolean]
+
+### `files()` <a id="method-i-files"></a> <a id="files-instance_method"></a>
+Not documented.
+
+### `initialize(kind:, path:, format:, glob: nil, single_file: false)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Location] a new instance of Location

data/doc/Agent/Sessions/Message.md

@@ -0,0 +1,59 @@
+# Class Agent::Sessions::Message <a id="class-Agent-Sessions-Message"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/message.rb |
+
+One turn. `role` is normalized to :user, :assistant, :system or :tool, with
+:unknown for a role the adapter did not recognize — the four the spec names
+were written before any real corpus was read, and Codex promptly said
+"developer".
+
+raw is never dropped (Layer 3 rule 1): when this normalization is wrong or
+incomplete, a caller escapes the abstraction instead of forking the gem.
+
+usage and model are nil wherever the format does not put them on the message
+itself — Codex records tokens in separate event records and the model in its
+session header, so its messages carry neither; the reader's session-level
+`usage` is where those formats answer. A nil here means "not recorded on this
+message", never "zero tokens".
+
+## Constants
+### `ROLES` <a id="constant-ROLES"></a> <a id="ROLES-constant"></a>
+Not documented.
+
+## Attributes
+### `at` [R] <a id="attribute-i-at"></a> <a id="at-instance_method"></a>
+Returns the value of attribute at
+- **@return** [Object] the current value of at
+
+### `model` [R] <a id="attribute-i-model"></a> <a id="model-instance_method"></a>
+Returns the value of attribute model
+- **@return** [Object] the current value of model
+
+### `parts` [R] <a id="attribute-i-parts"></a> <a id="parts-instance_method"></a>
+Returns the value of attribute parts
+- **@return** [Object] the current value of parts
+
+### `raw` [R] <a id="attribute-i-raw"></a> <a id="raw-instance_method"></a>
+Returns the value of attribute raw
+- **@return** [Object] the current value of raw
+
+### `role` [R] <a id="attribute-i-role"></a> <a id="role-instance_method"></a>
+Returns the value of attribute role
+- **@return** [Object] the current value of role
+
+### `usage` [R] <a id="attribute-i-usage"></a> <a id="usage-instance_method"></a>
+Returns the value of attribute usage
+- **@return** [Object] the current value of usage
+
+## Public Instance Methods
+### `initialize(role:, at:, parts:, raw:, usage: nil, model: nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@raise** [ArgumentError]
+- **@return** [Message] a new instance of Message
+
+### `text()` <a id="method-i-text"></a> <a id="text-instance_method"></a>
+Concatenated :text parts, as the design doc specifies — no separator inserted,
+because a separator is a formatting decision this layer has no business
+making. A caller that needs the boundaries has `parts`.

data/doc/Agent/Sessions/MissingDependency.md

@@ -0,0 +1,6 @@
+# Class Agent::Sessions::MissingDependency <a id="class-Agent-Sessions-MissingDependency"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Error](Error.md) |
+| **Defined in** | lib/agent/sessions/missing_dependency.rb |

data/doc/Agent/Sessions/Node.md

@@ -0,0 +1,24 @@
+# Class Agent::Sessions::Node <a id="class-Agent-Sessions-Node"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/node.rb |
+
+One message in a branching conversation, with the messages that follow it.
+Agents that let a turn be edited and re-run record two children under one
+parent: 380 such branch points sit across 85 of 151 real Claude transcripts,
+so a caller reading `messages` in file order is reading two alternative
+histories interleaved without being told.
+
+children is a plain Array and the Node is frozen, so the shape is settled
+before anyone sees it.
+
+## Attributes
+### `children` [R] <a id="attribute-i-children"></a> <a id="children-instance_method"></a>
+Returns the value of attribute children
+- **@return** [Object] the current value of children
+
+### `message` [R] <a id="attribute-i-message"></a> <a id="message-instance_method"></a>
+Returns the value of attribute message
+- **@return** [Object] the current value of message

data/doc/Agent/Sessions/Part.md

@@ -0,0 +1,41 @@
+# Class Agent::Sessions::Part <a id="class-Agent-Sessions-Part"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/part.rb |
+
+One piece of a message. `type` is the normalized vocabulary (design doc §5);
+everything an agent said that this gem could not classify arrives as :unknown
+rather than as an exception, and the message's `raw` still holds it.
+
+text carries the readable content for :text, :thinking and :tool_result. name
+and call_id are tool plumbing, nil elsewhere. An :image part has neither — its
+URL or payload stays in raw, because normalizing an image would mean deciding
+whether to load it, and reading is stat-cheap by design.
+
+## Constants
+### `TYPES` <a id="constant-TYPES"></a> <a id="TYPES-constant"></a>
+Not documented.
+
+## Attributes
+### `call_id` [R] <a id="attribute-i-call_id"></a> <a id="call_id-instance_method"></a>
+Returns the value of attribute call_id
+- **@return** [Object] the current value of call_id
+
+### `name` [R] <a id="attribute-i-name"></a> <a id="name-instance_method"></a>
+Returns the value of attribute name
+- **@return** [Object] the current value of name
+
+### `text` [R] <a id="attribute-i-text"></a> <a id="text-instance_method"></a>
+Returns the value of attribute text
+- **@return** [Object] the current value of text
+
+### `type` [R] <a id="attribute-i-type"></a> <a id="type-instance_method"></a>
+Returns the value of attribute type
+- **@return** [Object] the current value of type
+
+## Public Instance Methods
+### `initialize(type:, text: nil, name: nil, call_id: nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@raise** [ArgumentError]
+- **@return** [Part] a new instance of Part

data/doc/Agent/Sessions/Readers/Amp.md

@@ -0,0 +1,41 @@
+# Class Agent::Sessions::Readers::Amp <a id="class-Agent-Sessions-Readers-Amp"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/amp.rb |
+
+Amp threads. Written against the one real thread available (2026-08-14): 24
+messages, content parts tool_use 14, tool_result 14, text 2, thinking 1. One
+thread is thin evidence beside Codex's 415 files, and this reader says so
+through partial? rather than pretending otherwise.
+
+Two things make Amp unlike the JSONL readers:
+
+A thread is ONE JSON document, so it cannot be streamed a record at a time.
+Reading any of it means holding all of it, which is the gem's one unbounded
+read (0.2 follow-up 8). each_record below is where that bound finally lives.
+
+And its tool results are spelled its own way — toolUseID rather than
+tool_use_id, the payload under run.result rather than content. A mapper copied
+from Claude's would produce empty tool results and no warning, which is why
+each reader maps its own agent rather than sharing one.
+
+## Constants
+### `CONTENT_PARTS` <a id="constant-CONTENT_PARTS"></a> <a id="CONTENT_PARTS-constant"></a>
+Not documented.
+
+### `MAX_DOCUMENT_BYTES` <a id="constant-MAX_DOCUMENT_BYTES"></a> <a id="MAX_DOCUMENT_BYTES-constant"></a>
+150x the observed thread. A cap has to exist because nothing about a thread
+file announces its size before it is opened, and JSON.parse of a 200 MB
+document costs several times that in live objects. Refused and reported beats
+NoMemoryError, and beats silence either way.
+
+### `ROLES` <a id="constant-ROLES"></a> <a id="ROLES-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `partial?()` <a id="method-i-partial-3F"></a> <a id="partial?-instance_method"></a>
+The server holds the canonical copy; a local thread may be a mirror of part of
+the conversation. The adapter carries the same warning.
+- **@return** [Boolean]

data/doc/Agent/Sessions/Readers/Base.md

@@ -0,0 +1,91 @@
+# Class Agent::Sessions::Readers::Base <a id="class-Agent-Sessions-Readers-Base"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/agent/sessions/readers/base.rb |
+
+Layer 3: turning one session file into messages. Subclasses supply the
+mapping; everything about *how the file is read* lives here, because the three
+rules that make this layer survivable (design doc §5) are properties of the
+reading, not of any one agent's format:
+
+    1. raw is never dropped.
+    2. Unknown records become :unknown parts and warnings, never exceptions.
+    3. Reading streams. No code path may assume a file fits in memory.
+
+Rule 3 is why this does not use File.foreach without a chunk size. A truncated
+log can hold no newline at all, and "read one line" would then mean "read 2.6
+GB into a String" — the file the article that started this gem found on a real
+machine.
+
+## Constants
+### `MAX_RECORD_BYTES` <a id="constant-MAX_RECORD_BYTES"></a> <a id="MAX_RECORD_BYTES-constant"></a>
+Chunk size, and so the largest record that can be read whole. Measured against
+415 real Codex rollout files (128,987 records, 2026-08-12): 14 records exceed
+1 MB and the largest is 2.41 MB, so Layer 2's MAX_LINE_BYTES of 1 MB would
+silently drop real messages. 8 MB is ~3.3x the observed maximum. A record
+beyond it is reported, never dropped in silence, because a missing message is
+this gem's worst failure mode.
+
+## Attributes
+### `session` [R] <a id="attribute-i-session"></a> <a id="session-instance_method"></a>
+Returns the value of attribute session.
+
+## Public Instance Methods
+### `branching?()` <a id="method-i-branching-3F"></a> <a id="branching?-instance_method"></a>
+Whether this agent records which turn each turn followed. False here: most
+stores are an append-only list and a tree would have to be invented.
+- **@return** [Boolean]
+
+### `compactions()` <a id="method-i-compactions"></a> <a id="compactions-instance_method"></a>
+Boundaries where the agent replaced earlier turns with a summary. Its own
+pass: a caller asking only for compactions should not have to materialize
+every message to get them.
+
+### `each_message()` <a id="method-i-each_message"></a> <a id="each_message-instance_method"></a>
+Streams. Yields each message as it is parsed; a caller that breaks after one
+has read one record, not the file.
+
+### `fidelity()` <a id="method-i-fidelity"></a> <a id="fidelity-instance_method"></a>
+Not documented.
+
+### `initialize(session, include_events: false)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Base] a new instance of Base
+
+### `messages()` <a id="method-i-messages"></a> <a id="messages-instance_method"></a>
+Eager, for sessions small enough to hold. The design doc offers both and names
+this the convenience: `messages` is what a script wants, and `each_message` is
+what a 2.6 GB file requires.
+
+### `partial?()` <a id="method-i-partial-3F"></a> <a id="partial?-instance_method"></a>
+True where the local file is not the whole story — Amp, whose server holds the
+canonical copy. Overridden there, false everywhere else.
+- **@return** [Boolean]
+
+### `tree()` <a id="method-i-tree"></a> <a id="tree-instance_method"></a>
+The conversation as roots and their continuations, for an agent that records
+parent links. Unlike every other method here this cannot stream — a tree is
+not knowable until the last record is read — so it holds one session's
+messages at once and says so rather than pretending otherwise.
+
+Raises rather than returning an empty list or nil for a store with no parent
+links, for the reason Agent::Sessions.read raises: "this format does not
+record that" must never read as "this session has none".
+
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+This session's token totals as a Usage, or nil where the format does not
+record them (Amp) or this reader has not learned where they live. nil, not an
+empty Usage: "this store does not say" must never read as "this session cost
+nothing" — the same rule tree() enforces by raising.
+
+Each reader that overrides this also decides its own summation rule, because
+that rule is format knowledge: Claude repeats one API response's usage across
+several records (94 of 124 message ids in one real transcript), Codex writes a
+running total where only the last record counts. A base-class sum would get
+both wrong.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+Populated as records are read, so this answers for whatever has been consumed
+so far. uniq because a second pass over the same file would otherwise repeat
+every warning it already reported.

data/doc/Agent/Sessions/Readers/Claude.md

@@ -0,0 +1,77 @@
+# Class Agent::Sessions::Readers::Claude <a id="class-Agent-Sessions-Readers-Claude"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/claude.rb |
+
+Claude Code transcripts. Written against 142 real transcripts, 29,688 records,
+inventoried 2026-08-12.
+
+The content vocabulary is a straight match for this gem's: text, thinking,
+tool_use, tool_result and image are exactly the five part types the design doc
+names, so nothing here has to invent a mapping. What Claude adds is everything
+**around** the conversation — a third of all records are session state, and
+two more kinds carry context the model saw without being a turn anyone took.
+
+## Constants
+### `CONTENT_PARTS` <a id="constant-CONTENT_PARTS"></a> <a id="CONTENT_PARTS-constant"></a>
+Not documented.
+
+### `EVENT_TYPES` <a id="constant-EVENT_TYPES"></a> <a id="EVENT_TYPES-constant"></a>
+Context the model saw, but not a turn: `system` is turn_duration,
+stop_hook_summary, away_summary, local_command; `attachment` is hook output,
+skill listings, task reminders, pasted files. Same judgement Codex's event_msg
+gets — available on request, never on by default.
+
+### `MAX_SPILL_BYTES` <a id="constant-MAX_SPILL_BYTES"></a> <a id="MAX_SPILL_BYTES-constant"></a>
+A spilled file is read whole. The largest observed is well under this; the cap
+exists because the pointer says nothing about the size.
+
+### `NON_MESSAGE_TYPES` <a id="constant-NON_MESSAGE_TYPES"></a> <a id="NON_MESSAGE_TYPES-constant"></a>
+State, not conversation, and together 11,000+ of the records written. Skipped
+in silence: warning about a record deliberately classified would teach a
+caller that warnings are noise.
+
+atis-latch and bridge-session postdate the corpus above — found by running
+this reader over a live 2026-08-24 transcript and reading its own warnings (23
+and 17 records), the same way Codex's tool list grew. Both are session
+plumbing: a latch marker, and the record tying a local transcript to its cloud
+session id (bridgeSessionId, owner uuids). Neither is a turn anyone took.
+
+### `SPILL` <a id="constant-SPILL"></a> <a id="SPILL-constant"></a>
+How Claude Code points at output too large to inline. It is prose, not a
+structured field — 24 real tool_result parts and 149 attachments carry this
+sentence — so the path has to be matched out of the text.
+
+## Public Instance Methods
+### `branching?()` <a id="method-i-branching-3F"></a> <a id="branching?-instance_method"></a>
+Every uuid-bearing record names the record it followed, and 380 branch points
+sit across 85 of 151 real transcripts — a turn edited and re-run leaves two
+children under one parent. Exactly one root per file and no orphaned parent
+link was found in that corpus, so the links are trustworthy enough to build a
+tree from.
+- **@return** [Boolean]
+
+### `initialize(session, resolve_spills: true, **rest)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Claude] a new instance of Claude
+
+### `subagents()` <a id="method-i-subagents"></a> <a id="subagents-instance_method"></a>
+The transcripts of agents this session spawned, as readers of their own.
+Exposed rather than inlined, per design doc 8.1: a subagent's turns are not
+the parent's turns, and merging them would break every count taken from this
+reader. 124 of these sit beside real sessions on this machine.
+
+isSidechain is false on all 22,072 records in the main transcripts, so there
+is nothing to filter out there — the separation is already how Claude Code
+writes them.
+
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+Session totals, summed over assistant records but deduplicated by message.id
+first — and the dedup is most of the number. One API response streams into one
+record PER CONTENT BLOCK, each carrying the same message.id and the same
+usage: in one real transcript on this machine (2026-08-24), 260 assistant
+records share 124 message ids, 94 of which repeat with byte-identical usage. A
+naive sum reports roughly double what Anthropic billed. An id-less record (not
+observed, but rule 2 says formats drift) is counted rather than dropped:
+overcounting a novelty beats silently ignoring it.