agent_sessions 0.3.0

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

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          class Opencode < Base
+            agent :opencode
+            label "opencode"
+            documented :partly
+            verified_on "2026-07-21"
+            fidelity :full
+
+            def self.reader_class = Readers::Opencode
+
+            homedir :opencode, report_env: ["XDG_DATA_HOME"]
+
+            store :database, path: "opencode.db", format: :sqlite
+            store :legacy, dir: "storage", format: :json, optional: true
+
+            warning "pre-v1.2.0 storage/ tree may remain on disk after migration; " \
+                    "counting it alongside opencode.db double-counts sessions"
+
+            # The declared default stands unless another candidate actually holds a
+            # database. Falling back to it rather than to the first candidate that
+            # merely exists keeps `where` printing a concrete, conventional path on
+            # a machine with no opencode at all.
+            def base_dir
+              @base_dir ||= begin
+                probes = ([resolver.home(:opencode)] + resolver.candidates(:opencode)).map(&:to_s).uniq
+                probes.find { |dir| Dir.glob(File.join(escape_glob(dir), DATABASE_GLOB)).any? } || resolver.home(:opencode).to_s
+              end
+            end
+
+            # opencode names its database per release channel — opencode.db,
+            # opencode-stable.db — so the filename is a glob, not a constant
+            # (tokentelemetry globs the same pattern). Unverified here: this machine
+            # has only the plain name.
+            DATABASE_GLOB = "opencode*.db"
+
+            SESSION_COLUMNS = "id, directory, time_created, time_updated"
+
+            # Sessions are rows, not files, so the Base glob enumeration is replaced by
+            # a deferred query: it runs at first consumption, and only if the database
+            # exists. The existence check comes FIRST so machines without opencode
+            # never need sqlite3 at all (design doc section 9).
+            #
+            # Row order is deliberately unspecified: no ORDER BY, so rows arrive in
+            # whatever order SQLite's own scan produces (rowid order, absent an
+            # index that would change it) — unlike the other six adapters, which are
+            # path-sorted for free by Dir.glob. Invisible today because nothing here
+            # sorts before Task 10 does its own sort_by(&:updated_at); stated so a
+            # future caller of THIS method directly does not come to depend on
+            # insertion order looking stable.
+            #
+            # The gap between this check and the open below is a real TOCTOU window —
+            # opencode could delete or migrate the file in between — but the open
+            # that follows a vanished file raises SQLite3::CantOpenException (verified
+            # directly), which each_session_row already turns into UnreadableStore.
+            # That is judged the right answer, not a bug to special-case: unlike
+            # Base's own glob-then-stat race (one file silently missing from a
+            # multi-file listing, so build_session's rescue drops it and moves on),
+            # a vanished DATABASE is the store's only source for every session, so
+            # there is nothing partial to return — "the store I just confirmed
+            # exists is now unreadable" is what happened, and UnreadableStore says
+            # exactly that.
+            #
+            # Opens once per consumption, not once per instance: `sessions`,
+            # `sessions_for_project` and `project_paths` each open, query and close
+            # their own connection through each_session_row. That costs an extra
+            # open when a caller uses more than one of the three, but keeps every
+            # method independently correct rather than threading a shared handle
+            # through them — and Enumerator.new's block does not even run until the
+            # RETURNED lazy enumerator is consumed, so a caller that builds `sessions`
+            # and never touches it opens nothing at all. Confirmed empirically (not
+            # just assumed from Enumerator's docs) that the `ensure db&.close` inside
+            # each_session_row fires promptly either way a caller can stop early —
+            # `.lazy.first(n)` and an external `each { break }` both unwind the
+            # generator fiber immediately, before the outer call returns — so a
+            # caller taking `sessions.first` never leaves a connection open waiting
+            # for GC to reclaim the fiber.
+            def sessions
+              paths = database_paths
+              return [].lazy if paths.empty?
+
+              Enumerator.new do |yielder|
+                seen = {}
+                paths.each do |db_path|
+                  each_session_row(db_path, "SELECT #{SESSION_COLUMNS} FROM session") do |row|
+                    # Channel databases can hold the same session — a store migrated
+                    # between channels keeps both files. Deduped by id, first
+                    # database wins, so one session is one row to a caller counting
+                    # them. tokentelemetry dedups the same way for the same reason.
+                    next if seen[row.first]
+
+                    seen[row.first] = true
+                    yielder << build_db_session(db_path, row)
+                  end
+                end
+              end.lazy
+            end
+
+            # The directory column holds the full recorded path, so filtering is a
+            # WHERE clause instead of the Base read-and-compare loop.
+            def sessions_for_project(dir)
+              dir = File.expand_path(dir)
+              paths = database_paths
+              return [].lazy if paths.empty?
+
+              Enumerator.new do |yielder|
+                seen = {}
+                paths.each do |db_path|
+                  each_session_row(db_path, "SELECT #{SESSION_COLUMNS} FROM session WHERE directory = ?", [dir]) do |row|
+                    next if seen[row.first]
+
+                    seen[row.first] = true
+                    yielder << build_db_session(db_path, row)
+                  end
+                end
+              end.lazy
+            end
+
+            # ORDER BY matches the sorted order Base guarantees, so `projects` output is
+            # stable and diffable whichever adapter answers it. is_a?(String) excludes
+            # a row whose directory is NULL (build_db_session's guard, same rule 2
+            # container check) rather than letting a literal nil sort in among real
+            # paths — "excluded, not nil", matching Base's project_paths docstring.
+            # .uniq is needed on top of SQL's own DISTINCT: SQLite's DISTINCT treats a
+            # BLOB and a byte-identical TEXT value as different rows (confirmed
+            # directly — typeof reports "text" vs "blob" for the same bytes even
+            # though the sqlite3 gem returns both to Ruby as String, see
+            # build_db_session's comment), so without this a blob/text pair with
+            # identical bytes would surface as two entries where Base's own
+            # `.uniq.sort` would collapse them to one.
+            def project_paths
+              paths = []
+              database_paths.each do |db_path|
+                each_session_row(db_path, "SELECT DISTINCT directory FROM session ORDER BY directory") do |row|
+                  paths << row.first if row.first.is_a?(String)
+                end
+              end
+              # Sorted after the union, not per database: SQL's ORDER BY only orders
+              # within one file, and two channel databases concatenated would leave
+              # `projects` unsorted — the one thing Base guarantees about it.
+              paths.uniq.sort
+            end
+
+            # Base checks the declared path literally, which gets a machine holding
+            # only a channel-named database wrong twice: its "is this agent
+            # installed" gate sees no declared layer and skips the store checks
+            # entirely, and the store check itself would report :fail on a real
+            # store that is merely called something the declaration did not predict.
+            #
+            # Any file matching the glob satisfies the claim. The detail names what
+            # was actually found, so a non-canonical filename is visible rather than
+            # merely tolerated — the same reason detail_for prints a file count.
+            def verify
+              found = database_paths
+              return super if found.empty?
+
+              checks = super
+              database = checks.find { |candidate| candidate.claim == "store database exists" }
+              return checks.map { |c| c.claim == database&.claim && !c.pass? ? passing_database(found) : c } if database
+
+              # The skip gate fired: Base returned one :skip and never looked at the
+              # stores. Answer the store claim it never asked.
+              [passing_database(found)] + checks.reject { |c| c.claim == "agent is installed" }
+            end
+
+            private
+
+            def passing_database(found)
+              check(:pass, "store database exists", found.join(", "))
+            end
+
+            # Every database in the resolved store directory, canonical name first
+            # so its ids win the dedup above. Sorted for a stable order across runs;
+            # Dir.glob's own order is filesystem-dependent.
+            #
+            # The existence check that used to live in each caller is this method
+            # returning empty: a machine without opencode never opens anything, and
+            # so never needs the sqlite3 gem (design doc section 9).
+            def database_paths
+              @database_paths ||= begin
+                found = Dir.glob(File.join(escape_glob(base_dir), DATABASE_GLOB)).sort
+                canonical = primary_layer.path
+                found.include?(canonical) ? [canonical] + (found - [canonical]) : found
+              end
+            end
+
+            # `directory` carries TEXT affinity, so any numeric literal written to it
+            # is converted to text at INSERT time (SQLite's own rule, the mirror image
+            # of the INTEGER-affinity coercion `session_time` guards below) — but a
+            # NULL that reached this NOT-NULL column the way a NOT-NULL column added
+            # via a defaultless ALTER TABLE can hold NULL for pre-existing rows
+            # survives affinity untouched, and so does an Integer that landed in a
+            # column SQLite gave BLOB (no-conversion) affinity rather than TEXT (the
+            # test fixture for this reproduces it — a bare, undeclared column type).
+            # is_a?(String) catches both. It does NOT, however, catch an actual BLOB
+            # storage class value the way an earlier version of this comment claimed:
+            # confirmed directly that the sqlite3 gem returns a BLOB to Ruby as a
+            # plain String (ASCII-8BIT-encoded, but still is_a?(String)) — the guard
+            # is correct and load-bearing for what it DOES catch (rule 2's container
+            # check, the same one Cursor's `cwd.is_a?(String)` applies to the
+            # equivalent field, and the "excluded, not nil" project_paths needs per
+            # Base's own docstring), just not a universal type filter. project_paths
+            # separately guards the BLOB/TEXT duplicate this leaves open.
+            def build_db_session(db_path, row)
+              id, directory, created_ms, updated_ms = row
+              project_path = directory.is_a?(String) ? directory : nil
+              Session.new(
+                agent: self.class.agent_name, id: id, path: db_path, project_path: project_path,
+                started_at: session_time(created_ms),
+                updated_at: session_time(updated_ms) || session_time(created_ms) || db_mtime(db_path),
+                bytes: nil, # rows in a shared database; a file size would be a lie
+                format: primary_layer.format, fidelity: self.class.fidelity_value
+              )
+            end
+
+            # Mirrors Cursor's meta_time guard against the identical failure, reached
+            # by a different route: time_created/time_updated carry INTEGER affinity,
+            # which converts a numeric-LOOKING text value to a number at INSERT time
+            # but leaves non-numeric text (or a hand-edited NULL, despite NOT NULL —
+            # see build_db_session's comment on the same quirk for `directory`)
+            # stored as-is. is_a?(Numeric) rejects that. A value that passes but is
+            # merely huge (an absurd but real millisecond count) still overflows to
+            # Infinity once forced through Float by `/ 1000.0`, and Time.at(Infinity)
+            # raises FloatDomainError uncaught — rule 3's failure mode, one row
+            # taking the whole enumeration down. seconds.finite? is checked AFTER the
+            # division for the same reason Cursor's is: a finite Integer literal
+            # hundreds of digits long still overflows only once divided, so checking
+            # millis' own finiteness first would miss it.
+            #
+            # nil beats a wrong guess here for the same reason Base's started_at_for
+            # prefers nil to guessing: the only fallback available for a shared-db
+            # row is the database FILE's own stat, which would print the identical
+            # timestamp for every session in the store regardless of when each one
+            # actually happened — a plausible-looking wrong value is worse than an
+            # honest unknown one.
+            def session_time(millis)
+              return nil unless millis.is_a?(Numeric)
+
+              seconds = millis / 1000.0
+              Time.at(seconds) if seconds.finite?
+            end
+
+            # CRITICAL, caught in review: plan decision 5 makes updated_at a
+            # cross-adapter invariant — "never nil; started_at may be" — because
+            # every file-based adapter gets it for free from Base#updated_at_for =
+            # stat.mtime, which cannot be nil. opencode is the first adapter that
+            # CAN return nil here (session_time can fail on both created_ms and
+            # updated_ms independently), and a nil is not a value this reader gets
+            # to invent locally: Task 9's `since` filter and Task 10's
+            # sort_by(&:updated_at) both assume the invariant holds, and one
+            # malformed row in a 359-row shared database reaching either would take
+            # the WHOLE cross-agent listing down with an ArgumentError or
+            # NoMethodError — rule 3's failure mode, relocated one layer up and past
+            # every rescue, not removed. build_db_session's fallback chain
+            # (updated_ms -> created_ms -> db_mtime) keeps the invariant instead:
+            # time_created is a real per-session timestamp, not a guess, so it is
+            # tried before falling back to the database FILE's own mtime, which is
+            # reached only when a row's own pair of timestamps are BOTH malformed —
+            # it is not this session's timestamp, but it is a true upper bound on
+            # when anything in the store last changed, and unlike stat.birthtime
+            # it is never allowed to be nil either: File.mtime can still raise
+            # SystemCallError in the narrow window between a successful query and
+            # this call (the same class of race Base's own started_at_for guards
+            # its stat against), and letting THAT reach the caller unrescued would
+            # reintroduce the exact bug this method exists to close. Time.now is
+            # the true last resort — an honest "unknown, treat as just now" — so
+            # this method, unlike every other timestamp helper in this file, is
+            # never allowed to return nil.
+            def db_mtime(db_path)
+              @db_mtime ||= begin
+                File.mtime(db_path)
+              rescue SystemCallError
+                Time.now
+              end
+            end
+
+            # require_sqlite! must stay OUTSIDE the begin/rescue: if it raised inside,
+            # Ruby would evaluate the SQLite3::Exception rescue clause while matching
+            # and hit NameError, because the constant was never loaded.
+            #
+            # The open itself (read-only URI with escaped path, no immutable=1,
+            # 5s busy_timeout) lives in Agent::Sessions::Sqlite with the evidence for
+            # each choice — extracted when the opencode READER became its second
+            # caller. What stays here is this adapter's answer to failure: a query
+            # error becomes UnreadableStore, because a vanished or corrupt DATABASE
+            # is the store's only source for every session — there is nothing
+            # partial to return. Design doc section 10's "never write" caveat also
+            # still belongs to this store: opening a WAL db even read-only touches
+            # its -shm/-wal sidecars (SQLite's reader bookkeeping, confirmed
+            # directly); a directory with no write permission surfaces as
+            # SQLite3::ReadOnlyException → UnreadableStore, confirmed against a
+            # chmod 0555 directory.
+            #
+            # Lock contention is NOT covered by a test: reliably reproducing it
+            # needs a second process holding a write transaction for the exact
+            # duration of the read — noted rather than left looking covered.
+            def each_session_row(db_path, sql, params = [], &block)
+              require_sqlite!
+              db = nil
+              begin
+                db = Sqlite.open_readonly(db_path)
+                db.execute(sql, params, &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,
+                    "opencode sessions live in opencode.db (SQLite); add the sqlite3 gem to enumerate them"
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          class Pi < Base
+            agent :pi
+            label "pi"
+            documented true
+            verified_on "2026-07-21"
+
+            fidelity :full
+
+            # The reader shares this adapter's provisional standing: written against
+            # tokentelemetry's parser of the same format, since this machine's pi
+            # store holds no session files to observe. Its own header comment says
+            # what remains unverified.
+            def self.reader_class = Readers::Pi
+
+            homedir :pi
+
+            store :sessions, dir: "sessions", glob: "--*--/*.jsonl", format: :jsonl,
+                             env: "PI_CODING_AGENT_SESSION_DIR"
+
+            # pi's *session files* are still absent from this machine: all nine
+            # directories under ~/.pi/agent/sessions (real pi output — see
+            # encode_project below) are empty of .jsonl (2026-08-05). Everything
+            # about a session's CONTENT is therefore still inference from design
+            # doc 8.6, not observation: the header's "cwd" key (project_path_for
+            # below), which line it is on (the limit: argument there), and
+            # whether a session's id segment is 8 hex characters or a full uuid
+            # (FILENAME below). `warnings` below repeats the gist where a CLI user
+            # will actually see it, gated on the store existing.
+            #
+            # The directory NAMING scheme is a different story: it is real pi
+            # output, not a guess — see encode_project's comment.
+            #
+            # To check the remaining unverified points against a real session:
+            #   head -1 ~/.pi/agent/sessions/--*--/*.jsonl
+            # and look for: which key actually holds the cwd (assumed "cwd"),
+            # which line it is on (assumed line 1), and whether the id segment is
+            # 8 hex characters or a full uuid (assumed 8 hex). A mismatch means
+            # fixing the matching line below and the warning above it, not just
+            # the comment next to it.
+            def warnings
+              list = super
+              if primary_layer.exists?
+                list << "pi's session header shape is unverified — every project directory under this " \
+                        "store is empty of .jsonl files on the machine this adapter was written on, so " \
+                        "the header key inside a real session (assumed \"cwd\") has never been read. If " \
+                        "`projects` or `du --by project` report nothing while you have sessions, that key " \
+                        "is not \"cwd\"; please open an issue with the first line of one file."
+              end
+              list
+            end
+
+            # FILENAME's \h{8} id specifically contradicts the one written source
+            # available: design doc section 8.6 says pi's *entries* carry an
+            # 8-character hex id, while the section 8 table gives the filename
+            # itself as <timestamp>_<uuid>. Both cannot be right, and nothing on
+            # this machine can settle which one pi's own encoder does. \h{8} is
+            # what is implemented here; if a real file uses a full uuid instead,
+            # this regex simply never matches it, and session_id_from below falls
+            # back to the basename — a real but visibly non-canonical id, not a
+            # crash.
+            FILENAME = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})_(\h{8})\.jsonl\z/
+
+            def session_id_from(path)
+              captures = FILENAME.match(File.basename(path))&.captures or return super
+
+              captures.last
+            end
+
+            # The rescue is not optional. \d{2} accepts 00-99, and Time.new raises
+            # ArgumentError on month 13, minute 60 and friends. build_session scopes
+            # its own rescue to File.stat so that a raising hook surfaces as the
+            # adapter bug it usually is — but this hook raises on FILE DATA, and
+            # without the rescue one malformed filename returns zero sessions from
+            # `sessions`, `project_paths` and `for_project` alike, and exits the CLI
+            # with a raw backtrace that takes every other agent's rows with it.
+            # That failure mode was measured in Task 4, against Codex — pi has no
+            # real filenames of its own to reproduce it against, but the mechanism
+            # (Time.new rejecting digits \d{2} happily accepted) belongs to Ruby,
+            # not to any one adapter's data, so the same rescue applies here.
+            #
+            # Local, not UTC: copied from Codex's VERIFIED behaviour (its rollout
+            # filenames use the local clock, confirmed against 360 real files).
+            # pi's is UNVERIFIED — no real pi filename exists on this machine to
+            # check it against. If pi instead publishes UTC filenames, every pi
+            # started_at is silently off by the machine's UTC offset, with no
+            # signal that it happened. The test fixture's header timestamp and
+            # filename timestamp deliberately disagree (see build_fixture in
+            # test/pi_adapter_test.rb) so that a started_at_for which quietly fell
+            # back to reading the header would be caught returning the wrong hour,
+            # rather than passing by coincidence on a UTC machine.
+            #
+            # 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 fall back to stat.birthtime for every pi session: a
+            # plausible-looking wrong started_at with no signal, which is worse
+            # than a crash.
+            def started_at_for(path, stat)
+              parts = FILENAME.match(File.basename(path))&.captures or return super
+
+              begin
+                Time.new(*parts.first(6).map(&:to_i))
+              rescue ArgumentError # the digits matched but do not form a real date
+                super
+              end
+            end
+
+            # Verified against nine real pi project directories found on this
+            # machine on 2026-08-05 (~/.pi/agent/sessions/--*--, empty of .jsonl
+            # but real encoder output regardless — see the class comment above)
+            # — see test_encode_project_round_trips_the_nine_real_pi_directories
+            # in test/pi_adapter_test.rb. Design doc section 7 described this only
+            # as "wrap the dashed cwd in double dashes," ambiguous on two points
+            # neither of us had settled by observation. Both are now settled by
+            # real output rather than by carrying Claude's rule over into pi's:
+            #
+            #   1. The dash count. Read literally — dash-encode the WHOLE cwd,
+            #      including its leading "/", then wrap that in "--" — an
+            #      absolute path would get THREE leading dashes. Real pi output
+            #      has TWO: the leading "/" is absorbed into the wrap rather than
+            #      separately encoded, matching the store's own "--*--/*.jsonl"
+            #      glob (above).
+            #
+            #   2. The character class. This used to read like Claude's "every
+            #      non-alphanumeric character becomes -" and that was WRONG: pi
+            #      preserves dots. Two of the nine real directories contain a
+            #      literal "." (a domain name in the path) unchanged, while the
+            #      "/" separators around it became "-". Claude has 45 project
+            #      directories on this same machine and not one contains a dot —
+            #      the two adapters' rules genuinely differ; they do not merely
+            #      happen to agree on every example seen before now.
+            #
+            # What remains a guess: "_", spaces, and any other non-"/" separator
+            # never appear in the nine real directories, so nothing here confirms
+            # whether pi encodes them or preserves them too, the way it preserves
+            # ".". Do not widen this gsub back into a character class without new
+            # evidence — that is exactly the mistake being corrected here.
+            #
+            # This directory-name encoding is what sessions_for_project falls back
+            # to when a session's own header cwd cannot be read (see
+            # Base#encode_project) — pi's whole safety net for project_path_for's
+            # still-unverified "cwd" header key assumption. That fallback is now
+            # solid: a wrong "cwd" key degrades to accurate name matching instead
+            # of two guesses compounding into silent failure.
+            #
+            # Expects an absolute, expanded path; sessions_for_project expands
+            # first.
+            def encode_project(dir)
+              "--#{dir.delete_prefix("/").gsub("/", "-")}--"
+            end
+
+            # pi publishes its format: one header line, then typed entries (design
+            # doc 8.6) — which argues for staying TIGHTER than Claude's 25, whose
+            # cwd genuinely was not on line 1 and whose format was never
+            # published. But "publishes a spec" is not the same evidence as
+            # "measured against a real file," and this machine has zero pi
+            # sessions to measure against. limit: 25 matches Claude's number not
+            # because pi is assumed to behave like Claude, but because
+            # scan_jsonl_for_key returns as soon as it finds a usable record: the
+            # width costs nothing while the line-1 assumption holds, and is only
+            # ever paid on the one case this file cannot rule out — a preamble pi
+            # does not document, the same way Claude's kebab-case preamble was not
+            # documented either. The one real cost of going wide: the predicate
+            # below is type-checked but not otherwise selective, so a longer
+            # window is more exposure to a later, unrelated record that happens to
+            # carry a String "cwd" of its own — a decoy shadowing pi's real one —
+            # a risk this file cannot bound without a real session to look at.
+            #
+            # The predicate is mandatory, not decoration. scan_jsonl_for_key stops
+            # at the first record merely CARRYING the key, so without a value
+            # guard a record holding "cwd": null shadows a later usable one
+            # permanently, and a non-String cwd reaches project_paths' .uniq.sort
+            # and raises.
+            def project_path_for(path)
+              scan_jsonl_for_key(path, "cwd", limit: 25) { |record| record["cwd"].is_a?(String) }&.fetch("cwd")
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          # Qwen Code. PROVISIONAL: ~/.qwen does not exist on the machine this was
+          # written on (2026-08-24), so every claim here comes from tokentelemetry's
+          # working parser of the same store (resources/tokentelemetry,
+          # backend/main.py section 4) rather than from observation — the same
+          # standing the pi reader carries, and declared the same way.
+          #
+          # Qwen is a Gemini CLI fork that kept Gemini's directory layout and
+          # adopted Anthropic's message shape, which is why its store looks like
+          # ~/.gemini's while its records read like Claude's.
+          class Qwen < Base
+            agent :qwen
+            label "Qwen Code"
+            documented false
+            verified_on "2026-08-24"
+            fidelity :full
+
+            def self.reader_class = Readers::Qwen
+
+            homedir :qwen
+
+            store :chats, dir: "projects", glob: "*/chats/*.jsonl", format: :jsonl
+            store :settings, path: "settings.json", format: :json, optional: true
+
+            def warnings
+              list = super
+              if primary_layer.exists?
+                list << "Qwen's store shape is unverified — no ~/.qwen existed on the machine this " \
+                        "adapter was written on, so it follows tokentelemetry's parser of the same " \
+                        "format. If sessions or projects look wrong, please open an issue with the " \
+                        "first line of one chat file."
+              end
+              list
+            end
+
+            # Unlike Gemini's, the project directory is reported as a name this gem
+            # cannot decode into a path, so the recorded cwd inside the file is the
+            # only source — the same position Claude and pi are in. The predicate is
+            # mandatory: scan_jsonl_for_key stops at the first record merely CARRYING
+            # the key, so without it a record holding "cwd": null shadows a later
+            # usable one permanently.
+            def project_path_for(path)
+              scan_jsonl_for_key(path, "cwd", limit: 25) { |record| record["cwd"].is_a?(String) }&.fetch("cwd")
+            end
+          end
+        end
+  end
+end

