feat(trajectory): tester-facing bug report flow in raven trajectory

[forrestjgq]

Summary

Tester-facing bug report flow inside the raven trajectory browser
(and a scriptable report-bug subcommand): pick an attempt, type a
one-line description, confirm once, and get a stable report id with a
local shippable package.

Key decisions, in the order the phases landed:

• Two artifacts. A machine-local record.json (lifecycle: draft
  -> local_ready | retryable failed, crash recovery for interrupted
  drafts, 26 structural invariants on load) and the only exportable
  artifact <report-id>.tar.gz - sanitized problem metadata plus an
  embedded Trajectory Report in its existing layout. Everything the
  package will contain is frozen under snapshot/export/ (tree digest,
  verified before and after every tar run) before the confirmation
  screen, so the text the user approves, the first packaging run, and
  any retry use the same bytes.
• Safety gates. User input goes through the same known-value /
  pattern / residual redaction as the trajectory; the merged signals
  classify the report as clean (one confirmation), needs_review
  (separate authorization; --yes never implies it), or blocked
  (private-key hit; no flag can bypass it). Two sanitization layers
  strip absolute paths (generic POSIX/Windows/UNC token parser shared
  with the pre-export assertions), tar member headers are anonymized on
  both layers, and RAVEN_BUGREPORT_REQUIRE_REVIEW adds an
  organization-policy review trigger.
• Completeness that cannot drift. The deliverable tree is judged by
  an offline warn-mode mock replay probe plus explicit contract checks
  (validate_recording, corrupt span lines, format version), mapping to
  complete/degraded/unreplayable with reasons; unexplained probe
  failures degrade to unknown instead of masquerading as evidence
  damage. The probe runs with a new rates_offline() context so no
  pricing/catalog/vision-warm path can reach the network.
• Compatibility. raven trajectory report (including --yes) and
  every existing browser action keep their exact behavior and outputs;
  the new flow writes only under <trace-state>/bugreports/. All new
  functions (member_traces, classify_redaction, the sanitizer set,
  evaluate_completeness, diagnose_history_cut, validate_recording,
  rates_offline) are pure additions.

Two pre-existing gaps found and fixed along the way: the sanitizer's
placeholder path for missing artifacts made delivered trajectories fail
load_recording, and mock replays could fire OpenRouter/LiteLLM
catalog fetches.

Type

• Fix
• Feature
• Docs
• CI / tooling
• Refactor
• Other

Verification

• uv run pytest tests/test_trajectory_bugreport.py tests/test_trajectory_completeness.py tests/test_cli_trajectory_browse.py tests/test_cli_trajectory_commands.py tests/test_provider_rates.py tests/test_token_wise_pricing.py tests/test_trajectory_replay.py - all green (about 240 new tests among them)

• uv run pytest - 7090+ passed; the 11 failures + 20 errors are the
  pre-existing baseline (cron/everos/theme/tracing/config_loader),
  reproduced identically on a clean worktree of the base commit

• uv run ruff check . and uv run ruff format --check . - clean

• make check-large-files - clean

• Relevant tests pass locally

• Relevant lint / type checks pass locally

• User-facing docs or screenshots are updated when needed
  (CONTEXT.md domain terms; command help texts are the user docs)

Risk

• Security impact considered (the whole feature is an export gate:
  redaction classification, path sanitization, header anonymization,
  pre-export assertions; expert trajectory report --yes deliberately
  keeps its existing semantics)
• Backward compatibility considered (existing commands, browser
  actions, and store file protocols unchanged; covered by the
  pre-existing suites plus explicit regression tests)
• Rollback path is clear for risky changes (revert the branch; the
  only persistent state is the new <trace-state>/bugreports/
  directory, which older builds simply ignore)

Related Issues

N/A

[gloryfromca]

No blockers; this can merge as far as I am concerned, with two nonblocking correctness notes below.

I covered the repository rules in AGENTS.md/CLAUDE.md and the canonical trajectory terms in CONTEXT-MAP.md/CONTEXT.md; the complete target diff; the affected CLI, store, replay, pricing, sanitization, packaging, recovery, and report-list callers; relevant history; backward compatibility; and the changed tests for weakening (none found). I also checked the export/privacy, frozen-snapshot, state-machine, retry, offline-replay, and no-real-tool architecture constraints.

Verification: uv run pytest tests/test_trajectory_bugreport.py tests/test_trajectory_completeness.py tests/test_cli_trajectory_browse.py tests/test_cli_trajectory_commands.py tests/test_provider_rates.py tests/test_token_wise_pricing.py tests/test_trajectory_replay.py reported 447 passed in 16.02s, then the process exited 139 during teardown. To refute this as a branch regression, I ran the unchanged tests/test_trajectory_replay.py at the exact base commit 53532eb740d8; it likewise reported 31 passed and then exited 139, so the teardown crash is reproducible on the target baseline.

[gloryfromca]

Nonblocking: The required-description loop accepts any truthy string, so an entry containing only spaces proceeds through freeze_export and can land a report whose required description is visually blank. The scriptable command already strips before validating; the interactive path should apply the same empty-after-trimming rule.

[forrestjgq]

Fixed in 371a4e4: the interactive prompt (and freeze_export itself) now trims before the emptiness check, so a spaces-only entry reprompts; the existing reprompt test gained a spaces-only step and a data-layer test asserts freeze_export rejects whitespace-only descriptions.

[gloryfromca]

Confirmed on 371a4e4: both the interactive prompt and the data-layer guard trim before validation, and the regression tests cover spaces-only input. This resolves the finding.

