Design: session hub — live session dashboard + wrapup session report

1. Context and goals

obot.agent v0.1.0 (released 2026-07-11) gave working sessions a full lifecycle — session-init opens, five skills capture state along the way, session-wrapup closes into a diary entry — and the lead/sibling spawn pattern made sessions multi-agent operations: the 07-11 sessions ran four to five concurrent named agents. What v0.1 did not ship is a way to see a session. Mid-session state lives in files designed for agents (scratchpad, state.json, memory), and the operational picture at wrapup is reconstructed from transcripts and then discarded.

#24 closes that gap with a read-only static generator that renders one self-contained HTML page from the sources the session framework already maintains — a live dashboard during the session, and at wrapup the same view frozen into a session report published on the hub and linked from the diary entry. The reports double as keynote material for the R/Pharma 2026 diary narrative (#22, #10). Goals, in priority order:

• Answer “where are we?” at a glance, all session long, without asking an agent to re-render anything.
• Freeze each session's operational record into a durable, linkable report — no more reconstruct-and-discard.
• Add exactly one new capture channel (## Scaffold); everything else is render-only. No new state stores, no sync drift.
• Ship as the headline of obot.agent v0.2, alongside the session skills it visualizes.

2. Where the data already lives — verified inventory

Every input was verified against live data on 2026-07-11. Pinned fields are the parse contract (§4).

Not available (and therefore out of scope for v1, §9): per-session cost in USD. The statusline stdin JSON carries cost.total_cost_usd, but it is push-based, render-time-only, and interactive-only — there is no persisted per-session cost store. state.json → tokens is exact and persisted, so tokens are the v1 effort metric; a cost estimate (tokens × model rates, model from respawnFlags) is a cheap follow-on once wanted.

3. Prior art absorbed: the session-orchestration proposal

The session-orchestration proposal (2026-07-04) designed the same territory before the session skills existed, and left four decisions open. Events resolved most of it; #24 absorbs the remainder. Disposition, decision by decision:

Applied with sign-off (2026-07-11): the 2026-07-04 report now carries a status note (“absorbed by #24”) at the top of its README and page — annotated, per hub convention, never deleted. That closes the “session-orchestration D1–D4” item that had ridden the decisions backlog since 07-04.

4. Architecture — one generator, three collectors, two modes

A single zero-dependency Node script, tools/session-hub/session-hub.mjs, shipped in obot.agent (the versioned home of the session skills it visualizes; same layout precedent as the hub's scripts/render_diary.mjs). No server, no npm installs, no runtime state of its own.

collect                       normalize                render
───────                       ─────────                ──────
jobs/*/state.json   ─┐
claude agents --json ┼──►  session model (JS object) ──►  one self-contained HTML file
scratchpad sections  ┤     · session identity + boundary      · live:   .claude/session-hub/live.html
memory + last diary  ┤     · agents[] (pinned fields)         · report: obot.roadmap/reports/sessions/
gh sweep (cached)   ─┘     · priorities/todos/notes/scaffold            YYYY-MM-DD[-N].html
                           · roadmap events since start

• Collectors are independent and fallible. Each returns either data or a degradation notice; a collector failure (missing file, renamed field, gh offline) renders as a per-panel notice line, never a crash. The state.json parser pins exactly the fields in §2 and treats everything else as opaque.
• Session boundary (D4): the session starts at the newest <!-- session-init … --> marker in today's scratchpad; agents in scope are jobs under the workspace cwd with updatedAt ≥ start (plus anything still running); the gh sweep filters updated ≥ start. Fallback when no marker exists: local midnight.
• The gh sweep is cached (.claude/session-hub/cache/gh-sweep.json, ~5-minute TTL) so a 60-second regenerate loop doesn't hammer the API; the panel shows the sweep's timestamp. Gilead-BioStats repos are excluded (SAML-blocked API).
• Live mode (D1): --watch regenerates on an interval (default 60 s) to .claude/session-hub/live.html in the workspace (not a git repo — nothing to ignore); the page auto-refreshes and is read in Chrome from file://.
• Report mode (§6): --report runs the same pipeline once, freezing live panels into outcomes, and writes into the hub for publication.
• Visual system: the mockup's — keynote-adjacent warm palette, light/dark via prefers-color-scheme, all CSS inline. Alignment with the shared keynote stylesheet (obot.agent#15) once that lands.

5. Panels — the render contract

Exactly the mockup's inventory; each panel header names its source on the page itself, so the dashboard doubles as documentation.

6. Report mode and the diary

At wrapup, session-hub.mjs --report renders the final state with report semantics: the mode pill flips, the banner becomes an outcome strip, agents show final results (output.result), durations and total tokens, priorities show final check-state, and roadmap activity becomes the session's definitive event timeline. Output: obot.roadmap/reports/sessions/{slug}.html, where the slug mirrors the diary entry (2026-07-11, 2026-07-11-2, …) — one report per diary entry, forever paired.

Diary integration (D2) is link-first: the wrapup commits the report and adds one line to the diary entry (“📊 Session report” under the meta block). That needs zero changes to render_diary.mjs — a Markdown link renders as-is. Promoting the report to a proper tab on the diary page (and a chip on the diary index) is a contained render_diary.mjs follow-up, filed as its own small hub issue, not blocking v0.2.

7. Session-skill changes (obot.agent)

• session-wrapup gains a report step: render --report, commit to reports/sessions/, link from the diary entry (rides the existing diary commit under the standing hub grant). Its scaffold-review step (step 3) becomes a sweep of the ## Scaffold list instead of end-of-session recall.
• session-scaffold (new, D3): a thin capture skill mirroring session-note — trigger “scaffold: …” / “add that to the scaffold list” — appending to ## Scaffold in the scratchpad. Continuous-improvement candidates get captured when the friction happens, not reconstructed at wrapup.
• session-init: no functional change (the <!-- session-init … --> marker it already writes becomes the session-boundary anchor, D4); its scratchpad skeleton adds the empty ## Scaffold section, and its kickoff summary mentions the dashboard command.
• Docs: tools/session-hub/README.md (usage, data contract, degradation behavior); terminology stays aligned with docs/terminology.md (the Agents panel shows sessions — the lead and spawned agents; subagents are invisible by design, they have no session state).

8. Decisions Resolved 2026-07-11

Carried from the issue's Design placeholder; each was presented to @jwildfire with a recommendation as the gate on this design. All four resolved 2026-07-11 — recommendations accepted as written.

9. Out of scope

• Answering needs-input from the page (the old orchestration D2) — the dashboard is read-only; relay/answer flows belong to #18.
• Cost in USD — no persisted per-session cost source exists (§2 note); tokens are the v1 metric, model-rate estimation a follow-on.
• Cross-session analytics — reports accumulate under reports/sessions/; trends, token/cost rollups, and keynote-cut visualizations are a later requirement once a few weeks of reports exist.
• Autonomous regeneration/publishing — v1 is interactive-local; an unattended lane that regenerates and publishes belongs to #18.
• Replacing claude agents / the agents TUI — the hub is a workspace-level view, not a process manager.

10. Risks

11. Acceptance criteria

1. Live: one command from the workspace renders every §5 panel from a real session's data; opened in Chrome from file://, check-states, agent states, and token counts match the underlying sources at render time; the watch loop keeps it current unattended.
2. Degradation: removing a pinned state.json field, an entire scratchpad section, or network access still yields a rendered page with per-panel notices — no crash, no blank page.
3. Report: a real session's wrapup produces reports/sessions/{slug}.html, committed to the hub, linked from that day's diary entry, live on the Pages site — the first exemplar being the session that implements this.
4. Scaffold channel: “scaffold: …” lands in ## Scaffold, shows on the dashboard, and the wrapup sweep processes the list.
5. Footprint: no new state stores beyond the ## Scaffold section; roadmap activity remains derived + cached, never committed.

12. Task preview — the obot.agent v0.2 milestone

Decomposed via requirement-tasks into linked sub-issues after design sign-off — this preview is for shape and sizing only. #24 is the driver requirement for the obot.agent v0.2 milestone.