feat(hub): see what each agent session read, not just what it changed (BEA-98) (#135)

History showed what an agent run CHANGED. What it read lived in a daily
aggregate with no session dimension, so the two could not be joined and
nobody could answer "when my agent answered, what did it look at — and was
it the fresh version or archive/retired-spec.md?".

The join is one string carried through four places: hook -> spool -> hub ->
run card. A run card now marks each change the run also read, lists the
files it read and never touched, and says on screen why a read can be
missing.

The three landmines the issue asks be named here:

1. Op.Note is USER-SETTABLE (`bdrive sync --note`), so joining reads to
   writes on the note string would let any member with write access forge a
   note that collides with a teammate's run card and hang their reads off
   it. Fixed by adding journal.Op.Session — set only by `bdrive sync
   --hook`, never by --note — and joining on that. The note stays settable
   and stays untrusted; the join simply never reads it. Op.Session is
   additive JSONL and, like Mtime, is never an input to Less or Replay, so
   replay determinism is untouched and older ops carry "".

   The read half has the same hole one step further on: POST /reads takes
   the session id from the CLIENT, so a member could report reads under a
   teammate's session and paint files onto their card. Every session row is
   therefore pinned to the ownsDevice-validated device, and the query
   requires ?session= AND ?device= together — a forged row can only be found
   under the forger's own device, which MayActAs guarantees is never
   somebody else's.

2. BUCKET CARDINALITY. Putting the session in the read_stats key would take
   a 2k-file project from ~2k to ~100k rows/day, into a table ReadLedger
   loads whole at boot and full-scans on every heat request, hub-wide — so
   it would slow the Dashboard for projects that never ran an agent. This
   is the escape hatch the spec itself names, taken up front: session rows
   live in their own read_sessions repo, outside ReadLedger.byKey. No
   read_stats PK migration, no change to the resident-row count, ?by=device
   byte-identical. They get their own retention (session_retention_days,
   default 30) which DELETES rather than folds — no heat total was ever
   derived from them.

3. READS ARE RECORDED ONLY FOR PATHS IN THE CURRENT REPLAY, so a session
   that read a file it then deleted shows a change with no read. That is by
   design, and the run card says so in its footer rather than leaving it to
   read as a bug.

Privacy ruling, written into internal/webapp/reads.go before anything
serves it: a session id appears only in History responses on the op that
carries it, and as a ?session= filter INPUT. It is never enumerated — no
listing endpoint, no session column in /heat output, nothing new in
?by=device.

Also: PendingReads now dedupes on (path, session), not path alone. Two
agent sessions on one device between syncs used to collapse into one event
carrying whichever session flushed last — one session's reads silently
credited to another.

Tests: journal round-trip + Less-ignores-Session; the forge test (`sync
--note "claude-code session <someone-else's>"` leaves Session empty); a
multi-device syncer test carrying the session through convergence; spool
per-session dedup; hub round-trip, cross-device forge, query contract and
non-enumeration; db_conformance on file, sqlite AND postgres; runs.ts
grouping incl. legacy fallback; a Playwright spec on the seeded run card.

web/docs/src/content/docs/guides/what-agents-read.md

@@ -47,6 +47,30 @@ lens — four views:
   spotting an agent that never discovered the folder at all, which usually means
   a missing [root pointer](/guides/shared-agent-memory/).
 
+## One session, read and written
+
+History groups an agent session's changes into a single **run card**. The card
+also shows what that session *read*: files it read before changing them are
+marked, and files it read without touching at all get their own **Read, not
+changed** list underneath.
+
+That's the question the heat map alone can't answer — *when my agent answered,
+what did it actually look at, and was it the current version or the retired
+one?*
+
+Two things worth knowing:
+
+- Reads are shown only for files the project still has. A file a run read and
+  then deleted appears as a change with no read. The card says so on screen.
+- The join is on a session id the sync hook stamps, never on the run's note —
+  the note is free text anyone can set with `bdrive sync --note`, so joining on
+  it would let one person's changes attach to another person's card.
+
+Per-session detail is kept for 30 days by default
+(`reads.session_retention_days`, see [Hub config](/reference/hub-config/));
+after that the run card shows changes only. Read *counts* are unaffected — they
+come from the heat buckets, which have their own, much longer retention.
+
 ## Using it
 
 A few things this surfaces that are otherwise guesswork:
@@ -67,6 +91,13 @@ distinct-reader counts, and last-read times. **Never who read what.**
 already public via history. Human email addresses never appear in a heat
 response.
 
+A session id is treated the same way. It appears only in History, on the change
+that carries it, and is accepted as a `?session=<id>&device=<id>` filter
+**input** — both are required. Nothing enumerates sessions: no listing
+endpoint, no session column in heat output, nothing new in `?by=device`. And a
+session's reads are always recorded against the device the hub validated the
+report came from, so nobody can paint files onto a teammate's run card.
+
 Telemetry degrades silently: recording or flushing a read can never fail a
 request or a sync cycle.
 

web/docs/src/content/docs/reference/hub-config.md

@@ -63,7 +63,8 @@ cloud credentials on the serving machine.
   },
   "reads": {                         // read heatmap telemetry (hub mode)
     "enabled": true,                 // default true; aggregate counts only
-    "retention_days": 400            // daily buckets older than this fold into all-time totals
+    "retention_days": 400,           // daily buckets older than this fold into all-time totals
+    "session_retention_days": 30     // how long History's run cards keep per-session read detail
   },
   "database": { "driver": "sqlite", "dsn": "/var/lib/bdrive/hub.db" }
 }