agent_sessions 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9c351be12ac0d3201532322115c21d9277bb54e7d1d7d7b6e6e2c373ba793a9
+  data.tar.gz: 1ecb97c0d890c97542dafea00b6b8bd39b02f7427c7ad5c8627d69f2886ff1f7
+SHA512:
+  metadata.gz: f963abdeb2b16d53fc32bd098abeabc4f461bda5d229b960322b3513f06719136f933e77a6a2a2428a9b655d0a9e01946c16eb8de606b7e5f8acae2517d28f1c
+  data.tar.gz: 1f82162c07217a3175459d54301d5cb5417c18a35a42a68cda9efeaddba7276c84b666cbb6265c70089cf9a65fef55ea17de877699c4bbc26ba34424d9ee8371

data/CHANGELOG.md

@@ -0,0 +1,61 @@
+## 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
+- Base-dir resolution now delegates to `agent_homedir` and runs through a per-instance resolver instead of this gem's own expansion rules
+- Relative base-dir environment overrides now join `HOME` instead of the current working directory, `~user` no longer stays literal, and whitespace-only overrides fall back to adapter defaults
+- `cursor_ide` now honors `XDG_CONFIG_HOME` on Linux and `APPDATA` on Windows
+- Blank or non-absolute XDG overrides now fall back to defaults for Amp and opencode, and `OPENCODE_DATA_DIR` now appears in `env_overrides`
+- Adapters whose base-dir rules do not define the current host OS now raise instead of silently assuming Linux
+
+- `Usage` (`input`, `output`, `cache_read`, `cache_creation`, `reasoning`, `cost`): token counts normalized to disjoint buckets across agents. `nil` means "this format does not record that dimension", never zero; `cost` is only ever agent-reported, never derived from a pricing table
+- `Message#usage` and `Message#model`, populated where the format puts them on the message (Claude); `reader.usage` returns session totals or nil
+- Claude usage dedups by `message.id` before summing: one API response streams into one record per content block repeating identical usage (94 of 124 message ids in one real transcript), so a naive sum roughly doubles what was billed
+- Codex usage reads the last `token_count` record's running total and subtracts `cached_input_tokens` from `input_tokens` (Codex counts them inclusively; Claude disjointly — verified against real stores on both sides, 2026-08-24)
+- Claude reader recognizes `atis-latch` and `bridge-session` (session state postdating the 2026-08-12 corpus, observed live 2026-08-24) instead of warning about them
+- opencode reader — the first over SQLite: 13,804 messages from 365 real sessions with zero warnings, and its summed usage equals the store's own per-session rollup columns on all 365. One `tool` part becomes a `:tool_use` and a `:tool_result`; a `subtask` spawn becomes a `:tool_use` named after its agent; step markers, patches and file attachments stay in `raw`. Needs the optional `sqlite3` gem
+- pi reader, explicitly provisional: written against tokentelemetry's working parser of the format, since no pi session files exist on the machine it was written on — every mapping degrades to `:unknown` + warning rather than crashing if real pi output disagrees
+- **Four new agents: Gemini CLI, GitHub Copilot CLI, Qwen Code and Grok Build**, taking the gem from 7 adapters to 11
+- Gemini CLI adapter + reader, verified against a real store (12 sessions, 121 records): `~/.gemini/tmp/<projectHash>/chats/session-*.json`, one JSON document per chat. Its `cached` count sits INSIDE `input` — established arithmetically across all 97 real token records, where `total` equals `input + output + thoughts + tool` and never adds `cached` — so the reader subtracts it, as it does for Codex. `thoughts` become `:thinking` parts carrying subject and description; `info` records are opt-in events. Filenames are UTC, unlike Codex's and pi's local-clock ones, and their trailing hex is NOT a session id (two real files share one), so the id is the whole basename
+- GitHub Copilot CLI adapter + reader, verified against a real store: **the format has moved** to `~/.copilot/session-store.db` (SQLite, schema_version 3) from the `session-state/<id>/events.jsonl` layout the reference tooling still reads — an adapter following the older spec reports nothing on a current install. One `turns` row is a whole exchange and becomes two messages. No token or cost column exists anywhere in that schema, and the adapter says so rather than letting nil read as zero
+- Qwen Code adapter + reader, and Grok Build adapter + reader — both PROVISIONAL and declared as such at runtime: neither store exists on the machine they were written on, so they follow tokentelemetry's parsers rather than observation, and every mapping degrades to `:unknown` + a warning rather than crashing if real output disagrees
+- Grok's session is a directory, not a file: Layer 2 enumerates `summary.json`, the reader streams `chat_history.jsonl` beside it, and billed usage comes from a third file — `~/.grok/logs/unified.jsonl`, shared by every session and keyed by session id. `Readers::Base#record_path` is a new hook for exactly that split
+- **Cursor IDE is repointed at the store it actually uses** — `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`, table `cursorDiskKV`, keys `composerData:<uuid>` — confirmed by opening it (6 real sessions on the machine this was written on, where the 0.2 declaration `~/.cursor/projects/*/agent-transcripts/*` did not exist at all). Fidelity rises from `:unsupported` to `:metadata`; content is still unread, because every record seen carried an empty `conversation`, and the adapter says so rather than guessing the turn format
+- opencode store discovery now tries `OPENCODE_DATA_DIR`, `XDG_DATA_HOME`, `~/.local/share/opencode`, macOS `~/Library/Application Support/opencode` and the Windows app-data dirs, and matches `opencode*.db` rather than the plain name — a macOS user, or one on a release channel that renames the database, previously got an empty result from an agent they had used. A candidate must actually hold a database to win, so an empty directory cannot shadow a real store; two databases holding the same session report it once
+- `base_dir default:` accepts a Hash keyed by platform (`:macos`, `:linux`, `:windows`) for IDE-hosted agents whose store genuinely moves between operating systems; a Hash missing this machine's platform raises rather than falling back to another platform's path
+- `AgentSessions::Sqlite` extracts the one safe way this gem opens a SQLite store (read-only URI, escaped path, 5s busy timeout), now shared by the opencode adapter and reader
+- Layer 3 begins: `AgentSessions.read(session)` returns a streaming reader — `each_message`, `messages`, `compactions`, `warnings`, `fidelity`, `partial?`
+- `Message` (`role`, `at`, `parts`, `text`, `raw`) and `Part` (`:text`, `:thinking`, `:tool_use`, `:tool_result`, `:image`, `:unknown`); `raw` is never dropped
+- Codex reader, the first: reads 73,946 messages from 415 real sessions with zero warnings and zero exceptions, at 4.5 ms per session
+- `compacted` records become boundaries rather than messages — replaying their `replacement_history` would report the same turns twice
+- `event_msg` records (38% of the corpus) are excluded unless `include_events: true`
+- Readers stream at an 8 MB per-record cap, not Layer 2's 1 MB: 14 real records exceed 1 MB and the largest is 2.41 MB, so the smaller cap would have dropped real messages. A record past the cap is reported, never silently skipped
+- `AgentSessions.read` raises `UnsupportedFormat` for an agent with no reader, so "cannot read this format" never looks like "this session is empty"
+- Claude reader: 18,111 messages from 142 real transcripts, zero exceptions, 5.6 ms per session
+- Claude's spilled tool output is resolved from the sidecar file, so a `:tool_result` carries content instead of a pointer — bounded to the session's own sidecar tree, because the path is read out of tool output and must never become a file-read primitive. `resolve_spills: false` turns it off
+- `reader.subagents` returns readers for the transcripts a session spawned, never merged into its own messages — 124 of them on the machine this was written against
+- Claude's nine session-state record types and its `system`/`attachment` context records are separated from turns; the latter two arrive with `include_events: true`
+- Amp reader: `partial?` is true there, since the server holds the canonical copy. A thread is one JSON document rather than JSONL, so it is read whole under a 32 MB cap — the bound the gem's one unbounded read never had
+- `reader.tree` returns the conversation as roots and continuations for an agent that records parent links, with `reader.branching?` to ask first. Claude branches at 374 points across 83 of 151 real transcripts — a turn edited and re-run leaves two children under one parent, which reading in file order shows as two histories interleaved
+- Readers that record no parent links raise `UnsupportedFormat` from `tree` rather than returning an empty list, so "this format does not record that" never reads as "this session has none"
+- Agents other than Codex, Claude and Amp have no reader yet; `Session#fidelity` already says what each one will support
+
+## 0.2.0 (2026-08-10)
+
+First public release. 0.1.0 was never tagged or published, so its work is
+folded into this entry rather than shipping a changelog with two consecutive
+"(unreleased)" headings under two different version numbers.
+
+- Layer 1: resolve session store paths for Claude Code, Codex CLI, Cursor CLI, Cursor IDE, Amp CLI, opencode, and pi
+- Layer 2: `Session`, lazy `sessions`, `for_project`, `projects` across all seven adapters
+- `AgentSessions.sessions(agent, since:)`, `.for_project(dir, agents:)`, `.projects(agent)`
+- `Session` is a plain, lazily-resolved value object: `project_path` is computed on first access and memoized
+- `Location#files` replaces `matches`, aware of single-file layers (`single_file`, `enumerable?`)
+- opencode session enumeration via a deferred read-only SQLite query, behind an **optional** `sqlite3` gem — the gemspec stays runtime-dependency-free
+- CLI: `where`, `doctor`, `audit`, `list` (`--agent`, `--project`, `--since`), and `du` (`--by agent|project`), all with `--json` output
+- Amp's `secrets.json` is now optional: a missing file reports drift, not failure
+- `verify`'s skip gate now keys on store existence, not base-dir existence
+- `doctor` takes its agent positionally, matching `where`
+- `list`/`du` now exit non-zero when any agent's store had to be skipped, instead of exiting 0 with only a stderr notice
+- Codex declares `archived_sessions/` (flat, optional) and enumerates it: an archived rollout file is a session, and `sessions`, `list`, `du`, and `audit` all report it now
+- Claude's `Session#bytes` counts the sidecar directory each transcript gets — `<id>/subagents/`, `<id>/tool-results/` — so `du` and `audit` no longer disagree by 29% about the same store
+- `Adapters::Base#bytes_for(path, stat)` is a new overridable hook, defaulting to the transcript's own size

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Lucian Ghinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# agent_sessions
+
+Where do AI coding agents store their session logs? This gem knows.
+
+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`.
+
+Most of these eleven layouts are undocumented, or only partly documented, by their vendors and can move in any release — Copilot CLI's moved from JSONL files to SQLite, and Cursor IDE's was found in a different directory than the one previously believed. Each adapter carries the date its claims were last checked against a real install, and `agent-sessions doctor` reports both that date and what disk says now.
+
+Two adapters, Qwen Code and Grok Build, are marked provisional: no such store existed on the machine they were written against, so they follow another tool's working parser of the same format rather than direct observation. They say so at runtime.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "agent_sessions"
+```
+
+## Quick start
+
+```sh
+agent-sessions where
+agent-sessions doctor
+agent-sessions audit
+agent-sessions list --since 30d
+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).
+
+## Ruby API
+
+```ruby
+require "agent_sessions" # compatibility shim for Agent::Sessions
+
+store = Agent::Sessions.locate(:codex)
+store.effective.path   # => "/Users/you/.codex/sessions"
+store.format           # => :jsonl
+store.documented?      # => false
+store.retention        # => nil ("grows forever")
+```
+
+List agents:
+
+```ruby
+Agent::Sessions.all        # every supported agent
+Agent::Sessions.installed  # only agents present on this machine
+```
+
+Verify claims against disk:
+
+```ruby
+Agent::Sessions.verify(:codex)
+# => [#<Check status: :pass, claim: "store sessions exists", ...>]
+```
+
+Resolve for an environment that is not your own:
+
+```ruby
+Agent::Sessions.locate(:codex, env: { "CODEX_HOME" => "/tmp/x" })
+```
+
+Enumerate sessions and map them to projects:
+
+```ruby
+Agent::Sessions.sessions(:claude).first(5)      # lazy; stats files, never parses them
+Agent::Sessions.for_project(Dir.pwd)            # every agent's sessions for one project
+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.
+
+Read a session's messages and token usage (Claude, Codex, Amp, opencode, pi, Gemini CLI, Copilot CLI, Qwen and Grok):
+
+```ruby
+reader = Agent::Sessions.read(session)
+reader.each_message { |m| puts "#{m.role}: #{m.text}" }  # streams; raw is never dropped
+reader.usage                                  # session token totals, or nil if not recorded
+reader.usage&.input                           # disjoint buckets: input, output, cache_read,
+                                              #   cache_creation, reasoning, cost
+```
+
+`Usage` is normalized across agents: `input` never includes cached tokens (Codex counts them inclusively; the reader subtracts), and a `nil` dimension means the format does not record it — never zero. `cost` is only ever what the agent itself reported; this gem ships no pricing table.
+
+`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.
+
+## 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.5: `export` with secret redaction
+
+## History
+
+View the [changelog](CHANGELOG.md).

data/exe/agent-sessions

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "agent/sessions"
+
+exit Agent::Sessions::CLI.new(ARGV).run

data/lib/agent/sessions/adapters/amp.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          class Amp < Base
+            agent :amp
+            label "Amp CLI"
+            documented :partly
+            verified_on "2026-07-21"
+            fidelity :messages
+
+            homedir :amp, report_env: ["XDG_DATA_HOME"]
+
+            store :threads, dir: "threads", glob: "T-*.json", format: :json
+            # Design doc 8.4: Amp's local layout drifts between machines, so threads/ is the
+            # one path stable enough that its absence is a real failure. secrets.json is
+            # declared but optional: it is a credentials file rather than a transcript store,
+            # and it does not exist until `amp login` runs, so a missing one says the user has
+            # not authenticated, not that this adapter's claim about the layout is wrong.
+            # It stays a layer so `audit` can still report a plaintext token file inside a
+            # sync folder, which is the check that actually matters for it.
+            store :secrets, path: "secrets.json", format: :json, optional: true
+
+            def self.reader_class = Readers::Amp
+
+            warning "the server holds the canonical copy; local threads may be a partial mirror"
+
+            # 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.
+            def warnings
+              list = super
+              if primary_layer.exists?
+                list << "a thread with more than one workspace tree only has its first tree's path " \
+                        "recognized as a project; `projects` and `sessions_for_project` will not see " \
+                        "any other root — if a project you know has Amp sessions is missing, please " \
+                        "open an issue with that thread's env.initial.trees array"
+              end
+              list
+            end
+
+            # 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[0] 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 `file://localhost/Users/...`
+            # (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 `[]`/`.first` 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.
+            def project_path_for(path)
+              data = read_json(path)
+              return nil unless data.is_a?(Hash)
+
+              env = data["env"]
+              return nil unless env.is_a?(Hash)
+
+              initial = env["initial"]
+              return nil unless initial.is_a?(Hash)
+
+              trees = initial["trees"]
+              return nil unless trees.is_a?(Array)
+
+              tree = trees.first
+              return nil unless tree.is_a?(Hash)
+
+              uri = tree["uri"]
+              return nil unless uri.is_a?(String)
+
+              parsed = begin
+                URI.parse(uri)
+              rescue URI::InvalidURIError
+                return nil
+              end
+              return nil unless parsed.scheme == "file"
+              return nil unless parsed.host.to_s.empty?
+
+              raw_path = parsed.path
+              return nil if raw_path.nil? || raw_path.empty?
+
+              decoded = URI.decode_uri_component(raw_path)
+              # Strips a run of trailing separators, not just one: "/app//" would
+              # otherwise land in project_paths beside "/app" and be missed by
+              # sessions_for_project — the same false negative one slash further out.
+              # The lookbehind keeps a bare root "/" intact.
+              decoded.sub(%r{(?<=.)/+\z}, "")
+            end
+          end
+        end
+  end
+end

