feat: local telemetry counters + usage_summary + first-boot consent (v0.14.0)

[Knapp-Kevin]

Summary

Privacy-first observability foundation. Adds a local-only counter sink alongside the existing network relay, the bicameral.usage_summary MCP tool that reads from it, and a non-blocking first-boot notice so users see the telemetry policy on the first boot of an upgraded binary.

Issue	Fix
#39	New local_counters.py — append-only JSONL at ~/.bicameral/counters.jsonl. No network egress. Mode 0o600 on POSIX.
#42	New bicameral.usage_summary MCP tool — aggregate counts/percentages over N days.

Depends on

This PR targets dev and assumes #94 (chore: merge main into dev) lands first. The integration site is telemetry.send_event (introduced on main in v0.12.0); without #94 dev would still call the older record_event and the wiring would not match.

Architecture

       Tool call
           │
           ▼
   telemetry.send_event ──┬──► local_counters.increment(skill_name)   (always)
                          │       └─► ~/.bicameral/counters.jsonl  [0o600]
                          │
                          └──► consent.telemetry_allowed()? ─yes─► relay POST
                                       │                             └─► PostHog
                                       └─no─► (suppressed, counter still wrote)

consent.telemetry_allowed() is the single source of truth: returns True when env BICAMERAL_TELEMETRY != "0" AND (marker missing OR marker.telemetry == "enabled"). Missing marker preserves default-on for upgraders who haven't seen the notice yet.

First-boot notice (non-blocking)

server.serve_stdio calls consent.notify_if_first_run() once at startup. The notice fires on first boot of an upgraded binary (no marker, or stale policy_version), surfaces via:

• stderr (always)
• MCP notifications/message (when an active session is available — surfaced by harness like Claude Code)

After emit, the marker is stamped (acknowledged_via="first_boot_notice", policy_version=1) so the notice does not repeat. If telemetry policy ever changes, bumping POLICY_VERSION re-fires the notice for everyone.

Server is never blocked — notify_if_first_run is best-effort, wrapped in try/except. Marker write failure logs at debug and continues.

bicameral.usage_summary (#42)

Returns the schema specified in the issue:

{
  "period_days": 7,
  "ingest_calls": int,        # from local counters
  "bind_calls_total": int,    # from local counters
  "decisions_ingested": int,  # from ledger
  "decisions_ungrounded": int,
  "decisions_pending": int,
  "decisions_reflected": int,
  "decisions_drifted": int,
  "reflected_pct": float,
  "drift_pct": float,
  "cosmetic_drift_pct": float,
  "error_rate": float,
}

Privacy: aggregates only — no event rows, no session IDs, no user content.

Wizard hard-fail

setup_wizard._select_telemetry now writes the consent marker on every answer (interactive or auto-yes). On marker write failure (OSError from disk full / RO home / permission denied), the wizard exits non-zero — guarantees a "no" answer never silently leaves telemetry on.

Test plan

• tests/test_local_counters.py (7 tests) — file creation, append, aggregation, network independence, concurrent writes, env kill-switch
• tests/test_consent_notice.py (12 tests, 1 skipped on Windows) — telemetry_allowed() predicate truth table, marker shape, file mode, notice emit/suppress/re-fire, env-var skip, write-failure swallow, relay blocked when consent disabled
• tests/test_usage_summary.py (5 tests) — zero-days short-circuit, decision aggregation, cosmetic_drift_pct, empty ledger, tool-call counts from local file
• tests/conftest.py — session-scoped autouse fixture isolates ~/.bicameral/ to tmp dir; stdlib only
• CI: BICAMERAL_SKIP_CONSENT_NOTICE: '1' added to test job env

PR-B total: 23 pass, 1 skipped (POSIX-only file mode test on Windows host).

Closes

Closes #39
Closes #42

🤖 Authored via QorLogic SDLC (plan → audit → implement → substantiate).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 57b61fd1-c6de-4529-8b42-56e3b6a71276

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[Knapp-Kevin]

Rebased onto current dev HEAD — bf71c03 → 895f8a3 (force-pushed with --force-with-lease). Reviewers, please re-fetch.

What changed

• Dropped the local merge commit 21d4945 ("chore: merge main into dev — bring telemetry refactor onto dev") — it's been superseded by the official PR chore: merge main into dev (v0.13.3 telemetry refactor → dev) #94 merge already in dev (e3d066d).
• Replayed only the feature commit bf71c03 (telemetry counters + usage_summary + first-boot consent) onto dev HEAD.
• No content conflicts during rebase — git applied the feature cleanly. Triaged a local pytest run that flagged 11 failures, but they reproduce on plain upstream/dev and trace to my polluted local Python env (a venv from an unrelated project). CI on dev is green for the same HEAD via docs: development cycle reference + demos/guides/training scaffolding #93, docs(backlog): B5 — event-sourced ledger RFC (tracks #97) #98, feat: CodeGenome Phase 4 (#61) — semantic drift evaluation in resolve_compliance (M3) #91, so the rebased branch is no worse than baseline dev.

Status against DEV_CYCLE.md rules

• Mergeable: yes (was CONFLICTING, now clean).
• CI: re-triggering on the new HEAD; awaiting green.
• Review tier: this PR introduces a first-boot consent flow + telemetry counters → risk:L3 (privacy-touching). Per DEV_CYCLE.md §4.4, requires a second reviewer + a security-pass note. Will add the security-pass note to the PR description once a reviewer is assigned.
• Skill files: any tool added or response field changed in this PR needs the matching pilot/mcp/skills/<tool>/SKILL.md update in the same commit (CLAUDE.md skill rule). Will verify and amend if needed before requesting the second review.

Not self-merging — flagged here to surface that the rebase is done and the PR is unblocked, but the L3 review tier still applies.