[gloryfromca]

Nonblocking: new_report_id contains only the UTC date plus a random suffix, so reverse lexicographic directory order is random among reports filed on the same day. That makes the documented/UI newest first ordering wrong in the common case of multiple same-day reports; order the validated records by created_at (with a deterministic tie-breaker) instead.

[forrestjgq]

Fixed in 371a4e4: list_reports now sorts by the recorded created_at with the report id as a deterministic tie-breaker, instead of directory-name order; covered by a test with two same-day reports whose lexicographic id order contradicts creation order.

[gloryfromca]

Confirmed on 371a4e4: list_reports orders validated records by created_at with report_id as a deterministic tie-breaker, and the contradictory same-day IDs test covers the original failure. This resolves the finding.

[gloryfromca]

No blockers; this revision can merge as far as I am concerned, with the two previously posted nonblocking notes still open.

The new delta is test-only: it splits the fake PEM marker in three fixtures so the source scanner does not mistake it for a real key. I verified all three expressions still produce the exact original runtime value, and the affected blocked-classification tests still exercise that value. No production behavior, public API, package format, or architecture boundary changed. I rechecked the full target diff status and the delta against AGENTS.md/CLAUDE.md, the trajectory domain terms, affected test callers/history, backward compatibility, and test weakening; the new comment explains the necessary hook constraint in English.

Verification: uv run pre-commit run detect-private-key --files tests/test_cli_trajectory_browse.py tests/test_cli_trajectory_commands.py tests/test_trajectory_bugreport.py passed. uv run pytest tests/test_cli_trajectory_browse.py tests/test_cli_trajectory_commands.py tests/test_trajectory_bugreport.py reported 298 passed in 6.92s, then exited 139 during process teardown. This is the same teardown failure already reproduced at the exact target base in the prior review, not a new failure from this test-only delta.

[gloryfromca]

No blockers; this revision can merge as far as I am concerned.

Both previously reported nonblocking issues are resolved: whitespace-only descriptions are rejected at the interactive and data-layer boundaries, and reports are ordered by recorded creation time with a deterministic report-id tie-breaker. I found no new issues.

I reviewed the 371a4e4 fix delta in the context of the full target-branch diff, its affected interactive and scriptable callers, report-list consumers, and relevant history. I also rechecked AGENTS.md/CLAUDE.md and the context map, backward compatibility, architecture boundaries, and that the regression tests strengthen rather than weaken existing coverage. git diff --check 08509fc1b1a9..HEAD passed. The three focused regressions passed (3 passed). The broader affected run completed all assertions (300 passed) and then exited 139 during pytest teardown, matching the pre-existing environment teardown crash established on the target baseline in earlier rounds.

[forrestjgq]

Base changed to main as requested. The diff now also carries the 5 trajectory-browser UX commits from #379 that this branch is built on; once #379 merges, this PR's diff shrinks to the bug report work automatically (or if this one merges first, #379 becomes empty and can be closed).

[gloryfromca]

The automatic-shrink assumption no longer holds now that #379 was squash-merged. The live main comparison is still 23 commits ahead / 1 behind with 19 changed files, and git merge-tree --write-tree HEAD github/main reports content conflicts in raven/cli/trajectory_browse.py and tests/test_cli_trajectory_browse.py. The branch needs to be updated against current main before GitHub can merge it.

[gloryfromca]

Blocking: this branch does not merge cleanly into current main after #379 was squash-merged; see the base-update note.

The automatic-shrink assumption is false for the retained pre-squash commit ancestry. The live comparison remains 23 commits ahead and 1 behind with 19 changed files, and git merge-tree --write-tree HEAD github/main reports conflicts in raven/cli/trajectory_browse.py and tests/test_cli_trajectory_browse.py. Under the fourth-round standard, this revision retains the ancestry that introduces the conflict relative to current main, every ordinary merge attempt reaches it, and the operator has no working merge path until the branch is updated.

I refreshed and reviewed github/main...HEAD, isolated the effective tree delta from the now-base-identical #379 UX changes, and checked the relevant history, callers, backward compatibility, tests for weakening, architecture boundaries, AGENTS.md/CLAUDE.md, and the context glossary. No new code-level findings emerged, and both earlier bug-report findings remain resolved. Both live-base diff checks passed.

Tests: the effective bug-report suites completed 302 assertions successfully, then the pytest process exited 139 during the previously established teardown crash. The UX/theme run reported 168 passed and 1 failed (test_bold_accent_renders_styled_not_bare); its source and test files are identical to current main, so that failure is pre-existing and out of scope.

[gloryfromca]

No blockers; this can merge as far as I am concerned.

The prior integration blocker is resolved: this revision is based directly on squash-merged main, git merge-tree --write-tree HEAD github/main succeeds, and its tree is byte-for-byte identical to the previously reviewed clean revision. Both earlier bug-report findings remain fixed, and I found no new issue.

I reviewed the immutable github/main...HEAD comparison (SHA-256 e45f9fcdf74f52fb2a71318fb86a1eaf1b71473a09675b65d79ab018953ef379) and rechecked the project rules, full diff, relevant callers and history, backward compatibility, architecture and confidentiality boundaries, and tests for weakening. Risk assessment: high impact if the redaction/export boundary were wrong, low regression likelihood, partial regression protection because of the known teardown crash, managed recovery, and moderate confidence; recommendation is merge with human review.

Exact-head validation in an isolated offline checkout: the three focused regressions passed. The broader affected run completed all 302 assertions, then the interpreter exited 139 during the previously established teardown crash. Diff checks and the dry-run merge passed.