fix(review): make frozen candidate artifacts consumable by OpenCode reviewers

[Thrasno]

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

A negotiated high-risk review can freeze the candidate successfully but still become impossible to complete in OpenCode because the exact candidate diff is returned as one large base64 value inside the review-start JSON envelope. The reviewer actors cannot consume that exact artifact when their read surface truncates long lines, and they may also lack a file-writing tool for the required result artifact.

This creates a dead-end after review START: all selected lenses are bound to the frozen subject, but none can truthfully report inspection.status: completed; no results can be captured; and review finalize remains blocked waiting for every original reviewer result. Retrying would violate the one-run-per-lens contract, while fabricating completion would violate review authority.

The bug is in the artifact handoff between the compact facade and OpenCode reviewer actors, not in the reviewed repository.

🔄 Steps to Reproduce

1. In a Git repository with a sufficiently large uncommitted candidate, run the negotiated review-start flow for a high-risk candidate and obtain four selected lenses.
2. Observe that candidate_diff is embedded as a single base64-encoded JSON string (approximately 160 KB in the observed run), while the changed-path manifest is embedded in the same response.
3. Launch each bound OpenCode reviewer with the exact lineage, target, lens, order, and subject hash, instructing it to inspect the frozen artifact.
4. The reviewer read surface truncates the long base64 line before it can decode the complete candidate diff. In runtimes without a writable artifact tool, the reviewer also cannot create the required BOM-less result JSON file.
5. Run gentle-ai review finalize --lineage <lineage>. It refuses to finalize because all original reviewer results are missing.

✅ Expected Behavior

The negotiated START response should provide each reviewer with a lossless, directly consumable frozen diff and changed-path manifest. Prefer provider-owned opaque handles or materialized artifact files with stable paths and hashes, rather than a large single-line base64 payload.

Each selected reviewer should be able to read the exact immutable candidate, inspect every changed path in manifest order, return or persist its bound result artifact even without generic filesystem writes, and let the facade capture an explicit completed or typed-unavailable result so finalize reaches a terminal state without fabricating PASS.

❌ Actual Behavior

The facade freezes the candidate and binds the lenses, but the only delivered diff representation is not consumable by the reviewer runtime. Reviewers return unavailable because the payload is truncated and/or the required result file cannot be written. capture-result cannot accept those incomplete inspections, and finalize remains permanently blocked waiting for the four original results.

A related usability issue is that calling review finalize without --lineage when multiple lineages exist emits operation_outcome_unknown and generates a defect report, even though the caller-actionable remedy is simply to specify the lineage.

Gentle AI Version

2.2.0 (ee83e83)

Operating System

Linux (Other), amd64

AI Agent / Client

OpenCode

📋 Affected Area

CLI (commands, flags) / review integration contract

💡 Logs / Error Output

Unable to complete: the immutable candidate diff is base64 on one line and was truncated by the available read tool.

Cannot review: the candidate diff/manifest cannot be consumed losslessly and no result artifact can be written.

review finalize requires all original reviewer results; capture each missing one with gentle-ai review capture-result.

Additional Context

No repository name, local path, candidate content, user identity, lineage identifier, target hash, or project-specific information is included intentionally.

Potential fixes:

1. Materialize the frozen diff and manifest as provider-owned files before reviewer launch and expose stable opaque handles/paths in START.
2. Offer a reviewer result-capture channel that accepts the returned JSON object directly, without requiring model-owned filesystem writes.
3. Persist typed unavailable lens outcomes so a review can terminate safely instead of remaining indefinitely non-finalizable.
4. Classify the missing---lineage finalize case as invalid_request or selection_required, not operation_outcome_unknown.

[ftorga]

The original artifact-handoff failure is resolved on main. PR #1970 replaced the large single-line Base64 diff and inaccessible external paths with provider-owned immutable Git tree identities, an ordered manifest, and bounded Git inspection commands. Reviewers therefore no longer need to decode a truncated payload or access a materialized /tmp artifact.

Main commit 6a5af7eb also added explicit, audited abandonment for an incomplete multi-lens review, so a permanently unavailable lens does not require fabricated completion. Broader typed access/capture recovery remains tracked separately in #1867. A maintainer can close this issue as superseded by #1970 and the subsequent incomplete-review recovery.

[Alan-TheGentleman]