data/lib/agent/sessions/audit.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        # Answers: are these plaintext transcripts inside anything that syncs?
+        # Needs only Layer 1. Time Machine exclusion status is a planned addition.
+        class Audit
+          include HomeExpansion
+
+          Finding = Data.define(:agent, :kind, :path, :bytes, :synced_to)
+
+          SYNC_ROOTS = {
+            dropbox: ["~/Dropbox"],
+            icloud: ["~/Library/Mobile Documents"],
+            cloud_storage: ["~/Library/CloudStorage"],
+            onedrive: ["~/OneDrive"],
+            google_drive: ["~/Google Drive"]
+          }.freeze
+
+          def initialize(stores, env: ENV)
+            @stores = stores
+            @env = env
+          end
+
+          def report
+            @stores.flat_map do |store|
+              store.layers.select(&:exists?).map do |location|
+                Finding.new(
+                  agent: store.agent,
+                  kind: location.kind,
+                  path: location.path,
+                  bytes: bytes_under(location.path),
+                  synced_to: sync_services_for(location.path)
+                )
+              end
+            end
+          end
+
+          private
+
+          def bytes_under(path)
+            return File.size(path) if File.file?(path)
+
+            # FNM_DOTMATCH because a plain **/* skips dotfiles, and a byte total that
+            # quietly omits them is worse than no total at all.
+            Dir.glob(File.join(path, "**", "*"), File::FNM_DOTMATCH).sum do |entry|
+              File.file?(entry) ? File.size(entry) : 0
+            end
+          end
+
+          # Both sides are resolved through realpath before comparing. On macOS a
+          # temp dir lives at /private/var/... behind a /var symlink, and ~/Dropbox
+          # is frequently a symlink itself, so comparing raw paths silently misses.
+          def sync_services_for(path)
+            real = real_path(path) || path
+            SYNC_ROOTS.select do |_service, roots|
+              roots.any? do |root|
+                expanded = real_path(expand(root))
+                expanded && (real == expanded || real.start_with?("#{expanded}/"))
+              end
+            end.keys
+          end
+
+          def real_path(path)
+            File.realpath(path)
+          rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+            nil
+          end
+        end
+  end
+end

data/lib/agent/sessions/check.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        Check = Data.define(:agent, :status, :claim, :detail) do
+          def pass? = status == :pass
+        end
+  end
+end