fix(review): export frozen context for historical lineages

[EstebanCabreraArbizu]

Pre-flight Checklist

• I have searched existing issues and this is not a duplicate.
• I understand that PRs will be rejected if the linked issue does not have status:approved.

📝 Bug Description

Gentle AI v2.2.0 can create a reviewing compact-v2 lineage with frozen candidate context required by a bound reviewer. If a later non-mutating authority recovery makes that lineage no longer apply to the live target, the historical lineage remains intact but the reviewer can no longer obtain its exact frozen context through a documented read-only command.

The transaction state preserves the relevant trees and paths, but it does not expose the native base64 context payload required by the reviewer. Reconstructing a diff with Git is not a safe substitute for the canonical frozen bytes.

This is distinct from #1710. That issue concerns bounded frozen-context transport across restart. This report concerns read-only recovery of the original frozen context after a historical lineage becomes unrelated to the live target.

🔄 Steps to Reproduce

1. On Windows with OpenCode and Gentle AI v2.2.0, create a compact-v2 review for a candidate.

2. Record the returned <lineage> and <target> while the review is in reviewing state.

3. Confirm that the reviewing lineage includes frozen candidate context required for a reviewer.

4. Perform a later non-mutating authority recovery that leaves the historical lineage intact but makes it no longer apply to the live target.

5. Run:

   gentle-ai review status --lineage <lineage> --next-transition

6. Observe applicability: unrelated and that the response no longer includes candidate_diff or changed_path_manifest.

7. Attempt to obtain the original frozen candidate context through documented read-only review commands.

✅ Expected Behavior

A documented read-only command, such as the following or an equivalent, should export and verify the exact original frozen reviewer payload for an intact historical lineage:

gentle-ai review inspect --lineage <lineage> --export-context

The command should return the original canonical payload without restarting the review, mutating authority state, allocating a new lineage, or requiring reconstruction from the live target.

❌ Actual Behavior

After recovery, status reports the lineage as unrelated and omits candidate_diff and changed_path_manifest. No documented read-only command exports the original native base64 frozen context from the intact historical lineage.

The reviewer therefore cannot safely receive the required frozen bytes, and review cannot proceed. A plain Git diff cannot substitute because it is not the canonical frozen payload.

Gentle AI Version

v2.2.0

Operating System

Windows

AI Agent / Client

OpenCode

📋 Affected Area

CLI (commands, flags)

💡 Logs / Error Output

gentle-ai review status --lineage <lineage> --next-transition

lineage: <lineage>
target: <target>
state: reviewing
applicability: unrelated
candidate_diff: omitted
changed_path_manifest: omitted

Additional Context

Requested feature/bugfix: add a read-only review inspect/export-context --lineage <lineage> surface, or an equivalent verified export, for the original frozen context of an intact historical lineage.

The command must not restart or mutate authority state. It should preserve the distinction between the historical frozen candidate and the live target, so the reviewer receives only the exact original payload bound to <lineage> and <target>.

Shell: PowerShell.

[EstebanCabreraArbizu]

Reproduction clarification, not a retraction: the inability to export the canonical frozen context for an intact historical or non-current lineage is still real, and the requested read-only export remains valid.

In the observed instance, applicability: unrelated resulted from running gentle-ai review status in a different checkout/worktree from the one that owns the lineage. Authority recovery alone must therefore not be presented as the cause of that target mismatch. The same product gap still exists whenever an intact lineage must be inspected from a context where it is non-current: no documented read-only command exports its exact frozen reviewer payload. A verified review inspect --lineage <lineage> --export-context-style command would make that inspection safe without mutating authority state.

[dnlrsls]

Design is required before implementation to decide durable storage, lookup, and recovery semantics for native review results after context loss.

[danielgap]

@EstebanCabreraArbizu @dnlrsls taking this one via the design route from 2026-07-29.

Scope, so expectations are clear: the first deliverable is a design proposal answering the three open questions (durable storage, lookup, and recovery semantics for exporting the frozen context of intact historical lineages), not a PR. Implementation comes only after the design is reviewed and this issue moves to status:approved.

@EstebanCabreraArbizu if you already have design notes or a preferred direction, post them here and we coordinate in-thread rather than racing; your observations from the original report, including the worktree-mismatch clarification, are first-class input.

