agent_sessions 0.3.0 → 0.3.1

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

@@ -0,0 +1,54 @@
+# Class Agent::Sessions::Adapters::Cursor <a id="class-Agent-Sessions-Adapters-Cursor"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/cursor.rb |
+
+## Public Instance Methods
+### `project_path_for(path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+cwd's presence in meta.json is not enough on its own (rule 1): the key can
+hold a Hash, an Integer, anything JSON allows, and project_paths' .uniq.sort
+raises on a non-String member. is_a?(String) is the guard, not merely a style
+preference.
+
+### `session_id_from(path)` <a id="method-i-session_id_from"></a> <a id="session_id_from-instance_method"></a>
+chats/<chat-id>/<uuid>/store.db — two nested ids (design doc 16 Q5), so the
+session id keeps both. The blob store is never opened here; the sibling
+meta.json is the metadata source (8.3), with stat as fallback.
+
+Pure string manipulation on `path` — File.basename/File.dirname never raise
+for any String input, so this hook cannot violate rule 3 (build_session lets a
+raising hook propagate) regardless of shape. A path shallower than two
+segments is not reachable through this store's OWN enumeration: the glob above
+is "<strong>/</strong>/store.db", and Dir.glob's "*" never crosses a "/", so
+every path this adapter actually enumerates is exactly two directories deep,
+by construction, not by convention (see
+test_session_id_from_does_not_raise_for_a_shallow_path, which calls this hook
+directly to pin the behaviour for a caller that bypasses the glob).
+
+### `started_at_for(path, stat)` <a id="method-i-started_at_for"></a> <a id="started_at_for-instance_method"></a>
+Not documented.
+
+### `updated_at_for(path, stat)` <a id="method-i-updated_at_for"></a> <a id="updated_at_for-instance_method"></a>
+Not documented.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+meta.json's field names (createdAtMs, updatedAtMs, cwd) are read from design
+doc 8.3, itself written from a machine that had them to check against — this
+machine has no ~/.cursor/chats (Cursor CLI is a separate product from the
+Cursor editor and is simply not installed here). Gated, the same shape as pi's
+identical warning about its own unverified header key and cursor_ide's about
+its real session location below: a "here is what breaks, please act on it"
+report reaches only someone whose declared store actually exists.
+
+Why THIS unverified assumption specifically needs a warning, where some others
+might get away without one: the failure is silent and looks correct. If
+createdAtMs/updatedAtMs are the wrong keys, meta_time returns nil and
+started_at_for/updated_at_for fall back to stat.birthtime/mtime — real file
+timestamps, not an obviously broken value. If cwd is the wrong key,
+project_path_for returns nil exactly the way it correctly does for a chat that
+genuinely has no recorded cwd. Nothing in the output distinguishes "Cursor
+recorded no project" from "the gem read the wrong key" — `projects`, `du --by
+project`, and `sessions_for_project` all silently under-report Cursor, with no
+error and no implausible-looking number anywhere to notice.

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

@@ -0,0 +1,49 @@
+# Class Agent::Sessions::Adapters::CursorIde <a id="class-Agent-Sessions-Adapters-CursorIde"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/cursor_ide.rb |
+
+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/<strong>/agent-transcripts/</strong>) 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.
+
+## Constants
+### `KEY_PREFIX` <a id="constant-KEY_PREFIX"></a> <a id="KEY_PREFIX-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `project_path_for(_path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+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.
+
+### `project_paths()` <a id="method-i-project_paths"></a> <a id="project_paths-instance_method"></a>
+Not documented.
+
+### `sessions()` <a id="method-i-sessions"></a> <a id="sessions-instance_method"></a>
+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.
+
+### `sessions_for_project(_dir)` <a id="method-i-sessions_for_project"></a> <a id="sessions_for_project-instance_method"></a>
+Not documented.

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

@@ -0,0 +1,135 @@
+# Module Agent::Sessions::Adapters::Enumeration <a id="module-Agent-Sessions-Adapters-Enumeration"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/agent/sessions/adapters/enumeration.rb |
+
+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.
+
+## Constants
+### `MAX_LINE_BYTES` <a id="constant-MAX_LINE_BYTES"></a> <a id="MAX_LINE_BYTES-constant"></a>
+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.
+
+## Public Instance Methods
+### `bytes_for(_path, stat)` <a id="method-i-bytes_for"></a> <a id="bytes_for-instance_method"></a>
+Bytes this session occupies on disk. The transcript alone for a store that
+keeps one file per session; an adapter whose agent writes sidecar files beside
+the transcript overrides this and adds them. Like the two time hooks it takes
+the stat the enumerator already holds, so the common case still costs nothing
+beyond the syscall already made.
+
+An override runs EAGERLY for every session, so it carries build_session's
+constraint: it must not raise on an unreadable path, or one bad sidecar takes
+down the whole listing rather than its own row.
+
+### `encode_project(_dir)` <a id="method-i-encode_project"></a> <a id="encode_project-instance_method"></a>
+nil means this adapter has no directory-name fallback rule. Used only by
+sessions_for_project, and only for a session whose own recorded cwd could not
+be read. When overridden: dir arrives pre-expanded here from
+sessions_for_project (File.expand_path), which is the precondition an override
+may rely on — a direct caller must pass an absolute, expanded path itself, or
+the encoding is nonsense ("app", "~/app", and a trailing slash all encode
+differently from the canonical form real project directories were named from).
+
+### `project_dir_name(path)` <a id="method-i-project_dir_name"></a> <a id="project_dir_name-instance_method"></a>
+The directory whose name the encoding must match, when sessions_for_project
+falls back to it. Overridable: not every store puts the encoded project
+directly above the session file — cursor_ide nests
+projects/<name>/agent-transcripts/*, where the immediate parent is
+agent-transcripts and matching it would find nothing, silently.
+
+### `project_path_for(_path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+nil means the project is unknown for this session. Adapters override with a
+bounded read of their own metadata; Base cannot guess.
+
+### `project_paths()` <a id="method-i-project_paths"></a> <a id="project_paths-instance_method"></a>
+Distinct recorded project paths, sorted. This is the read-everything direction
+(design doc section 7): the encodings cannot be reversed, so the recorded cwd
+inside each file is the only reliable source. Sessions whose project cannot be
+determined are excluded, not returned as nil.
+
+Sorted rather than left in glob order because a stable order is what makes
+`projects` output diffable and `du --by project` deterministic — and adapters
+answering from a database would otherwise impose their own.
+
+### `session_id_from(path)` <a id="method-i-session_id_from"></a> <a id="session_id_from-instance_method"></a>
+--- Layer 2 hooks, overridable per adapter ---
+
+### `sessions()` <a id="method-i-sessions"></a> <a id="sessions-instance_method"></a>
+Lazily enumerates the primary store. Each consumed session costs one stat plus
+filename parsing — never a content read. project_path is the exception and
+pays for itself on first access.
+
+A store the gem has no layout for is refused rather than reported empty:
+Location#enumerable? exists precisely so "nothing here to enumerate" and
+"enumerated, found none" stay distinguishable, and silently returning no
+sessions is this gem's worst failure mode.
+
+### `sessions_for_project(dir)` <a id="method-i-sessions_for_project"></a> <a id="sessions_for_project-instance_method"></a>
+Match by RECORDED cwd, exact, per session (design doc section 7, revised
+2026-08-05 — the third design for this method, kept honest here because the
+next reader deserves to know why it is not "cheap"). The first two designs
+were built and disproved against a real store, not in theory:
+
+    1. Directory-name matching (the original design) assumed a
+       session's parent directory equals encode(its own recorded cwd).
+       A project rename breaks that: the agent keeps writing under the
+       OLD encoded directory, so two directories can hold live sessions
+       for the SAME current cwd, and name-only matching silently
+       dropped the stale one — false negatives, the failure mode this
+       gem treats as worst (decision 11).
+
+    2. One-read-per-directory sampling (the first fix for #1) assumed
+       sessions within a directory share a cwd, to keep the match
+       sublinear. Reading a real renamed project's stale directory
+       disproved that: two of its three sessions had been resumed after
+       the rename and recorded the NEW cwd; the third was never resumed
+       and still recorded the OLD one. Sampling one session and
+       applying its verdict to the whole directory is wrong in BOTH
+       directions on the same store — it invented a false positive
+       here, and a different glob order would just as easily have
+       reproduced #1's false negative for that same directory.
+       Approximate cwd resolution doesn't make the error smaller; it
+       just moves where it lands.
+
+Measured cost of reading every session instead of sampling: 0.17 ms per
+session (68 real Claude sessions, full sweep, 0.012s total) — 0.7s
+extrapolated to a 4,000-session store. That is what the sampling complexity
+was buying, and it is not a trade worth making: the enumerator is already
+lazy, so a caller taking first(n) never pays for sessions it never asked
+about, and even the worst case (every session checked, no match) stays under a
+second on a store two orders of magnitude larger than anything observed.
+
+A session whose own cwd cannot be read (the scan gave up, the file is
+unreadable, the adapter declares no reader) falls back to comparing ITS OWN
+directory's name against the encoding, when the adapter declares one — this is
+the only thing encode_project still buys: it keeps a session with an
+unreadable header from becoming invisible, without resolving an unknown
+project for every other session that happens to share its directory.
+
+### `started_at_for(_path, stat)` <a id="method-i-started_at_for"></a> <a id="started_at_for-instance_method"></a>
+Both time hooks take the stat the enumerator already holds, so a session still
+costs one syscall. path is passed for adapters that answer from a sibling
+metadata file instead.
+
+nil beats a wrong guess when the filesystem cannot answer at all — and it says
+so through ENOSYS/EPERM from statx as often as NotImplementedError.
+
+### `updated_at_for(_path, stat)` <a id="method-i-updated_at_for"></a> <a id="updated_at_for-instance_method"></a>
+Not documented.

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

@@ -0,0 +1,67 @@
+# Class Agent::Sessions::Adapters::Gemini <a id="class-Agent-Sessions-Adapters-Gemini"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/gemini.rb |
+
+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.
+
+## Constants
+### `FILENAME` <a id="constant-FILENAME"></a> <a id="FILENAME-constant"></a>
+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.
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `encode_project(dir)` <a id="method-i-encode_project"></a> <a id="encode_project-instance_method"></a>
+Not documented.
+
+### `project_dir_name(path)` <a id="method-i-project_dir_name"></a> <a id="project_dir_name-instance_method"></a>
+<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.
+
+### `project_path_for(path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+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.
+
+### `project_paths()` <a id="method-i-project_paths"></a> <a id="project_paths-instance_method"></a>
+Not documented.
+
+### `started_at_for(path, stat)` <a id="method-i-started_at_for"></a> <a id="started_at_for-instance_method"></a>
+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.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+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.

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

@@ -0,0 +1,64 @@
+# Class Agent::Sessions::Adapters::Grok <a id="class-Agent-Sessions-Adapters-Grok"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/grok.rb |
+
+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.
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `bytes_for(path, stat)` <a id="method-i-bytes_for"></a> <a id="bytes_for-instance_method"></a>
+The whole session directory, not just summary.json: the transcript and every
+sibling log live in it.
+
+### `decode_project(name)` <a id="method-i-decode_project"></a> <a id="decode_project-instance_method"></a>
+Not documented.
+
+### `encode_project(dir)` <a id="method-i-encode_project"></a> <a id="encode_project-instance_method"></a>
+Not documented.
+
+### `project_dir_name(path)` <a id="method-i-project_dir_name"></a> <a id="project_dir_name-instance_method"></a>
+Not documented.
+
+### `project_path_for(path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+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.
+
+### `session_id_from(path)` <a id="method-i-session_id_from"></a> <a id="session_id_from-instance_method"></a>
+<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".
+
+### `started_at_for(path, stat)` <a id="method-i-started_at_for"></a> <a id="started_at_for-instance_method"></a>
+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.
+
+### `updated_at_for(path, stat)` <a id="method-i-updated_at_for"></a> <a id="updated_at_for-instance_method"></a>
+Not documented.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+Not documented.

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

@@ -0,0 +1,93 @@
+# Class Agent::Sessions::Adapters::Opencode <a id="class-Agent-Sessions-Adapters-Opencode"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/opencode.rb |
+
+## Constants
+### `DATABASE_GLOB` <a id="constant-DATABASE_GLOB"></a> <a id="DATABASE_GLOB-constant"></a>
+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.
+
+### `SESSION_COLUMNS` <a id="constant-SESSION_COLUMNS"></a> <a id="SESSION_COLUMNS-constant"></a>
+Not documented.
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `base_dir()` <a id="method-i-base_dir"></a> <a id="base_dir-instance_method"></a>
+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.
+
+### `project_paths()` <a id="method-i-project_paths"></a> <a id="project_paths-instance_method"></a>
+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
+<code>.uniq.sort</code> would collapse them to one.
+
+### `sessions()` <a id="method-i-sessions"></a> <a id="sessions-instance_method"></a>
+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 <code>sessions.first</code> never leaves a
+connection open waiting for GC to reclaim the fiber.
+
+### `sessions_for_project(dir)` <a id="method-i-sessions_for_project"></a> <a id="sessions_for_project-instance_method"></a>
+The directory column holds the full recorded path, so filtering is a WHERE
+clause instead of the Base read-and-compare loop.
+
+### `verify()` <a id="method-i-verify"></a> <a id="verify-instance_method"></a>
+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.

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

@@ -0,0 +1,137 @@
+# Class Agent::Sessions::Adapters::Pi <a id="class-Agent-Sessions-Adapters-Pi"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/pi.rb |
+
+## Constants
+### `FILENAME` <a id="constant-FILENAME"></a> <a id="FILENAME-constant"></a>
+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.
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+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.
+
+## Public Instance Methods
+### `encode_project(dir)` <a id="method-i-encode_project"></a> <a id="encode_project-instance_method"></a>
+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.
+
+### `project_path_for(path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+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.
+
+### `session_id_from(path)` <a id="method-i-session_id_from"></a> <a id="session_id_from-instance_method"></a>
+Not documented.
+
+### `started_at_for(path, stat)` <a id="method-i-started_at_for"></a> <a id="started_at_for-instance_method"></a>
+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.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+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.

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

@@ -0,0 +1,32 @@
+# Class Agent::Sessions::Adapters::Qwen <a id="class-Agent-Sessions-Adapters-Qwen"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Adapters::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/adapters/qwen.rb |
+
+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.
+
+## Public Class Methods
+### `reader_class()` <a id="method-c-reader_class"></a> <a id="reader_class-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `project_path_for(path)` <a id="method-i-project_path_for"></a> <a id="project_path_for-instance_method"></a>
+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.
+
+### `warnings()` <a id="method-i-warnings"></a> <a id="warnings-instance_method"></a>
+Not documented.

data/doc/Agent/Sessions/Adapters.md

@@ -0,0 +1,5 @@
+# Module Agent::Sessions::Adapters <a id="module-Agent-Sessions-Adapters"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/agent/sessions/adapters/pi.rb, lib/agent/sessions/adapters/amp.rb, lib/agent/sessions/adapters/base.rb, lib/agent/sessions/adapters/grok.rb, lib/agent/sessions/adapters/qwen.rb, lib/agent/sessions/adapters/codex.rb, lib/agent/sessions/adapters/claude.rb, lib/agent/sessions/adapters/cursor.rb, lib/agent/sessions/adapters/gemini.rb, lib/agent/sessions/adapters/copilot.rb, lib/agent/sessions/adapters/opencode.rb, lib/agent/sessions/adapters/cursor_ide.rb, lib/agent/sessions/adapters/enumeration.rb |