feat(trace): add safe local trace reader

[OnlineChef (ChefGroep)]

Summary

Adds a local read-only CLI for the trace store introduced by #298.

This PR is intentionally stacked on feat/trace-store / #298. It does not add a management API, remote trace access, capture coverage, or any new persistence format.

Commands

ocx trace list
ocx trace list --conversation <conversation-id> --limit 20
ocx trace list --json

ocx trace show <trace-id>
ocx trace show <trace-id> --json
ocx trace show <trace-id> --body
ocx trace show <trace-id> --body --json

The proxy does not need to be running; the reader opens the local trace.sqlite store directly.

Privacy boundary

Payloads remain opt-in at the read boundary:

• trace list is metadata-only.
• trace show <id> is metadata-only.
• --json changes format only and still omits inbound/outbound/response bodies.
• Bodies are included only with explicit --body.
• Human output escapes dynamic metadata and stored bodies so terminal control sequences from traced content are not executed.
• No management/API endpoint is added.

Metadata-only trace summaries that were never body-persisted remain in usage.jsonl; ocx trace list enumerates body-backed rows present in trace.sqlite.

Implementation

• new src/cli/trace.ts command module
• top-level CLI dispatch + help entry
• CLI reference documentation
• focused privacy, filtering, body-opt-in, terminal-escape, and invalid-input tests

Verification

Exact head 331a38df810a20dc77bdc4d8e03472bcc770d219:

• bun run typecheck ✅
• focused trace + CLI trace tests: 23 pass, 0 fail ✅
• full repository suite: 7032 pass, 11 explicit skips, 0 fail across 524 files ✅
• 34,932 assertions ✅
• bun run privacy:scan ✅
• git diff --check ✅

The 11 skips are existing environment/capability skips, not introduced by this PR.

Dependency

Stacked on #298. Merge/rebase this only after the trace-store parent lands.

[OnlineChef (ChefGroep)]

CodeRabbit (@coderabbitai) review

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 26 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: GroepOnline/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: c566e4a6-1de5-420d-8096-2ec9bda21719

📥 Commits

Reviewing files that changed from the base of the PR and between faeaa19 and 331a38d.

📒 Files selected for processing (5)

• docs-site/src/content/docs/reference/cli.md
• src/cli/help.ts
• src/cli/index.ts
• src/cli/trace.ts
• tests/cli-trace.test.ts

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

---

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

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.