For context: I have been working the adjacent lens-context-budget lane (#4680, PR #4725), so canonical payload transport and sizing constraints are fresh. The proposal will explicitly cover large contexts and the unrelated-but-intact case from your reproduction clarification.

[danielgap]

Design proposal for #1894, answering the three questions from 2026-07-29 (durable storage, lookup, recovery semantics). File references are from main @ e772935. This draft was revised after a blind adversarial review round; the review is what hardened the fail-closed matrix below.

0. Framing correction that shapes everything below

The frozen candidate context is not a stored blob. START persists a Snapshot (internal/reviewtransaction/snapshot.go:58-69) holding Kind, BaseTree/CandidateTree (immutable Git tree SHAs), PathsDigest, IntendedUntracked, Paths, Identity, Projection, UnbornHead, and LedgerIDs, inside CompactState.InitialSnapshot as one review-state.json under <gitCommonDir>/gentle-ai/review-transactions/v2/<lineage>/. The candidate content lives in the repository object DB; the record binds it by digests. candidate_diff as bytes exists only in the legacy v1 negotiated transport and is never persisted (verified: CompactState has no diff field; it appears only in transport envelopes): it is re-derived on demand (WithLegacyCandidateDiff, internal/reviewtransaction/frozen_candidate_context.go:150) under twelve pinned flags (--binary --full-index --no-color --no-renames --no-ext-diff --no-textconv --diff-algorithm=myers --no-indent-heuristic --unified=3 --ignore-submodules=none --src-prefix=a/ --dst-prefix=b/), which is deterministic for a given git version, capped, and digest-bound.

Consequence: exporting the "original frozen context" is necessarily a deterministic re-derivation from the frozen trees, verifiable against the digests stored in the record. There is no byte-exact v1 payload to recover because none was ever stored. This proposal makes that explicit and treats determinism plus digest binding as the integrity contract, with its limits stated in section 4.

1. Durable storage

The compact record (revision-bound: Revision = "sha256:" + hex(sha256(CompactStateSchema + "\x00" + stateBytes)), compact_store.go:2151-2153) persists at v2/<lineage>/review-state.json until one of four explicit paths, which differ in what they leave behind:

• burn (approved-acknowledgement, compact_burn.go:214-227): deletes store.Dir and the effect marker; a terminal-consumption tombstone remains, keyed by repo+target identity. Git objects survive.
• abandon / reclaim: rename the entry out of v2/<lineage> into quarantine with a persisted audit record (compact_abandon.go:340, compact_reclaim.go:29).
• invalidation: keeps the record in place, state invalidated, explicitly still auditable (compact.go:1896-1906, status.go:29-31).
• store reset: explicit destructive seam (store_reset.go).

There is no automatic GC: review reclaim quarantines one explicit incomplete entry (internal/cli/review_reclaim.go:18, requires --lineage --reason --actor), never a bulk sweep.

Guarantees this design adds: a lineage whose record is present under v2/<lineage> and parseable is exportable regardless of its applicability to the live target, and every absence class says so explicitly (section 3 matrix) instead of degrading to a bare not-found.

2. Lookup

Resolution by explicit lineage ID through the same read path lens-context uses (discoverCompactFacadeReview, internal/cli/review_facade.go:2782). To be precise about locking, since the first draft of this proposal was wrong here: that path is read-only (no writes, no authority mutation) but not lock-free, unlike review inspect-authority: CompactStore.Load acquires the shared REVIEW-MAINTENANCE.lock flock while reading when the record exists (compact_store.go:1434-1473) and refuses while a prepared batch-reconciliation marker is present. The export inherits exactly those semantics: shared-lock reads, no mutation, and the reconciliation refusal becomes an explicit matrix row.

The store lives under the Git common dir, so sibling worktrees of the same clone can resolve a lineage the live working tree no longer matches, which is the reporter's clarified scenario. Unrelated clones cannot and should not resolve it. Applicability is reported as information in the export output, never as a gate: unrelated means "this lineage does not govern the live target" (target_status.go:534-576), not "storage is unreadable". The existing contract that unrelated status carries no frozen inputs (review_status_contract.go:476-486) stays untouched; export is a separate surface.

3. Recovery semantics (the command)

Proposed surface (naming per maintainer preference; the issue sketch suggested an inspect-family flag):

gentle-ai review export-context --lineage <id> [--cwd .] [--json]

Behavior:

• Read-only per section 2 semantics: no writes, no authority mutation, no new lineage, no re-importable authority transport (that is review-bundle-export's job; this is an inspection/documentation artifact).
• Output envelope: {lineage, revision, snapshot: {kind, base_tree, candidate_tree, paths_digest, intended_untracked, identity, projection, unborn_head, ledger_ids}, state, applicability, candidate_diff: {encoding, data (canonical base64), sha256, byte_size}, changed_path_manifest, derivation: {git_flags, tool_version}, budget}. The full Snapshot identity preimage is included so a historical consumer can tell a current-changes review from a base-diff or commit-range one without re-deriving identity.
• Deterministic derivation via WithLegacyCandidateDiff under its twelve pinned flags; manifest re-derived from the trees; both bound against the stored PathsDigest/manifest digests and the payload's self-verifying Bytes() (frozen_candidate_context.go:46-62).

Fail-closed matrix, with absence classes made explicit:

• record present and parseable → export (report state and applicability as information, including invalidated and unrelated)
• unknown lineage → not_found
• burned → consumed. Implementation note from the review: terminal-consumption tombstones are keyed by sha256(repo+target) with the lineage only inside the payload (compact_terminal_consumption.go:30-58), so classifying a burned lineage requires a small new derived index (or an explicit tombstone scan matching Lineage in-file). This is the one new lookup mechanism the design requires.
• abandoned or reclaimed → retired, resolved through the quarantine location and its persisted audit record (pointer to the audit entry in the output), never a bare not_found for a lineage that provably existed
• historical-compat retired schema → read-only refusal consistent with ErrHistoricalCompatReadOnly (compact_store.go:120)
• prepared batch-reconciliation marker present → refusal with the existing error class
• ambiguous/corrupted store → refuse (existing vocabulary)
• missing Git objects (externally pruned) → distinct reason; the record without objects is not exportable
• derived diff above MaxFrozenCandidateDiffBytes (4 MiB, frozen_candidate_context.go:21) → budget-exceeded refusal, same fail-closed discipline as lens_context_budget_exceeded, no truncation (this is where the bug(review): START accepts a candidate whose ~4 MiB lens context the Claude reviewer rejects as "Prompt is too long"; every capture fails deterministically (2.9.1) #4680/fix(review): summarize generated entries and make the lens budget transport-aware (#4680) #4725 transport-aware budget lessons apply directly)

4. Integrity semantics, stated honestly

What is verifiable without the live target: the envelope is self-verifying (Bytes() checks canonical base64, byte size, and the payload sha256), and the record's Revision and PathsDigest bind the snapshot. What is NOT stored anywhere: a digest of the derived diff bytes anchored in the record. NewFrozenCandidateDiff computes its sha256 fresh at derivation. Consequence: a future git version that renders the same two trees differently would change exported bytes with no stored-anchor mismatch to catch. Mitigation proposed: the output records the full derivation fingerprint (the twelve flags, tool version, and the derived sha256 at export time), so any later consumer can re-derive and detect drift explicitly. Byte-stability across git versions is not claimed.

5. Test plan

Byte-identity of review-state.json before/after export (pattern from review_historical_compat_test.go); unrelated-but-intact and invalidated lineages export with their state/applicability reported; burned lineage classifies consumed via the new index; abandoned/reclaimed classify retired with the audit pointer; unknown stays not_found; digest-binding failures (tampered tree object, mismatched paths digest, corrupted base64) each fail closed; budget refusal at 4 MiB; reconciliation-marker refusal; historical-compat refusal; sibling worktree of the same clone resolves and exports while an unrelated clone gets not_found; JSON shape contract test for the envelope including the derivation fingerprint.

Open questions for review

1. Command naming: new review export-context subcommand (my recommendation, mirrors inspect-authority/inspect-candidate) vs extending review inspect with --export-context as the issue sketch suggested.
2. Should the envelope include per-path evidence blocks (GENTLE_AI_REVIEW_PATCH style) or only the canonical diff plus manifest? My recommendation: only diff plus manifest; lens-context already serves per-path needs.
3. Should changed_path_manifest entries carry per-entry digests, or is the stored aggregate digest binding sufficient?
4. For retired lineages: should export read the quarantined record bytes directly (and thus export them), or resolve only the audit record and report retirement without payload? My lean: the latter, since quarantine exists to remove the entry from the authoritative surface.