feat: preflight telemetry capture loop pieces 1–4 (#65)

[Knapp-Kevin]

Summary

First slice of issue #65 — local-only, default-off capture loop that records bicameral.preflight events plus downstream tool engagement, attributable per-call via a new preflight_id. Used for self-triage of false fires / silent misses; never leaves the machine and is not part of the existing PostHog relay path.

This PR covers pieces 1–4 only. Pieces 5 (SessionEnd reconciliation skill) and 6 (triage CLI) are deferred to follow-up plans #65-pt2 and #65-pt3.

Architecture

                        bicameral.preflight (handler)
                                  │
                                  │  generates preflight_id (UUIDv4)
                                  │  when BICAMERAL_PREFLIGHT_TELEMETRY=1
                                  ▼
        ┌───────────────────────────────────────────────────┐
        │  preflight_telemetry.py    (NEW, top-level)       │
        │                                                    │
        │  Piece 1 — salt + hash                             │
        │    _get_or_create_salt()  →  ~/.bicameral/salt    │
        │      O_EXCL race-safe; FileExistsError fallback    │
        │      reads winner's bytes  ◀── audit MF1 inline    │
        │    hash_topic / hash_file_paths  → 16 hex chars   │
        │    new_preflight_id()  → UUIDv4                    │
        │                                                    │
        │  Piece 3 — writers                                 │
        │    write_preflight_event  → preflight_events.jsonl │
        │    write_engagement       → engagements.jsonl     │
        │      explicit | fallback (subset-match)            │
        │                                                    │
        │  Piece 4 — retention                               │
        │    _maybe_rotate  → 50 MB / 30 days, keep last 5  │
        │      os.replace (atomic Win + POSIX)               │
        └───────────────────────────────────────────────────┘
                                  │
                                  │  Piece 2 — preflight_id plumb-through
                                  ▼
   PreflightResponse ───── preflight_id: str | None ────────┐
   LinkCommitResponse ──── preflight_id: str | None ────────│
   BindResponse ────────── preflight_id: str | None ────────│
   RatifyResponse ──────── preflight_id: str | None ────────│
   update.py dict returns  preflight_id key (11 sites) ─────┤
                                                            │
   server.py inputSchema ──── optional preflight_id ────────┘
   for: preflight, link_commit, bind, update, ratify

Privacy stance

• Opt-in. Default OFF. Set BICAMERAL_PREFLIGHT_TELEMETRY=1 to capture; unsetting it makes every writer a no-op.
• Hashed by default. Topic and file_paths are 16-char salted SHA-256 prefixes. Set BICAMERAL_PREFLIGHT_TELEMETRY_RAW=1 to additionally store plaintext — separate, explicit opt-in.
• surfaced_ids are written raw. Opaque ledger decision_id strings, already non-PII; hashing them would defeat the only useful triage join. Documented as an invariant in the module docstring (audit S1).
• Local-only. Files live under ~/.bicameral/, mode 0o600. Never leaves the machine. Separate path from the PostHog relay in telemetry.py.
• Bounded retention. 50 MB rolling cap per file; 30-day mtime ceiling; keep last 5 rotations.

Test results

$ python -m pytest tests/test_preflight_telemetry.py tests/test_preflight_id_plumbing.py -v
================== 28 passed in 2.86s ==================

$ python -m pytest tests/test_phase2_ledger.py tests/test_phase3_integration.py -q
================== 22 passed in 18.57s ==================

Pre-existing collection failures in test_v055_region_anchored_preflight.py and test_v0412_preflight.py (refer to old preflight internals: _merge_decision_matches, _has_actionable_signal_in_search) are unchanged on this branch — they fail on origin/dev unmodified. Verified via git stash round-trip.

Audit reference

Plan: plan-preflight-telemetry-65.md in the parent worktree.

Audit verdict: PASS with MF1 applied inline.

• MF1 (must-fix). _get_or_create_salt wraps the os.O_EXCL os.open in a try/except FileExistsError and falls back to _SALT_FILE.read_bytes() on the race-loser path. Two dedicated tests (test_salt_race_loser_reads_winner_bytes, test_salt_race_loser_handles_exclusive_failure) exercise the path including a synthetic race injection via monkeypatch.setattr(os, "open", flaky_open).
• S1 invariant (surfaced_ids written raw) — documented in preflight_telemetry.py module docstring.
• S3 update.py return-site count — verified by grep: 11 dict returns inside handle_update, all carry preflight_id.

Out of scope (tracked separately)

• Piece 5 — SessionEnd reconciliation skill (#65-pt2). Reads the JSONL files, classifies entries as suspected_miss / suspected_false_fire / normal, writes failure_review.jsonl.
• Piece 6 — Triage CLI + redaction (#65-pt3). bicameral-mcp triage CLI for labeling failure rows; promotion to tests/eval/real_dataset.jsonl requires explicit redaction.

Test plan

• All Phase 1 unit tests pass (salt, hash helpers, env gates)
• All Phase 2 plumb-through tests pass (preflight, link_commit, bind, ratify, update)
• All Phase 3 writer tests pass (event, engagement, raw mode, fallback attribution)
• All Phase 4 rotation tests pass (size, age, keep-last-N)
• MF1 race-loser path exercised by dedicated test
• Existing phase2 + phase3 regression suites pass
• No new dependencies introduced

Closes

Closes #65 (pieces 1–4 only — pieces 5–6 tracked separately as #65-pt2 and #65-pt3).

🤖 Generated with Claude Code

[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: c08a0613-9715-434c-b3f1-031c6ddc610a

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.}