agent_sessions 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9c351be12ac0d3201532322115c21d9277bb54e7d1d7d7b6e6e2c373ba793a9
-  data.tar.gz: 1ecb97c0d890c97542dafea00b6b8bd39b02f7427c7ad5c8627d69f2886ff1f7
+  metadata.gz: 963cada8c8c93c253b1e09647a64a210b1f1e009b84e064b38e5aa39d20853af
+  data.tar.gz: 3a2c3b727bf7710e8be93f52370fe5710898a6b12abc458135826c32a0a97178
 SHA512:
-  metadata.gz: f963abdeb2b16d53fc32bd098abeabc4f461bda5d229b960322b3513f06719136f933e77a6a2a2428a9b655d0a9e01946c16eb8de606b7e5f8acae2517d28f1c
-  data.tar.gz: 1f82162c07217a3175459d54301d5cb5417c18a35a42a68cda9efeaddba7276c84b666cbb6265c70089cf9a65fef55ea17de877699c4bbc26ba34424d9ee8371
+  metadata.gz: 2a947ed4f5ffe8890d0d4785048c88218857f113325656ea5be28c34761d2178f8d08a3a661adcf8d22bd096e3d53470e9234642ac734f2ee8a5a81be5030f46
+  data.tar.gz: ff29e6acb8c4bde8c8aabfa7775c9b1fc3de945419f21922ff87d7272bd5e258b8d98a5c7df102fa5564ba5aff6a50c437dd9e1ce10a2321e37d7f08ef6cd512

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.3.1 (2026-08-26)
+
+- Add tracked Markdown YARD documentation and a consolidated `llm.txt`, package both with the gem, and validate every local documentation link
+- Add a deterministic, warning-free documentation generator and a fail-fast `bin/prepare_release` workflow that tests, rebuilds documentation, refreshes `llm.txt`, and builds without publishing
+- Verify the supported Ruby floor and current release in CI on Ruby 3.2 and 4.0.1, and harden gem builds with a Git-independent manifest plus isolated installation and CLI checks
+- Strengthen adapter conformance coverage and remove order dependence from the affected tests and fixtures
+- Keep YARD tooling development-only; runtime dependencies remain `agent_homedir` and `zeitwerk`
+
 ## 0.3.0 (2026-08-25)
 
 - Breaking: the Ruby namespace is now `Agent::Sessions`; `AgentSessions` is removed with no alias. `require "agent_sessions"` still works through the shim and defines the new namespace

data/README.md

@@ -2,6 +2,8 @@
 
 Where do AI coding agents store their session logs? This gem knows.
 
+![agent-sessions demo](docs/demos/demo.gif)
+
 Resolves session store paths for Claude Code, Codex CLI, Cursor (CLI and IDE), Amp CLI, opencode, pi, Gemini CLI, GitHub Copilot CLI, Qwen Code, and Grok Build. Verifies those paths against disk. Audits whether plaintext transcripts sit inside anything that syncs.
 
 Read-only by design. Runtime dependencies: `agent_homedir` and `zeitwerk`.
@@ -12,12 +14,22 @@ Two adapters, Qwen Code and Grok Build, are marked provisional: no such store ex
 
 ## Installation
 
-Add to your Gemfile:
+Use Ruby 3.2 or newer.
+
+Install the CLI directly:
+
+```sh
+gem install agent_sessions
+```
+
+Or add to your application's Gemfile:
 
 ```ruby
 gem "agent_sessions"
 ```
 