Closing as fixed in v2.2.1. Reviewers can inspect immutable Git trees without external files, managed capture is direct, and incomplete multi-lens reviews have an audited abandonment path.

[gaston-ara]

Confirmed a regression of the managed-capture path on Gentle AI 2.2.4, Windows x64, OpenCode 1.18.10.

Observed evidence

• Negotiated gentle-ai.review-integration/v2 review, medium risk, one review-reliability lens.
• Frozen candidate: 3 paths, 176 changed lines, correction budget 88.
• STATUS returned collect / reviewer_results_required with capture operation review.capture-result.
• The bound OpenCode reviewer completed inspection and returned provider-owned artifact rart1_2b8d7dbd39d6d97ea5cb6515812d11e155fdcb03c631f98ab86e4f9d6c49bf93, admission decision completed.
• The installed review capture-result command exposes only --input (file or stdin) for the reviewer payload. It does not accept the provider-owned artifact handle, and the orchestrator has no access to the artifact's JSON content.
• A bounded capture attempt using the provider-owned handle was rejected during flag parsing because --captured-results is not defined. No mutation started.

Safe binding identifiers: lineage review-3224045b4a27c2eb; authority revision sha256:69b93615c7e78a69a231518a66494ea01429d4cbe20a6047b8ce10881f51218c; subject hash sha256:ccb835fde424968edde73a04b1cb15565d1ee413ac90686752342b910f74f56c.

Minimal reproduction

1. Start a negotiated v2 review in OpenCode and reach a reviewer_result collect transition.
2. Launch the exact bound reviewer slot.
3. Observe a completed gentle-ai.review-result-artifact/v2 response containing only an opaque rart1_... reference.
4. Attempt the named review.capture-result operation.
5. Observe that the CLI requires raw JSON through a file/stdin but exposes no accepted argument for the provider-owned reference.

Expected vs actual

Expected: managed capture should persist the completed reviewer artifact automatically, or the collect transition should provide an executable capture operation that consumes the returned opaque reference.

Actual: the reviewer succeeds, but the CLI and orchestrator have no compatible transport for that result, so STATUS remains collect / reviewer_results_required and no receipt can be produced.

The frozen target, candidate tree, snapshot identity, paths, and modes remained unchanged. The reviewer and failed capture attempt made no repository mutation. This reports observed behavior only and does not assert an unconfirmed root cause.

[nick130920]

Regression occurrence on Gentle AI 2.2.4, Windows x64, OpenCode 1.18.13.

Observed evidence:

• A negotiated review-integration/v2 review reached
  eviewer_results_required for a high-risk four-lens candidate.
• The first bound reviewer completed inspection and returned gentle-ai.review-result-artifact/v2 with opaque reference
  art1_e93ec83166fe85361194ee0e398c8f47793f63746b26750140d1c1ac1041a883 and �dmission_decision: completed.
• The named
  eview capture-result command accepts only raw JSON through --input (file or stdin). Passing that opaque reference makes it attempt a local file read and fail with file-not-found.
• STATUS remains collect / reviewer_results_required; no receipt can be produced.
• The subsequently requested audited abandonment is refused because authority reports
  eviewer-results beyond pristine state, so neither capture nor the documented abandon path is usable.

Safe binding identifiers: lineage
eview-25e15e1ed5f594a3; authority revision sha256:18c7cf9ef815d6ce1a768ea729564275824fb41eae438faed87b0c6925bc4d7a; frozen target sha256:25e15e1ed5f594a3e3f157cfc89be350444d8019445ce2f6a649b46e92cd57a1; subject hash sha256:a444a113ac68dcd926c5c818b159419436918a25edfc30ac4f7b57d1ad064745.

Minimal reproduction:

1. Start a negotiated v2 review in OpenCode and reach a reviewer-result collect transition.
2. Launch the exact bound reviewer slot.
3. Receive only the provider-owned
   art1_... artifact reference.
4. Run the named capture operation using that reference.
5. Observe the local-file read failure and then the unavailable abandonment path.

Expected: managed capture persists the opaque reviewer artifact, or capture consumes that artifact reference; if capture cannot proceed, audited abandonment remains available.

Actual: the reviewer completes, but its artifact has no compatible transport into capture and the lineage cannot be abandoned.

Preserved state: the frozen candidate identity, paths, modes, and working tree remained unchanged after the failed capture and abandonment attempts. This report describes observed behavior only.