WIP: feat(shell): per-session statistics module — integration tracker

[efirvida]

Integration PR — do not merge yet (draft)

This is the root of the per-session statistics module for issue #1583. The branch stays at the verified default branch and accumulates the review slices as they are approved, so the review really happens slice by slice and this PR is the integration record.

What this delivers

A self-contained per-session statistics module: what the session cost, what each subagent and each model cost, and where the time went — plus an hours report for people who bill.

• Canonical usage record, no coercion. A provider-reported $0 and an unreported value stay different states, for cost and now for tokens too; an unavailable value renders as unavailable, never as 0.
• Session cost total in the bar and header: orchestrator plus every subagent, with a + marker while the total is partial.
• Transcript reader and replay for parent and child sessions, streamed and bounded.
• Pure aggregation engine over session, subagent, model, agent-class and project totals, with provenance on every monetary, token and count figure.
• Timeline: per-turn model latency and per-tool duration by timestamp pairing, reported as median and p90 with the sample size, the parallel-batch artifact flagged, and the harness cd <cwd> && prefix normalized.
• Local opt-in JSONL store with bounded retention, DO_NOT_TRACK/CI opt-out, nothing ever transmitted.
• Versioned transport and exporters: gentle-shell.statistics/v1 on its own widget key, plus markdown/CSV/JSON rendered from the same aggregate.
• Overlay view and command: /gentle:statistics, with the panel reading a cached snapshot instead of recomputing per frame.
• Billable-hours report: hourly rate, currency, rounding policy and a date range, opt-in.

Review slices (27, in order)

#	Fork PR	What it delivers	Changed lines
1	efirvida#29	feat(statistics): add canonical SessionUsageRecord and nano-USD cost primitives	345
2	efirvida#30	fix(statistics): stop coercing unreported cost to zero at both ingestion sites	93
3	efirvida#31	feat(statistics): delegated-cost transport, publication and the bar total	318
4	efirvida#32	fix(statistics): clamp delegated counts, exact task cost, monotonic ordering	177
5	efirvida#33	feat(statistics): transcript reader — parse, classify and stream lines	281
6	efirvida#34	feat(statistics): transcript reader — enumerate sessions and join task identity	143
7	efirvida#35	test(statistics): cover the transcript reader fixtures	288
8	efirvida#36	feat(statistics): pure aggregation engine (totals, breakdowns, ratios, provenance)	324
9	efirvida#37	test(statistics): cover the aggregation engine, with a shared line stream	288
10	efirvida#38	feat(statistics): transcript timeline (segments, percentiles, parallel flags, idle)	366
11	efirvida#39	test(statistics): cover the timeline and ignore a start-only timing	217
12	efirvida#40	feat(statistics): local opt-in JSONL store with bounded retention	290
13	efirvida#41	test(statistics): cover the store opt-out, retention and round-trip	172
14	efirvida#42	feat(statistics): versioned RPC transport (schema, bounds, discard, coalescing)	250
15	efirvida#43	test(statistics): cover the transport encoder and publisher	156
16	efirvida#44	feat(statistics): markdown, CSV and JSON exporters, with the v1 contract docs	267
17	efirvida#45	test(statistics): cover the exporters and add the export golden files	335
18	efirvida#46	fix(statistics): redact absolute paths from tool commands in the payload	20
19	efirvida#47	feat(shell): statistics overlay view (model and width-aware renderer)	203
20	efirvida#48	feat(shell): statistics command, overlay wiring and palette row	214
21	efirvida#49	test(shell): cover the statistics view and command	264
22	efirvida#50	refactor(shell): make the statistics panel readable instead of technical	219
23	efirvida#51	feat(shell): billable hours report (config, rounding, pure report builder, collection)	313
24	efirvida#52	feat(shell): billable renderers, the gentle:billable command and tests	352
25	efirvida#53	test(shell): billable golden files, and fit the panel with the opt-in	313
26	efirvida#54	perf(shell): bound the billable collection concurrency and cover it	60
27	efirvida#55	fix(statistics): stop coercing unreported tokens to a measured zero	244

Why the slices live in the fork

GitHub requires a PR's base branch to exist in the destination repository, so with read-only access here the nested chain could not be opened on this repository. Each slice is ≤400 changed lines and keeps its tests and docs with the unit they verify.

Integration

Once the chain is reviewed, the fork tracker branch (upstream/statistics-tracker) carries the integrated result and this PR's diff becomes the whole feature. Because that diff exceeds 400 changed lines, this PR would need the repository's size:exception route at that point — the review has already happened slice by slice.

The architecture, data catalog and settled decisions are in issue #1583 and its epic.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[efirvida]

Hi — a short note from my side, and a question, because I'd rather not assume.

This is the draft tracker I opened for the work in #1583. I split the change into 27 PRs in my fork (efirvida/gentle-shell #29–#55) so each piece stays small enough to review comfortably, and each one builds on the previous. This branch stays at main and would grow as they're approved, so the real review happens in the fork slices — this PR is only the integration point, not the review surface.

While doing that I realised I'd probably gotten part of the process wrong, and I'd appreciate your help with it:

• I believe the linked issue is meant to carry status:approved before a PR links it, and feat(shell): per-session statistics module — cost, tokens, time and a billable report #1583 is still at status:needs-review. I held off linking it, but I'm honestly not sure that was the right call.
• My branch names (upstream/statistics-…) don't match the ^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$ rule in skills/branch-pr. That one is on me, and I'll rename them to whatever you prefer.
• I also ran into this: chained PRs can't be based on fork branches, because GitHub wants the base branch to live in the destination repository. So I couldn't open the 27 slices here at all, and they ended up in my fork.

So I'm a bit stuck on what you'd prefer, and I'd rather ask than guess:

• one PR here with size:exception, with the fork slices linked so you can still review them one at a time?
• or would you rather create the chain branches here (or give me push access) so the slices arrive as normal PRs, reviewed in order?
• or is 27 too many? I can regroup them into fewer, larger ones — I'd just rather not trim tests or docs just to hit a number.

Thank you, and sorry for the extra noise. The fuller context is in #1583.

[efirvida]

Pulling this tracker back while the per-session statistics module is still under active development. I will reopen it (or a replacement tracker) once the module is in a reviewable state. No impact on main.