+Enumerating the SQLite-backed agents — opencode, Cursor IDE, and GitHub Copilot CLI — needs the optional `sqlite3` gem. Every other adapter works without it.
+
 ## Quick start
 
 ```sh
@@ -30,8 +42,32 @@ agent-sessions du --by project
 
 Add `--json` to `where`, `doctor`, `audit`, `list`, or `du` for machine-readable output. `du --by project` is the one command in the gem that is not stat-only: resolving a project name pays one bounded read per session for the file-based agents (opencode answers from its own SQL query instead, so it pays nothing extra).
 
+## Supported agents
+
+Use the bare name in CLI arguments and the symbol in Ruby calls:
+
+| Agent | CLI | Ruby |
+| --- | --- | --- |
+| Claude Code | `claude` | `:claude` |
+| Codex CLI | `codex` | `:codex` |
+| Cursor CLI | `cursor` | `:cursor` |
+| Cursor IDE | `cursor_ide` | `:cursor_ide` |
+| Amp CLI | `amp` | `:amp` |
+| opencode | `opencode` | `:opencode` |
+| pi | `pi` | `:pi` |
+| Gemini CLI | `gemini` | `:gemini` |
+| GitHub Copilot CLI | `copilot` | `:copilot` |
+| Qwen Code | `qwen` | `:qwen` |
+| Grok Build | `grok` | `:grok` |
+
+Ruby callers passing any other symbol get `Agent::Sessions::UnknownAgent`; its message lists the valid names. The CLI catches that error, prints its message, and exits with status 1.
+
 ## Ruby API
 
+![agent_sessions Ruby API demo](docs/demos/demo-ruby.gif)
+
+Browse the [generated API documentation](https://github.com/lucianghinda/agent_sessions/blob/main/doc/Agent/Sessions.md) or the consolidated [`llm.txt`](https://github.com/lucianghinda/agent_sessions/blob/main/llm.txt) reference.
+
 ```ruby
 require "agent_sessions" # compatibility shim for Agent::Sessions
 
@@ -70,7 +106,7 @@ Agent::Sessions.for_project(Dir.pwd)            # every agent's sessions for one
 Agent::Sessions.projects(:codex)                # distinct recorded project paths (reads headers)
 ```
 
-Enumerating the SQLite-backed agents — opencode, Cursor IDE and Copilot CLI — needs the optional `sqlite3` gem. Readers exist for opencode and Copilot CLI; Cursor IDE remains metadata-only. The other adapters do not need that additional optional dependency.
+Among the SQLite-backed agents, readers exist for opencode and Copilot CLI; Cursor IDE remains metadata-only.
 
 Read a session's messages and token usage (Claude, Codex, Amp, opencode, pi, Gemini CLI, Copilot CLI, Qwen and Grok):
 
@@ -86,13 +122,45 @@ reader.usage&.input                           # disjoint buckets: input, output,
 
 `Session#bytes` is what that session occupies on disk, not just its transcript. Claude Code writes a sidecar directory beside each transcript — `<id>/subagents/`, `<id>/tool-results/` — and those bytes belong to the session that produced them, which is why `du` and `audit` agree on the same store.
 
+### Errors
+
+Every domain-specific error the gem raises descends from `Agent::Sessions::Error`:
+
+- Catch `Agent::Sessions::UnknownAgent` for a name outside the supported-agents table; the message lists valid names.
+- Catch `Agent::Sessions::MissingDependency` when a SQLite-backed agent is enumerated without the optional `sqlite3` gem installed.
+- Catch `Agent::Sessions::UnsupportedFormat` when `read` is called on a session whose format has no reader (Cursor CLI and Cursor IDE).
+- Catch `Agent::Sessions::UnreadableStore` when a store exists but cannot be opened.
+
 ## Roadmap
 
 - 0.2: enumerate sessions, map them to projects (`list`, `du`)
 - **0.3 (this release):** read and normalize messages; Ruby API renamed to `Agent::Sessions` while `require "agent_sessions"` stays as the compatibility shim, and base-dir resolution delegates to `agent_homedir`
-- 0.4: Cursor IDE remains metadata-only; the opencode and Copilot CLI SQLite readers landed in 0.3
+- 0.4: a reader for Cursor IDE, which is metadata-only today
 - 0.5: `export` with secret redaction
 
+## Contributing
+
+Activate Ruby 3.2 or newer.
+
+Run the tests before sending a change:
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+Before a release, run:
+
+```sh
+bin/prepare_release
+```
+
+It runs the test suite, regenerates the API documentation and `llm.txt`, and builds the gem without publishing it.
+
+## License
+
+MIT
+
 ## History
 
 View the [changelog](CHANGELOG.md).

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