data/lib/agent/sessions/adapters/base.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          # 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.
+          class Base
+            include HomeExpansion
+            include Enumeration
+
+            FIDELITIES = %i[full messages metadata unsupported].freeze
+
+            class << self
+              attr_reader :agent_name, :label_text, :documented_value, :verified_on_date, :declared_warnings
+
+              # :unsupported is the honest default for an adapter that has not declared
+              # what a reader could reconstruct from its format.
+              def fidelity_value = @fidelity_value || :unsupported
+
+              def homedir_config = @homedir_config || raise(Error, "#{inspect} declares no homedir")
+
+              def store_configs
+                @store_configs || raise(Error, "#{inspect} declares no store")
+              end
+
+              # 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.
+              def reader_class = nil
+
+              private
+
+              def agent(name) = @agent_name = name
+              def label(text) = @label_text = text
+              def documented(value) = @documented_value = value
+              def verified_on(date) = @verified_on_date = Date.parse(date)
+
+              def fidelity(value)
+                unless FIDELITIES.include?(value)
+                  raise ArgumentError, "fidelity #{value.inspect} must be one of #{FIDELITIES.join(", ")}"
+                end
+
+                @fidelity_value = value
+              end
+
+              def homedir(name, join: nil, report_env: [], entry: nil)
+                @homedir_config = { name:, join:, report_env:, entry: }
+              end
+
+              def store(kind, format:, dir: nil, path: nil, glob: nil, env: nil, optional: false)
+                raise ArgumentError, "store #{kind.inspect} needs exactly one of dir: or path:" if [dir, path].compact.size != 1
+
+                @store_configs ||= []
+                @store_configs << {
+                  kind: kind, format: format, dir: dir, path: path,
+                  glob: glob, env: env, optional: optional
+                }
+              end
+
+              def warning(message)
+                @declared_warnings ||= []
+                @declared_warnings << message
+              end
+            end
+
+            def initialize(env: ENV)
+              @env = env
+            end
+
+            def locate
+              Store.new(
+                agent: self.class.agent_name,
+                label: self.class.label_text,
+                documented: self.class.documented_value,
+                verified_on: self.class.verified_on_date,
+                effective: layers.first,
+                layers: layers,
+                env_overrides: env_overrides,
+                retention: retention,
+                retention_source: retention_source,
+                warnings: warnings
+              )
+            end
+
+            # 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.
+            def verify
+              unless layers.any?(&:exists?)
+                detail = if Dir.exist?(base_dir)
+                           "#{base_dir} exists but holds none of the declared stores"
+                         else
+                           "#{base_dir} does not exist"
+                         end
+                return [check(:skip, "agent is installed", detail)]
+              end
+
+              self.class.store_configs.map do |config|
+                location = resolve(config)
+                claim = "store #{config[:kind]} exists"
+                if location.exists?
+                  check(:pass, claim, detail_for(location))
+                elsif config[:optional]
+                  check(:drift, claim, "#{location.path} not found (optional; undocumented layouts drift)")
+                else
+                  check(:fail, claim, "#{location.path} not found")
+                end
+              end
+            end
+
+            def base_dir
+              @base_dir ||= begin
+                config = self.class.homedir_config
+                root = resolver.home(config[:name]).to_s
+                config[:join] ? File.join(root, config[:join]) : root
+              end
+            end
+
+            def retention = nil
+            def retention_source = :none
+
+            def warnings
+              (self.class.declared_warnings || []).dup
+            end
+
+            private
+
+            def resolver
+              @resolver ||= begin
+                config = self.class.homedir_config
+                options = { env: @env.to_h, home: home }
+                options[:entries] = { config[:name] => injected_entry(config) } if config[:entry]
+                Agent::Homedir::Resolver.new(**options)
+              end
+            end
+
+            def injected_entry(config)
+              {
+                label: self.class.label_text || config[:name].to_s,
+                env: nil,
+                verified_on: nil
+              }.merge(config[:entry])
+            end
+
+            def layers
+              @layers ||= self.class.store_configs.map { |config| resolve(config) }
+            end
+
+            # The store sessions live in. Adapters declare it first, by convention.
+            def primary_layer = layers.first
+
+            def layer(kind)
+              layers.find { |candidate| candidate.kind == kind }
+            end
+
+            # single_file is a property of the declaration, not of the resolved path: a
+            # store-level env override replaces where the layer lives without changing
+            # whether it is one file or a directory.
+            def resolve(config)
+              override = presence(config[:env] && @env[config[:env]])
+              root = override ? expand(override) : File.join(base_dir, config[:dir] || config[:path])
+              Location.new(
+                kind: config[:kind], path: root, format: config[:format],
+                glob: config[:glob], single_file: !config[:path].nil?
+              )
+            end
+
+            def env_overrides
+              config = self.class.homedir_config
+              names = [resolver[config[:name]].env_override, *config[:report_env], *self.class.store_configs.map { |c| c[:env] }]
+              names.compact.uniq.map { |name| EnvOverride.new(name: name, value: presence(@env[name])) }
+            end
+
+            def presence(value)
+              value.to_s.strip.empty? ? nil : value
+            end
+
+            # Location#files escapes its own path for the reason its comment gives —
+            # a resolved path may legitimately contain glob metacharacters, and
+            # unescaped they are read as syntax and silently match nothing. An
+            # adapter globbing a path it was handed needs the same protection.
+            def escape_glob(path)
+              path.gsub(/[\\{}\[\]*?]/) { |char| "\\#{char}" }
+            end
+
+            def env_active?(name)
+              !presence(@env[name]).nil?
+            end
+
+            def check(status, claim, detail)
+              Check.new(agent: self.class.agent_name, status: status, claim: claim, detail: detail)
+            end
+
+            # A single file's own path is the whole detail; counting it "(1 file)" adds noise.
+            def detail_for(location)
+              return location.path unless location.glob
+
+              count = location.files.size
+              "#{location.path} (#{count} file#{"s" unless count == 1})"
+            end
+
+            # SystemCallError, not the four Errno constants this used to list: those
+            # four were the failures observed, not the exhaustive set that can
+            # happen. Task 7 (Cursor) made this reachable from a hook that runs
+            # EAGERLY for every session (started_at_for/updated_at_for read a
+            # sibling meta.json to answer, not lazily like project_path), so a
+            # single unreadable sibling file now has the blast radius of an
+            # unrescued raise: it takes the WHOLE listing down, not just its own
+            # session — Enumerator::Lazy#filter_map does not isolate one failing
+            # iteration. Two errnos found this way, both real, neither in the old
+            # list: ELOOP (a symlink loop — Location#files already rescues this on
+            # the glob side, so the codebase had already judged it reachable, and
+            # this method's own test reproduces it directly against a real
+            # symlink-loop meta.json) and EPERM (macOS TCC denies a protected path
+            # with EPERM, not EACCES — reported and reproduced during code review
+            # by reading a TCC-protected path directly; not independently
+            # re-verified here, but Base#started_at_for already rescues
+            # SystemCallError and its own comment names EPERM, so this method was
+            # simply behind its sibling, not making a different judgment call).
+            # This gets more likely, not less, once cursor_ide is repointed at
+            # ~/Library/Application Support/… in a future release — that path is
+            # TCC territory on macOS.
+            #
+            # What this still does NOT catch: a FIFO (named pipe) named meta.json
+            # blocks File.read forever rather than raising anything — same class of
+            # problem (a store directory containing something other than a plain
+            # file), no cheap fix, and out of scope here.
+            def read_json(path)
+              JSON.parse(File.read(path))
+            rescue SystemCallError, JSON::ParserError
+              {}
+            end
+
+          end
+        end
+  end
+end