feat(bridge): read Claude Code session records with helmet bridge read

[yia-mw-agent]

Closes #67 (child of #55).

Adds helmet bridge read --session ID [--transcript PATH] [--max-bytes N] for one Claude Code session. The reader streams saved JSONL and subagent records, retains records across compaction, drops thinking, verifies session IDs and supported versions, and uses exact-ID lookup. A partial final line is reported without discarding complete records.

Refs are full 32-hex UUID-derived identities independent of other records, timestamps, and presentation order. Multiple output blocks from one source UUID get deterministic distinct identities. Synthetic tests cover stable refs and resolved parent links through append, earlier/tied timestamps, partial-tail completion, subagent discovery/growth, and multiple blocks.

The JSON output reports coverage and omitted bytes. It preserves person prompts and assistant text, then excerpts and drops old tool results to meet the serialized-byte budget; protected-text conflicts produce the documented warning. Documented failures exit 2.

Updated from main dc99e4c, preserving its Codex MCP and observation changes. The repository updater synchronizes version 0.7.0 across the package and both manifests. Codex feature delivery remains owned by epic #53.

Validation: Captain ran 65 focused reader, public-boundary, and plugin-packaging tests successfully; independent CLI probes confirmed stable append refs, a 39,040-byte output under a 40,000-byte budget, accurate omitted tool-input bytes, and rejection of malformed text and unsupported versions. Version-policy check passes against main 0.6.0. All fixtures are synthetic. Claude Code mod CLI tests belong to #68; installed-host acceptance remains #73.

[timeleft--]

Reviewed 23ac0be against #67 and #55. The 54 focused reader, packaging and public-boundary tests pass, and the five required source checks are green. Additional synthetic CLI probes reproduced three contract failures, grouped inline: refs change after an append collision; the serialized summary exceeds its byte limit and some cuts are absent from coverage; malformed core content and an unsupported version on a skipped record are accepted as success.

Please repair these through the same PR, with CLI argv/stdout/exit-code regression tests. Keep fixtures synthetic and the reader read-only. Version synchronization remains a separate merge blocker: the current Version policy check fails while the Captain's no-touch instruction for .codex-plugin/plugin.json prevents the normal updater. Preserve that instruction and the existing checks during this repair.

[timeleft--]

Captain re-review of exact head 7c64147.

The serialization and format repairs pass. Independent public-CLI probes now return 38,987 stdout bytes under --max-bytes 40000, include 7,982 omitted bytes for clipped tool input, and reject malformed core text and unsupported versions on skipped records with exit 2. All 61 focused Python tests pass, and all five required source checks pass on this head.

The reference repair remains incomplete. read_session sorts by timestamp before _assign_refs allocates tokens. A synthetic public-CLI probe starts with one prompt whose ref is 4f1c2a9e, then appends an assistant record with a colliding UUID prefix and an earlier timestamp. Both reads exit 0. After refresh, the old prompt changes to 4f1c2a9e000000000000000000000001 and the appended answer receives 4f1c2a9e. An existing explanation can therefore cite the wrong record. No monotonic-timestamp requirement exists in #55. This also applies when partial tails or subagent records become visible between reads.

There is a contract conflict to resolve before further repair: #55 requires the shortest unique UUID prefix (at least 8 characters) and identical refs across appends, while the reader is read-only and has no persisted allocation. A future colliding UUID can invalidate a previously unique shortest prefix. The repair's exact-token allocation is a different interpretation and still depends on ordering. Do not silently weaken either requirement, introduce persistent collection, or change the accepted graph to work around this. No further code repair is requested until the reference contract is reconciled.

The repository Version policy is also still red: it requires 0.6.0 across the Python package and both manifests, while this track explicitly forbids modifying .codex-plugin/plugin.json. Preserve that exclusion and the check.

This exact-head checkpoint is blocked; it is not a merge approval.

[timeleft--]

Captain review of exact head 7c64147 under the updated #55/#67 reader contract.

The Captain has resolved both prior constraints. #55 now requires full 32-hex UUID-derived refs computed independently of other records and presentation order, with deterministic per-block identities when one source UUID expands into several output records. The shortest-prefix requirement is removed. Manifest updates required by the existing version updater are permitted, including .codex-plugin/plugin.json. The previous blocked review is superseded by this actionable repair request.

Replace the order-dependent prefix allocation with full stable record identities and use them for parentRefs. The current public-CLI append probe still reassigns 4f1c2a9e from an existing prompt to an appended earlier-timestamp assistant record. Add/adjust synthetic CLI regressions for stable refs and correct parents through earlier/tied timestamps, partial-tail completion, subagent growth/discovery, UUID-prefix collisions and multiple blocks. Preserve read-only operation, exact-session identity, full protected text, streaming and accurate output-budget/coverage behavior. The serialization and fail-closed repairs already pass the original independent probes and 61 focused tests; reuse unchanged evidence.

Run scripts/mw-version.py update/check against latest origin/main with this PR's actual title/body, synchronizing all configured versions. Re-run after main changes. Update the affected reader documentation and changelog to the full-ref contract and remove obsolete version-hold or prefix-allocation claims. Preserve version checks, Codex feature work and #53/#56–#61. Return the repair on this same worker PR.

[timeleft--]

Captain review of this exact head is clean against #67 and the updated #55 reader contract. The full 32-hex record identities now depend only on their own source UUID/block index, so earlier/tied timestamps, partial-tail completion, and subagent discovery/growth do not reassign existing refs. Resolved parent links and deterministic multi-block identities are covered by synthetic CLI tests.

Independent verification: 65 focused reader/public-boundary/plugin-packaging tests pass. CLI probes confirm stable append refs, 39,040 stdout bytes under a 40,000-byte limit, accurate omitted tool-input bytes, and unsupported-format failures for malformed text and an unsupported version on a non-core record. Existing compaction, exact-ID lookup, mismatch, thinking-drop and >4 MiB streaming coverage remains valid. Version-policy check passes against dc99e4c with synchronized 0.7.0; that main commit is included. The obsolete description claims were corrected as metadata only.

Required source checks for this head pass. Preview image-build status remains separate from source readiness. This review does not claim installed Claude Code host acceptance, which remains human-only #73.