@@ -0,0 +1,91 @@
+# Class Agent::Sessions::Adapters::Amp <a id="class-Agent-Sessions-Adapters-Amp"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/amp.rb |
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `project_path_for(path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+env.initial.trees is the array a workspace's roots live in (plural —the format
+is shaped for more than one). Verified 2026-08-05: the one real thread on this
+machine carries exactly one tree, so `trees` is reported and an actual
+multi-root thread's other roots are silently unreachable through
+sessions_for_project/project_paths — see the warning below, which is where a
+user who hits that finds out, since nobody who has looked at real data has hit
+it yet. Reporting only the first is still the right call: Session#project_path
+is a single String, not a list, so supporting every root would be a data-model
+change this task does not make, and the failure mode is a false NEGATIVE (a
+real root that never matches), never a false positive.
+
+started_at deliberately does NOT read `created` from this same JSON: that
+would turn every session's stat-only listing into a content read, not just
+project_path's already-deferred one, breaking the stat-only guarantee
+`sessions` makes for every adapter (Base's class comment on `sessions`) — and
+it cannot be fixed by memoizing the parse across both hooks, either:
+build_session computes started_at_for eagerly at construction and defers only
+project_path through Session's resolver block, so a memo would always be cold
+when started_at runs. The ordering never reverses without a Session/Base
+change, which is out of scope here. Base's stat.birthtime fallback stays in
+effect, nil-on-Linux limitation and all (see rule 3) — that gap is not
+Amp-specific; Claude's started_at has the identical gap from the identical
+fallback. Worth revisiting if a caller needs started_at at all on a filesystem
+without birthtime; nothing today does (Task 10 sorts by updated_at, matching
+Codex's own note on the same trade-off).
+
+URI.parse, not `uri.delete_prefix("file://")`: the naive strip mishandles the
+authority-component form <code>file://localhost/Users/...</code> (it would
+leave a leading "localhost/" in the path), which URI.parse's #path strips
+correctly by design. That fix is only net-positive once its own new failure
+modes are covered, and a partial mirror's JSON is exactly the kind of data
+that can be present-but-wrong at every step, not merely absent (rule 1, one
+level up: the CONTAINER at each step needs checking, not just the leaf):
+    - opaque form "file:relative/x" parses with scheme "file" but
+      #path nil — decode_uri_component(nil) raises NoMethodError.
+    - "file:", "file://", "file://localhost" all parse to path "" —
+      truthy, so left unchecked it becomes an empty-string project
+      instead of the unknown-project nil an empty path actually means.
+    - "file://nas/share" (a real host, e.g. a network share) parses to
+      path "/share" with host "nas" — a location this machine cannot
+      read as a local directory, silently rejected here rather than
+      reported as if it were one.
+    - a trailing slash ("file:///Users/you/app/") survives decoding
+      unchanged and would never equal a caller's expanded path.
+    - an unescaped character (a literal space) makes URI.parse itself
+      raise URI::InvalidURIError — file DATA, not an adapter bug, so
+      that raise is rescued rather than left to propagate and take
+      every agent's listing down with it (rule 2). The rescue is
+      scoped to the URI.parse call alone, not the whole method: Codex
+      and pi both wrap only Time.new the same way, for the same
+      reason — a method-scoped rescue would just as readily swallow a
+      raise from a genuine adapter bug above it. decode_uri_component
+      needs no rescue of its own: it only ever substitutes /%\h\h/, and
+      URI.parse has already rejected any malformed escape by the time
+      its #path reaches that call (verified against %FF%FE, %C3%28,
+      %80 — none raise).
+
+Every JSON level below is unwrapped by hand and type-checked, rather than one
+#dig("env", "initial", "trees", 0, "uri") call: #dig raises TypeError the
+moment an intermediate value is present but not itself diggable (a String
+"env", a top-level Array, "trees" holding a String instead of an Array...),
+which is the same present-but-wrong risk as above, one level higher. Each
+<code>[]</code>/<code>.first</code> below is only called once its receiver has
+already been confirmed the right shape, so none of them can raise on their
+own. uri.is_a?(String) is kept even though URI.parse's own rescue above would
+also catch every non-String value JSON can produce here (Hash, Array, Integer,
+Float, true, false, nil all raise URI::InvalidURIError when handed to
+URI.parse, verified 2026-08-05) — the guard is not load-bearing against those
+specific values today, but it keeps this method's contract with URI.parse
+explicit rather than resting on an undocumented side effect of what that call
+happens to do with the wrong type, and it matches every sibling adapter's
+convention of checking a value's type before use.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+Gated, unlike the warning above. That one is a permanent property of the agent
+and is worth reading before adopting the gem; this one is a "here is what
+breaks, please send this back" report, and the plan's rule for those is that
+they reach only people who can act on them. Same gate pi uses.

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

@@ -0,0 +1,198 @@
+# Class Agent::Sessions::Adapters::Base <a id="class-Agent-Sessions-Adapters-Base"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Includes** | [Agent::Sessions::Adapters::Enumeration](Enumeration.md), [Agent::Sessions::HomeExpansion](../HomeExpansion.md) |
+| **Defined in** | lib/agent/sessions/adapters/base.rb |
+
+Base class for every agent adapter. Subclass this directly, never another
+adapter: the DSL keeps its configuration in singleton instance variables,
+which Ruby does not carry down a second level of inheritance, so a subclass of
+a subclass would silently declare nothing.
+
+An instance memoizes what it resolves. Build a new instance per resolution
+rather than reusing one across changes to the env hash.
+
+What lives here is Layer 1: where a store is, what it declares, and whether
+disk agrees. Turning that store into sessions is Layer 2 and lives in
+Enumeration, included below — the two halves met at 460 lines in one class and
+were split before Layer 3 readers could make it three.
+
+## Constants
+### `FIDELITIES` <a id="constant-FIDELITIES"></a> <a id="FIDELITIES-constant"></a>
+Not documented.
+
+## Attributes
+### `agent_name` [R] <a id="attribute-c-agent_name"></a> <a id="agent_name-class_method"></a>
+Returns the value of attribute agent_name.
+
+### `declared_warnings` [R] <a id="attribute-c-declared_warnings"></a> <a id="declared_warnings-class_method"></a>
+Returns the value of attribute declared_warnings.
+
+### `documented_value` [R] <a id="attribute-c-documented_value"></a> <a id="documented_value-class_method"></a>
+Returns the value of attribute documented_value.
+
+### `label_text` [R] <a id="attribute-c-label_text"></a> <a id="label_text-class_method"></a>
+Returns the value of attribute label_text.
+
+### `verified_on_date` [R] <a id="attribute-c-verified_on_date"></a> <a id="verified_on_date-class_method"></a>
+Returns the value of attribute verified_on_date.
+
+## Public Class Methods
+### `fidelity_value()` <a id="method-c-fidelity_value"></a> <a id="fidelity_value-class_method"></a>
+:unsupported is the honest default for an adapter that has not declared what a
+reader could reconstruct from its format.
+
+### `homedir_config()` <a id="method-c-homedir_config"></a> <a id="homedir_config-class_method"></a>
+Not documented.
+
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+The Layer 3 reader for this agent, or nil while it has none. nil is what makes
+Agent::Sessions.read raise UnsupportedFormat instead of handing back a reader
+that quietly yields nothing.
+
+### `store_configs()` <a id="method-c-store_configs"></a> <a id="store_configs-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `base_dir()` <a id="method-i-base_dir"></a> <a id="base_dir-instance_method"></a>
+Not documented.
+
+### `bytes_for(_path, stat)` <a id="method-i-bytes_for"></a> <a id="bytes_for-instance_method"></a>
+Bytes this session occupies on disk. The transcript alone for a store that
+keeps one file per session; an adapter whose agent writes sidecar files beside
+the transcript overrides this and adds them. Like the two time hooks it takes
+the stat the enumerator already holds, so the common case still costs nothing
+beyond the syscall already made.
+
+An override runs EAGERLY for every session, so it carries build_session's
+constraint: it must not raise on an unreadable path, or one bad sidecar takes
+down the whole listing rather than its own row.
+
+### `encode_project(_dir)` <a id="method-i-encode_project"></a> <a id="encode_project-instance_method"></a>
+nil means this adapter has no directory-name fallback rule. Used only by
+sessions_for_project, and only for a session whose own recorded cwd could not
+be read. When overridden: dir arrives pre-expanded here from
+sessions_for_project (File.expand_path), which is the precondition an override
+may rely on — a direct caller must pass an absolute, expanded path itself, or
+the encoding is nonsense ("app", "~/app", and a trailing slash all encode
+differently from the canonical form real project directories were named from).
+
+### `initialize(env: ENV)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Base] a new instance of Base
+
+### `locate()` <a id="method-i-locate"></a> <a id="locate-instance_method"></a>
+Not documented.
+
+### `project_dir_name(path)` <a id="method-i-project_dir_name"></a> <a id="project_dir_name-instance_method"></a>
+The directory whose name the encoding must match, when sessions_for_project
+falls back to it. Overridable: not every store puts the encoded project
+directly above the session file — cursor_ide nests
+projects/<name>/agent-transcripts/*, where the immediate parent is
+agent-transcripts and matching it would find nothing, silently.
+
+### `project_path_for(_path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+nil means the project is unknown for this session. Adapters override with a
+bounded read of their own metadata; Base cannot guess.
+
+### `project_paths()` <a id="method-i-project_paths"></a> <a id="project_paths-instance_method"></a>
+Distinct recorded project paths, sorted. This is the read-everything direction
+(design doc section 7): the encodings cannot be reversed, so the recorded cwd
+inside each file is the only reliable source. Sessions whose project cannot be
+determined are excluded, not returned as nil.
+
+Sorted rather than left in glob order because a stable order is what makes
+`projects` output diffable and `du --by project` deterministic — and adapters
+answering from a database would otherwise impose their own.
+
+### `retention()` <a id="method-i-retention"></a> <a id="retention-instance_method"></a>
+Not documented.
+
+### `retention_source()` <a id="method-i-retention_source"></a> <a id="retention_source-instance_method"></a>
+Not documented.
+
+### `session_id_from(path)` <a id="method-i-session_id_from"></a> <a id="session_id_from-instance_method"></a>
+--- Layer 2 hooks, overridable per adapter ---
+
+### `sessions()` <a id="method-i-sessions"></a> <a id="sessions-instance_method"></a>
+Lazily enumerates the primary store. Each consumed session costs one stat plus
+filename parsing — never a content read. project_path is the exception and
+pays for itself on first access.
+
+A store the gem has no layout for is refused rather than reported empty:
+Location#enumerable? exists precisely so "nothing here to enumerate" and
+"enumerated, found none" stay distinguishable, and silently returning no
+sessions is this gem's worst failure mode.
+
+### `sessions_for_project(dir)` <a id="method-i-sessions_for_project"></a> <a id="sessions_for_project-instance_method"></a>
+Match by RECORDED cwd, exact, per session (design doc section 7, revised
+2026-08-05 — the third design for this method, kept honest here because the
+next reader deserves to know why it is not "cheap"). The first two designs
+were built and disproved against a real store, not in theory:
+
+    1. Directory-name matching (the original design) assumed a
+       session's parent directory equals encode(its own recorded cwd).
+       A project rename breaks that: the agent keeps writing under the
+       OLD encoded directory, so two directories can hold live sessions
+       for the SAME current cwd, and name-only matching silently
+       dropped the stale one — false negatives, the failure mode this
+       gem treats as worst (decision 11).
+
+    2. One-read-per-directory sampling (the first fix for #1) assumed
+       sessions within a directory share a cwd, to keep the match
+       sublinear. Reading a real renamed project's stale directory
+       disproved that: two of its three sessions had been resumed after
+       the rename and recorded the NEW cwd; the third was never resumed
+       and still recorded the OLD one. Sampling one session and
+       applying its verdict to the whole directory is wrong in BOTH
+       directions on the same store — it invented a false positive
+       here, and a different glob order would just as easily have
+       reproduced #1's false negative for that same directory.
+       Approximate cwd resolution doesn't make the error smaller; it
+       just moves where it lands.
+
+Measured cost of reading every session instead of sampling: 0.17 ms per
+session (68 real Claude sessions, full sweep, 0.012s total) — 0.7s
+extrapolated to a 4,000-session store. That is what the sampling complexity
+was buying, and it is not a trade worth making: the enumerator is already
+lazy, so a caller taking first(n) never pays for sessions it never asked
+about, and even the worst case (every session checked, no match) stays under a
+second on a store two orders of magnitude larger than anything observed.
+
+A session whose own cwd cannot be read (the scan gave up, the file is
+unreadable, the adapter declares no reader) falls back to comparing ITS OWN
+directory's name against the encoding, when the adapter declares one — this is
+the only thing encode_project still buys: it keeps a session with an
+unreadable header from becoming invisible, without resolving an unknown
+project for every other session that happens to share its directory.
+
+### `started_at_for(_path, stat)` <a id="method-i-started_at_for"></a> <a id="started_at_for-instance_method"></a>
+Both time hooks take the stat the enumerator already holds, so a session still
+costs one syscall. path is passed for adapters that answer from a sibling
+metadata file instead.
+
+nil beats a wrong guess when the filesystem cannot answer at all — and it says
+so through ENOSYS/EPERM from statx as often as NotImplementedError.
+
+### `updated_at_for(_path, stat)` <a id="method-i-updated_at_for"></a> <a id="updated_at_for-instance_method"></a>
+Not documented.
+
+### `verify()` <a id="method-i-verify"></a> <a id="verify-instance_method"></a>
+Checks every declared store against disk. The design doc says each adapter
+declares its own checks, and each one does: its store_configs decide what is
+looked for and whether an absence is a failure or drift. Content-level checks
+(first record type, encoding round-trip) need file reads and wait for Layer 3.
+An adapter that needs its own can override this and call super.
+
+The skip gate is the same signal Store#installed? uses: any declared store
+exists. It is deliberately NOT base-dir existence — ~/.cursor is created by
+the Cursor editor with no agent store in it (observed 2026-08-05), and the old
+gate made doctor report FAIL while `where` said "(not installed)". A missing
+store proves nothing on its own (never used? layout moved? the gem cannot
+tell), so :fail is reserved for the one case with evidence: some store exists,
+proving the agent records data here, while a required one is absent — the
+layout-moved signature.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+Not documented.

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

@@ -0,0 +1,63 @@
+# Class Agent::Sessions::Adapters::Claude <a id="class-Agent-Sessions-Adapters-Claude"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/claude.rb |
+
+## Constants
+### `DEFAULT_CLEANUP_PERIOD_DAYS` <a id="constant-DEFAULT_CLEANUP_PERIOD_DAYS"></a> <a id="DEFAULT_CLEANUP_PERIOD_DAYS-constant"></a>
+Not documented.
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `bytes_for(path, stat)` <a id="method-i-bytes_for"></a> <a id="bytes_for-instance_method"></a>
+Claude Code writes a directory beside each transcript, named after the session
+id with the extension dropped: subagents/ holds the transcripts of agents this
+session spawned, tool-results/ holds tool output too large to inline. Those
+bytes are this session's, and until they were counted `du` reported 122.1 MB
+for a store `audit` reported 173.0 MB for — 71% — because audit sums the store
+directory whole while du sums sessions. Two commands, one directory, a 29%
+disagreement.
+
+Measured over 128 real sessions on 2026-08-10: 0.002 ms per session when there
+is no sidecar (one stat, the common case on a fresh install) and 0.080 ms when
+there is. That is under half what project_path's content read costs, and
+unlike project_path this cannot be deferred —bytes is eager, and a
+lazily-corrected byte total would leave `list` printing one number while `du`
+summed another.
+
+### `encode_project(dir)` <a id="method-i-encode_project"></a> <a id="encode_project-instance_method"></a>
+Every non-alphanumeric character becomes "-" (design doc section 7). dir must
+already be absolute and expanded — sessions_for_project guarantees that; a
+direct caller passing "app", "~/app", or a trailing slash gets a nonsense
+encoding (see Base#encode_project). Verified against real project directories
+on 2026-08-05: /Users/dev/.local -> -Users-dev--local
+
+### `project_path_for(path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+cwd is NOT on line 1. Real sessions open with a kebab-case preamble (ai-title,
+agent-name, mode, permission-mode) followed by a variable-length run of
+file-history-snapshot records — that run is what pushes the first cwd-bearing
+record out further on some files, and nothing bounds its length. Observed on
+this machine on 2026-08-05: line 3 (19 files), line 4 (48 files), line 9 (1
+file, a longer snapshot run). limit: 25 is ~2.8x that observed maximum —
+headroom for the variable-length run, not a tight fit to the common case — and
+keeps this a few-KB read even on multi-GB files.
+
+The block guards against a record that carries "cwd" but not usably: null
+shadows a later valid record, and a wrong type (Integer, Hash) would otherwise
+reach project_paths' .uniq.sort and raise there. scan_jsonl_for_key already
+guarantees the key is present once the block accepts, so a plain fetch (no
+default) is safe.
+
+### `retention()` <a id="method-i-retention"></a> <a id="retention-instance_method"></a>
+Not documented.
+
+### `retention_source()` <a id="method-i-retention_source"></a> <a id="retention_source-instance_method"></a>
+Not documented.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+Not documented.

data/doc/Agent/Sessions/Adapters/Codex.md

@@ -0,0 +1,79 @@
+# Class Agent::Sessions::Adapters::Codex <a id="class-Agent-Sessions-Adapters-Codex"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/codex.rb |
+
+## Constants
+### `FILENAME` <a id="constant-FILENAME"></a> <a id="FILENAME-constant"></a>
+rollout-<YYYY-MM-DDTHH-MM-SS>-<uuid>.jsonl (verified 2026-08-05 against 360
+real session files on this machine — every one matched). The timestamp uses
+the local clock and dashes where ISO 8601 has colons. started_at_for's comment
+says what "local" costs elsewhere. The uuid group is pinned to its actual
+shape (8-4-4-4-12 hex), not (.+): greedy against .jsonlz, (.+) would swallow a
+sync tool's or backup's " (conflicted copy)" suffix into what looks like a
+canonical id rather than falling back to the basename, where such a copy is at
+least visibly non-canonical.
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `project_path_for(path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+Line 1 is session_meta; the cwd lives in its payload (design doc section 6 and
+8.2, verified 2026-08-05 — 360/360 real files carry a usable
+session_meta/payload/cwd on line 1). limit: 3 is slack against that guarantee,
+not a fit to any observed multi-line case: it tolerates a truncated or blank
+first line without paying for an unbounded scan. "3" counts iterations of
+File.foreach(path, "n", MAX_LINE_BYTES), not lines: a >1MB record is chunked
+and each chunk is one iteration, so this is really 3MB of read headroom, not
+"3 records." A future adapter copying this pattern with limit: 1 would lose
+that tolerance entirely.
+
+The predicate requires more than scan_jsonl_for_key's key-presence check can:
+real sessions on this machine also carry a "payload" key on later,
+non-session_meta records (turn_context observed 2026-08-05) whose payload
+itself carries "cwd" — a presence-only scan would stop at whichever comes
+first, right only by coincidence. Requiring type == "session_meta" pins the
+read to the one documented source of truth (design doc 8.2), and requiring a
+Hash payload with a String cwd stops a malformed record (payload not a Hash,
+or cwd not a String) from permanently shadowing a later, usable session_meta
+or reaching project_paths' .uniq.sort with the wrong type.
+
+### `session_id_from(path)` <a id="method-i-session_id_from"></a> <a id="session_id_from-instance_method"></a>
+Not documented.
+
+### `sessions()` <a id="method-i-sessions"></a> <a id="sessions-instance_method"></a>
+Codex writes rollout files to two stores, and Base enumerates only the primary
+one. An archived session is still a session — a real one was found outside the
+sessions/ glob on 2026-08-10 — and a session the gem does not report is the
+silent under-reporting this design treats as its worst failure mode. Every
+filename hook below applies unchanged: the archived files carry the same
+rollout-<timestamp>-<uuid>.jsonl name.
+
+`super` first, so the guard it raises when the primary store has no known
+layout still fires, and so live sessions come out before archived ones.
+Chained rather than concatenated to keep the result lazy: a caller taking
+first(n) must not stat an archived file it never asked about.
+
+### `started_at_for(path, stat)` <a id="method-i-started_at_for"></a> <a id="started_at_for-instance_method"></a>
+The digit groups accept 00-99 each, which Time.new does not: month 13, minute
+60, and similar out-of-range values raise ArgumentError rather than being
+normalized. That is file DATA, not an adapter bug, so it must not cross the
+line build_session draws between the two (a raising hook is meant to surface
+as a programming error) — one such filename among many good ones would
+otherwise take sessions, project_paths, and sessions_for_project down to zero
+for every agent, not just Codex.
+
+Local, not UTC: session_meta's own "timestamp" field is UTC and agrees with
+this to within 1s across all 360 real files here, but a machine whose TZ
+changed, or a store copied from another machine, would make this off by the
+offset delta while Claude's birthtime-based started_at stays an absolute
+instant. Harmless today because Task 10 sorts sessions by updated_at, not
+started_at. The rescue wraps Time.new alone rather than the whole method. A
+method-scoped rescue would also swallow an ArgumentError from a future
+signature change — the commonest Ruby programming error — and silently return
+birthtime for every Codex session: a plausible-looking wrong started_at with
+no signal, which is worse than a crash.

data/doc/Agent/Sessions/Adapters/Copilot.md

@@ -0,0 +1,38 @@
+# Class Agent::Sessions::Adapters::Copilot <a id="class-Agent-Sessions-Adapters-Copilot"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/copilot.rb |
+
+GitHub Copilot CLI. Verified against a real store on this machine
+(2026-08-24): ~/.copilot/session-store.db, schema_version 3, one session.
+
+This store has MOVED since tokentelemetry's parser was written against it:
+that reads ~/.copilot/session-state/<id>/events.jsonl, and no such file exists
+here. The session-state/<id>/ directory does still exist as a companion
+(workspace.yaml, checkpoints/, files/, research/), but the session record
+itself is now a row in SQLite. An adapter following the older spec would
+report nothing on a current install — the failure this gem's `verified_on`
+dates exist to make visible.
+
+## Constants
+### `SESSION_COLUMNS` <a id="constant-SESSION_COLUMNS"></a> <a id="SESSION_COLUMNS-constant"></a>
+created_at/updated_at are ISO 8601 strings here, not the epoch milliseconds
+opencode and Cursor use — verified against a real row
+("2026-05-26T04:36:01.288Z").
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `project_paths()` <a id="method-i-project_paths"></a> <a id="project_paths-instance_method"></a>
+Not documented.
+
+### `sessions()` <a id="method-i-sessions"></a> <a id="sessions-instance_method"></a>
+Not documented.
+
+### `sessions_for_project(dir)` <a id="method-i-sessions_for_project"></a> <a id="sessions_for_project-instance_method"></a>
+cwd is a real column holding a real absolute path, so filtering is a WHERE
+clause rather than a read-and-compare loop.