agent_sessions 0.3.0

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          # Cursor's IDE agent (Composer). Repointed 2026-08-24 at the store the
+          # 0.2 adapter's own warning named as the real one, now that it has been
+          # opened rather than inferred: ~/Library/Application Support/Cursor/User/
+          # globalStorage/state.vscdb, table cursorDiskKV, keys composerData:<uuid>
+          # — 6 real rows on the machine this was written on. The 0.2 declaration
+          # (~/.cursor/projects/*/agent-transcripts/*) does not exist there at all,
+          # so this adapter reported nothing for an agent that had sessions.
+          #
+          # What is verified: the file, the table, the key prefix, and the record's
+          # own composerId/createdAt. What is NOT: anything about the conversation
+          # itself — all six records on this machine carry "conversation": [], so
+          # the shape of a turn has never been seen here. fidelity stays :metadata
+          # and no reader exists, which is the honest report: this adapter can say
+          # a session happened and when, and must not pretend to say what was said.
+          class CursorIde < Base
+            agent :cursor_ide
+            label "Cursor IDE"
+            documented false
+            verified_on "2026-08-24"
+            fidelity :metadata
+
+            homedir :cursor_ide, join: "User/globalStorage"
+
+            store :database, path: "state.vscdb", format: :sqlite
+
+            warning "the IDE composer store does not sync with the CLI chat store"
+            warning "session content is not read: every composerData record seen carried an " \
+                    "empty conversation, so the turn format remains unverified"
+
+            KEY_PREFIX = "composerData:"
+
+            # Rows, not files, so Base's glob enumeration is replaced the way
+            # opencode's is — including the existence check FIRST, so a machine
+            # without Cursor never needs the sqlite3 gem at all.
+            #
+            # value is parsed for createdAt alone. It is the whole composer document
+            # (context, capabilities, code blocks), which is why `bytes` stays nil:
+            # a row in a shared database has no file size of its own, and the
+            # database's size belongs to all 7 rows together.
+            def sessions
+              db_path = primary_layer.path
+              return [].lazy unless File.exist?(db_path)
+
+              Enumerator.new do |yielder|
+                each_composer_row(db_path) do |key, value|
+                  yielder << build_row_session(db_path, key, value)
+                end
+              end.lazy
+            end
+
+            # Cursor's composer records do not name a project. context.fileSelections
+            # holds paths of files ATTACHED to a turn — on this machine, a settings
+            # file from an unrelated directory — and a workspace root inferred from
+            # one attachment would be a guess dressed as a fact. nil is the honest
+            # answer, and `projects` reporting nothing for this agent is correct
+            # rather than empty-looking.
+            def project_path_for(_path) = nil
+
+            def project_paths = []
+
+            def sessions_for_project(_dir) = [].lazy
+
+            private
+
+            def build_row_session(db_path, key, value)
+              created = parse_created_at(value)
+              Session.new(
+                agent: self.class.agent_name, id: key.delete_prefix(KEY_PREFIX), path: db_path,
+                project_path: nil, started_at: created,
+                updated_at: created || db_mtime(db_path), bytes: nil,
+                format: primary_layer.format, fidelity: self.class.fidelity_value
+              )
+            end
+
+            # createdAt is epoch milliseconds (1776161422165 in real rows). The
+            # guards are opencode's, for the identical failures: a non-Numeric value
+            # is nil rather than a wrong time, and a huge-but-real Integer that
+            # overflows to Infinity once divided must never reach Time.at, which
+            # raises FloatDomainError and would take the whole listing down.
+            def parse_created_at(value)
+              millis = read_json_value(value)["createdAt"]
+              return nil unless millis.is_a?(Numeric)
+
+              seconds = millis / 1000.0
+              Time.at(seconds) if seconds.finite?
+            end
+
+            def read_json_value(value)
+              parsed = JSON.parse(value.to_s)
+              parsed.is_a?(Hash) ? parsed : {}
+            rescue JSON::ParserError, TypeError
+              {}
+            end
+
+            # updated_at may never be nil (the cross-adapter invariant `since` and
+            # every sort rely on), and a composer record carries no updated
+            # timestamp at all — only createdAt. The database file's own mtime is
+            # not this session's time, but it is a true upper bound on when anything
+            # in the store last changed, and it is reached only when createdAt is
+            # missing or malformed.
+            def db_mtime(db_path)
+              @db_mtime ||= begin
+                File.mtime(db_path)
+              rescue SystemCallError
+                Time.now
+              end
+            end
+
+            def each_composer_row(db_path, &block)
+              require_sqlite!
+              db = nil
+              begin
+                db = Sqlite.open_readonly(db_path)
+                db.execute("SELECT key, value FROM cursorDiskKV WHERE key LIKE ?", ["#{KEY_PREFIX}%"], &block)
+              rescue SQLite3::Exception => e
+                raise UnreadableStore, "#{db_path}: #{e.message}"
+              ensure
+                db&.close
+              end
+            end
+
+            def require_sqlite!
+              require "sqlite3"
+            rescue LoadError
+              raise MissingDependency,
+                    "Cursor IDE sessions live in state.vscdb (SQLite); add the sqlite3 gem to enumerate them"
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          # Layer 2: turning a resolved store into sessions. Split out of Base once it
+          # held three concerns at 460 lines, and before Layer 3 readers add a fourth.
+          #
+          # Mixed into Base rather than included per adapter, so every adapter keeps
+          # inheriting all of this and overriding the hooks it needs — the extraction
+          # is a move, not a change in how an adapter is written.
+          #
+          # What this half needs from Layer 1 is deliberately small, and worth keeping
+          # small: `primary_layer` (the store to enumerate and the format to stamp on
+          # each session) and the class-level DSL readers `agent_name` and
+          # `fidelity_value`. Nothing here resolves a path, reads an env override, or
+          # touches @env. A method that needs to do any of those belongs in Base.
+          module Enumeration
+            # Caps how many bytes one iteration of a JSONL scan may pull into memory.
+            # "One line" is not a bounded quantity on disk: a record carrying a pasted
+            # file or a base64 image is routinely tens of MB, and a truncated file may
+            # hold no newline at all. An over-long line arrives as chunks of this size,
+            # which fail to parse and are skipped, so the scan gives up rather than
+            # reading a 2.6 GB file into a single String.
+            MAX_LINE_BYTES = 1_000_000
+
+            # 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.
+            def sessions
+              unless primary_layer.enumerable?
+                raise Error, "#{self.class.agent_name} store #{primary_layer.kind} at " \
+                             "#{primary_layer.path} has no known layout to enumerate"
+              end
+
+              enumerate(primary_layer.files)
+            end
+
+            # 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.
+            def sessions_for_project(dir)
+              dir = File.expand_path(dir)
+              encoded = encode_project(dir)
+              sessions.select do |session|
+                # expand_path does not resolve symlinks, so a cwd recorded as
+                # /private/tmp/x will not match a caller's /tmp/x on macOS.
+                # Deliberate: realpath would cost a stat per comparison to fix a
+                # rare mismatch.
+                cwd = session.project_path
+                next cwd == dir unless cwd.nil?
+
+                encoded && project_dir_name(session.path) == encoded
+              end
+            end
+
+            # 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.
+            def project_paths
+              sessions.filter_map(&:project_path).uniq.force.sort
+            end
+
+            # --- Layer 2 hooks, overridable per adapter ---
+
+            def session_id_from(path)
+              File.basename(path, ".*")
+            end
+
+            # 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).
+            def encode_project(_dir) = nil
+
+            # 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.
+            def project_dir_name(path) = File.basename(File.dirname(path))
+
+            # nil means the project is unknown for this session. Adapters override
+            # with a bounded read of their own metadata; Base cannot guess.
+            def project_path_for(_path) = nil
+
+            # 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.
+            def started_at_for(_path, stat)
+              stat.birthtime
+            rescue NotImplementedError, SystemCallError
+              nil
+            end
+
+            def updated_at_for(_path, stat) = stat.mtime
+
+            # 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.
+            def bytes_for(_path, stat) = stat.size
+
+            private
+
+            # Turns paths into sessions, lazily. Extracted so an adapter whose agent
+            # writes sessions to more than one store can enumerate the others without
+            # copying `sessions`' guard clause — see Codex, which chains its archived
+            # store onto this. The glob behind `paths` has already run; what stays
+            # lazy is the stat and the hooks, which is where the per-session cost is.
+            def enumerate(paths)
+              paths.lazy.filter_map { |path| build_session(path) }
+            end
+
+            # nil drops the session from the enumeration. A file that vanished between
+            # the glob and its stat is one fewer session, not an error: enumeration is
+            # lazy, so that window spans the whole listing, and agents rotate and
+            # compact these logs while a caller is still reading them.
+            #
+            # The rescue covers the stat and nothing else. Wrapping the hooks too would
+            # mean an adapter whose started_at_for raised EACCES silently returned zero
+            # sessions — a misdeclared adapter erasing a listing rather than failing.
+            # A hook that raises is a programming error and surfaces, matching `all`.
+            #
+            # SystemCallError, not just ENOENT/EACCES, for the same reason
+            # started_at_for's own rescue already widened past those two (see its
+            # comment) and read_json's did too: the FILE this stats can itself be a
+            # symlink loop (ELOOP) or TCC-denied (EPERM on macOS), not only vanished
+            # or permission-denied in the two ways originally listed.
+            def build_session(path)
+              stat = File.stat(path)
+            rescue SystemCallError
+              nil
+            else
+              Session.new(
+                agent: self.class.agent_name,
+                id: session_id_from(path),
+                path: path,
+                started_at: started_at_for(path, stat),
+                updated_at: updated_at_for(path, stat),
+                bytes: bytes_for(path, stat),
+                format: primary_layer.format,
+                fidelity: self.class.fidelity_value
+              ) { project_path_for(path) }
+            end
+
+            # Streams a JSONL file looking for a record carrying `key`. Bounded twice
+            # over — `limit` caps the iterations, MAX_LINE_BYTES caps each read — so the
+            # worst case is a few tens of MB even for a file with no newlines in it.
+            # Tolerant of the non-JSON lines and non-object records real logs contain:
+            # a scan that gives up is worth more here than one that raises.
+            #
+            # Presence of `key` alone is not "found": a record can carry it with a
+            # null or wrong-typed value, which would otherwise stop the scan and
+            # permanently shadow a later, usable record — or hand a caller a Hash
+            # where it expected a String, which is exactly what turns project_paths'
+            # .uniq.sort into an ArgumentError from one malformed record. An optional
+            # block is the value check, evaluated only once presence already holds;
+            # it defaults to accepting whatever presence accepted, so a caller with
+            # no block sees no behavior change.
+            def scan_jsonl_for_key(path, key, limit: 25)
+              File.foreach(path, "\n", MAX_LINE_BYTES).with_index do |line, index|
+                break if index >= limit
+
+                begin
+                  record = JSON.parse(line)
+                rescue JSON::ParserError, EncodingError
+                  next
+                end
+                next unless record.is_a?(Hash) && record.key?(key)
+                next if block_given? && !yield(record)
+
+                return record
+              end
+              nil
+            # SystemCallError, matching read_json and build_session. The enumerated
+            # Errno list this replaced missed EPERM, which is what macOS returns for a
+            # TCC-protected path rather than EACCES, and ELOOP. The exposure here is
+            # narrower than read_json's — build_session stats the session file first and
+            # drops it on any SystemCallError, so a file that fails outright never
+            # reaches this — but a file that stats cleanly and then fails on read does,
+            # and the three rescues disagreeing on which errnos count is the kind of
+            # inconsistency that becomes a bug the moment one of them moves.
+            rescue SystemCallError
+              nil
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          # Gemini CLI. Verified against a real store on this machine (2026-08-24):
+          # 9 project directories, 12 chat files, 121 records.
+          #
+          # The store is keyed by an opaque project hash, not by an encoded path:
+          # ~/.gemini/tmp/<projectHash>/chats/session-<UTC stamp>-<hex8>.json, with
+          # a sibling logs.json holding a flat prompt log. Nothing anywhere under
+          # the store names a working directory — grepping every JSON file in it for
+          # cwd, workspace, projectPath, rootPath and directory found zero — which
+          # is why project resolution below depends on a separate map file rather
+          # than on decoding the hash.
+          class Gemini < Base
+            agent :gemini
+            label "Gemini CLI"
+            documented false
+            verified_on "2026-08-24"
+            fidelity :full
+
+            def self.reader_class = Readers::Gemini
+
+            homedir :gemini
+
+            store :chats, dir: "tmp", glob: "*/chats/session-*.json", format: :json
+            store :projects, path: "projects.json", format: :json, optional: true
+
+            warning "sessions are grouped by an opaque project hash; without ~/.gemini/projects.json " \
+                    "this gem cannot say which directory a session belongs to"
+
+            # The delta-log variant: tokentelemetry's parser of this same store
+            # handles chats written as JSONL with a header line and `$set` deltas.
+            # No such file exists here (zero .jsonl anywhere under the store), so
+            # this adapter reads the verified .json spelling only — and says so
+            # where a user with the other spelling will see it, rather than
+            # silently enumerating nothing for half their sessions.
+            def warnings
+              list = super
+              jsonl = Dir.glob(File.join(escape_glob(primary_layer.path), "*", "chats", "*.jsonl"))
+              if jsonl.any?
+                list << "#{jsonl.size} chat file(s) use the JSONL delta format, which this adapter does " \
+                        "not read yet; those sessions are not enumerated"
+              end
+              list
+            end
+
+            # session-2025-11-29T20-08-b20947ab.json. The trailing hex is NOT a
+            # session id: two files in the real store share d4abc9ce while being
+            # different sessions, so the whole basename is the id — unique, stable,
+            # and derivable without opening the file, which is what Layer 2 is for.
+            # The agent's own sessionId lives inside the document and reaches a
+            # caller through the reader.
+            FILENAME = /\Asession-(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-\h+\.json\z/
+
+            # UTC, unlike Codex and pi, whose rollout filenames use the local clock.
+            # Verified rather than assumed: four real filenames match their own
+            # document's startTime to the minute when read as UTC (12-42 against
+            # 2025-12-12T12:42:50.033Z), and would be three hours out as local time
+            # on the machine this was written on.
+            #
+            # Minute precision only — the document's startTime carries seconds, but
+            # reading it would cost a parse per session, and Layer 2 is stat-only.
+            def started_at_for(path, stat)
+              parts = FILENAME.match(File.basename(path))&.captures or return super
+
+              begin
+                Time.utc(*parts.map(&:to_i))
+              rescue ArgumentError # digits that do not form a real date
+                super
+              end
+            end
+
+            # The store groups sessions under a hash of the project directory that
+            # this gem cannot reverse: it is not a plain SHA-256 of the path (tested
+            # directly against real directories), and the store records the path
+            # nowhere else. ~/.gemini/projects.json is the map Gemini itself keeps —
+            # when it exists, this reads it; when it does not, nil is the honest
+            # answer and `projects` reports nothing rather than inventing a name
+            # from the hash.
+            def project_path_for(path)
+              hash = project_dir_name(path)
+              hash && project_map[hash]
+            end
+
+            # <base>/tmp/<projectHash>/chats/<file>.json — two levels up from the
+            # file, not one, so Base's default (the immediate parent) would answer
+            # "chats" for every session.
+            def project_dir_name(path)
+              File.basename(File.dirname(File.dirname(path)))
+            end
+
+            def encode_project(dir)
+              project_map.key(dir) || super
+            end
+
+            def project_paths
+              return [] unless primary_layer.exists?
+
+              Dir.glob(File.join(escape_glob(primary_layer.path), "*", "chats", "session-*.json"))
+                 .filter_map { |path| project_path_for(path) }.uniq.sort
+            end
+
+            private
+
+            # projects.json maps a directory to its hash. Memoized per instance, and
+            # inverted once here rather than scanned per session — a store with
+            # hundreds of sessions would otherwise re-read the file for each.
+            #
+            # Shape unverified: this file does not exist on the machine this adapter
+            # was written on. Both plausible spellings are accepted (a flat
+            # path => hash map, and a nested one under "projects"), and anything
+            # else yields an empty map, which degrades to the same nil
+            # project_path a missing file gives.
+            def project_map
+              @project_map ||= begin
+                layer = layer(:projects)
+                raw = layer&.exists? ? read_json(layer.path) : {}
+                raw = raw["projects"] if raw["projects"].is_a?(Hash)
+                if raw.is_a?(Hash)
+                  raw.each_with_object({}) do |(dir, hash), map|
+                    map[hash] = dir if dir.is_a?(String) && hash.is_a?(String)
+                  end
+                else
+                  {}
+                end
+              end
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          # Grok Build (xAI). PROVISIONAL: ~/.grok does not exist on the machine
+          # this was written on (2026-08-24), so every claim follows
+          # tokentelemetry's working parser of the same store
+          # (resources/tokentelemetry, _scan_grok_sessions and
+          # _grok_usage_from_unified_log) rather than observation.
+          #
+          # A Grok session is a DIRECTORY, not a file:
+          #   ~/.grok/sessions/<url-encoded cwd>/<session-uuid>/
+          #     summary.json  chat_history.jsonl  events.jsonl  updates.jsonl
+          #     signals.json  plan_mode.json  subagents/<spawn-id>/meta.json
+          #
+          # summary.json is what this adapter enumerates, because it is the record
+          # that always exists and carries the session's own metadata. The
+          # transcript beside it is what the reader reads, and `bytes` counts the
+          # whole directory — the same choice Claude's adapter makes for its
+          # sidecar tree, and for the same reason: those bytes belong to this
+          # session, and a `du` that ignored them would disagree with the disk.
+          class Grok < Base
+            agent :grok
+            label "Grok Build"
+            documented false
+            verified_on "2026-08-24"
+            fidelity :full
+
+            def self.reader_class = Readers::Grok
+
+            homedir :grok_build
+
+            store :sessions, dir: "sessions", glob: "*/*/summary.json", format: :json
+            store :unified_log, path: File.join("logs", "unified.jsonl"), format: :jsonl, optional: true
+
+            warning "billed token usage is not in the session directory: it lives in " \
+                    "~/.grok/logs/unified.jsonl, keyed by session id, and is unavailable if that " \
+                    "log has rotated away"
+
+            def warnings
+              list = super
+              if primary_layer.exists?
+                list << "Grok's store shape is unverified — no ~/.grok existed on the machine this " \
+                        "adapter was written on, so it follows tokentelemetry's parser of the same " \
+                        "format. Please open an issue if sessions, projects or usage look wrong."
+              end
+              list
+            end
+
+            # <sessions>/<url-encoded cwd>/<session-uuid>/summary.json — the id is
+            # the directory holding the file, not the file's own basename, which is
+            # the constant "summary".
+            def session_id_from(path)
+              File.basename(File.dirname(path))
+            end
+
+            # The project bucket is a URL-encoded absolute path (tokentelemetry
+            # unquotes it), so unlike Claude's and pi's dash encodings this one is
+            # losslessly reversible. summary.json's own info.cwd is preferred where
+            # readable, because a recorded path beats a decoded directory name; the
+            # decode is the fallback, and a good one.
+            def project_path_for(path)
+              recorded = read_json(path).dig("info", "cwd")
+              return recorded if recorded.is_a?(String)
+
+              decode_project(File.basename(File.dirname(File.dirname(path))))
+            end
+
+            def project_dir_name(path)
+              File.basename(File.dirname(File.dirname(path)))
+            end
+
+            def encode_project(dir)
+              # Percent-encode everything a path separator is not, matching what
+              # URL-encoding a whole path produces. CGI.escape is deliberately not
+              # used: it encodes a space as "+", which decodes back to "+" here.
+              URI.encode_www_form_component(dir).gsub("+", "%20")
+            end
+
+            def decode_project(name)
+              URI.decode_www_form_component(name)
+            rescue ArgumentError # a name that is not valid percent-encoding
+              name
+            end
+
+            # summary.json carries the session's own clock; the file's mtime is only
+            # ever a proxy for it. Both are ISO 8601 strings per the reference
+            # parser, with created_at standing in when updated_at is absent.
+            def started_at_for(path, stat)
+              parse_time(read_json(path)["created_at"]) || super
+            end
+
+            def updated_at_for(path, stat)
+              summary = read_json(path)
+              parse_time(summary["updated_at"]) || parse_time(summary["created_at"]) || super
+            end
+
+            # The whole session directory, not just summary.json: the transcript and
+            # every sibling log live in it.
+            def bytes_for(path, stat)
+              dir = File.dirname(path)
+              Dir.glob(File.join(escape_glob(dir), "**", "*"), File::FNM_DOTMATCH).sum do |entry|
+                File.file?(entry) ? File.size(entry) : 0
+              rescue SystemCallError
+                0
+              end
+            end
+
+            private
+
+            def parse_time(value)
+              return nil unless value.is_a?(String)
+
+              Time.iso8601(value)
+            rescue ArgumentError
+              nil
+            end
+          end
+        end
+  end
+end