fix(opencode): bound 4R frozen-context transport across restart

[doblas]

Pre-flight Checklist

• I searched open and closed issues for context overflow/compaction, 4R, resume/relaunch, capture-result, partial results, untracked scope, and immutable diff prompts; this is not a duplicate
• I understand that PRs will be rejected if the linked issue does not have status:approved

Bug Description

A high-risk OpenCode review can enter an infinite restart loop when the parent session exceeds its context limit before any foreground lens reaches the managed capture hook.

On restart, native authority correctly reports the same reviewing lineage. However, review status --next-transition serializes the complete immutable candidate diff and changed-path manifest once inside every missing lens input. Canonical 4R therefore puts four copies in one parent-visible response. The managed OpenCode plugin then independently preflights and appends the same full frozen context to each foreground task prompt.

If OpenCode fails with Session too large to compact - context exceeds model limit even after stripping media before any tool.execute.after capture, native authority has zero captured artifacts. The next session sees all four lenses missing and repeats the same oversized fan-out indefinitely.

This is separate from #1250: default workspace projection can inflate scope with unrelated untracked files, but this defect is repeated per-lens transport plus no parent-failure-safe checkpoint before relaunch.

Audited remote main: 1f3fda46311030abb351ff81971d905b78d40cac. Installed production commit 8881b60b01c7cbf80da072d95579fe66b3e3a63b is an ancestor and contains the relevant behavior.

Steps to Reproduce

1. On Windows, use OpenCode with Gentle AI 1.49.1-0.20260722122850-8881b60b01c7.
2. Prepare a high-risk candidate. The observed target had 25 paths, 1,708 changed lines, and correction budget 200.
3. Start or resume negotiated native review.
4. Run review status --contract gentle-ai.review-integration/v1 --next-transition for the active lineage.
5. Observe four reviewer_result inputs, each containing the complete candidate_diff and changed_path_manifest.
6. Launch all four bound foreground tasks. The managed hook appends GENTLE_AI_FROZEN_CANDIDATE_CONTEXT with the full diff/manifest to every task prompt.
7. Let parent context exceed OpenCode's compaction limit before any lens completes and invokes tool.execute.after.
8. Start a fresh orchestrator session and query the same lineage.
9. Observe all four lenses still missing, all four relaunched, and the parent overflowing again.

Expected Behavior

• Restart output carries immutable candidate context once, or bounded provider references resolvable outside the parent transcript.
• Parent-visible lifecycle messages remain bounded for moderate high-risk diffs.
• Each completed lens is independently durable and restart launches only missing lenses.
• Failure before the first capture does not recreate the same guaranteed-overflow fan-out; collection can checkpoint sequentially or use bounded transport.
• The same lineage, target, and budget make forward progress across restarts.

Actual Behavior

• review status --next-transition duplicates full context per missing lens (internal/cli/review_next_transition.go:218-253); TestNegotiatedRestartStatusSuppliesFrozenContextForEveryMissingReviewer explicitly requires equivalent context for every input (internal/cli/review_next_transition_test.go:280-333).
• Status expands one frozen context through all missing inputs (internal/cli/review_facade.go:478-527).
• The OpenCode hook performs full preflight and appends that context to each foreground prompt (internal/assets/opencode/plugins/review-result-artifacts.ts:124-184, 253-290).
• Capture becomes durable only after the after-hook: native code atomically publishes each lens artifact (internal/cli/review_artifact.go:328-419) and restart discovers captured orders (internal/cli/review_artifact.go:639-681; internal/cli/review_next_transition.go:218-232).
• Partial resumability works after at least one capture; parent failure before the first callback leaves no checkpoint and repeats all four.

Sanitized authority evidence:

{
  "lineage_id": "review-<redacted>",
  "state": "reviewing",
  "risk_level": "high",
  "selected_lenses": [
    "review-risk",
    "review-resilience",
    "review-readability",
    "review-reliability"
  ],
  "lens_results": [],
  "target": {
    "path_count": 25,
    "changed_lines": 1708
  },
  "correction_budget": 200
}

lens_results: [] alone does not prove capture absence because compact lens results merge at finalize. The decisive symptom is restart artifact discovery returning all four lenses as missing.

Gentle AI Version

1.49.1-0.20260722122850-8881b60b01c7 (audited against remote main 1f3fda46311030abb351ff81971d905b78d40cac)

Operating System

Windows

AI Agent / Client

OpenCode

Affected Area

Other (native review payload and managed OpenCode capture hook)

Logs / Error Output

Session too large to compact - context exceeds model limit even after stripping media

lineage: review-<redacted>
state: reviewing
selected lenses: review-risk, review-resilience, review-readability, review-reliability
captured/missing after restart: 0 / 4

Additional Context

Root cause and contributing factors

Primary boundary: Gentle AI/OpenCode integration. OpenCode owns the hard compaction failure, but Gentle AI amplifies it by serializing four full contexts into one parent response, injecting another full copy into each prompt, and requiring bound review tasks to run in the foreground.

Scope contributor: workspace START intentionally discovers every non-ignored untracked path (internal/cli/review_facade.go:870-877; internal/reviewtransaction/snapshot.go:533-552). --projection staged excludes unstaged/untracked content (internal/cli/review_facade_test.go:23-75). Exact staged/manifest concerns remain in #1250.

This is not all-or-nothing native persistence: tool.execute.after invokes capture-result per completed lens, capture atomically publishes that slot, and status omits captured orders. Current-main focused tests passed:

go test ./internal/cli -run 'TestNegotiatedRestartStatusSuppliesFrozenContextForEveryMissingReviewer|TestReviewCaptureResultConcurrentSelectedLenses|TestReviewCaptureResultStrictBindingReplayAndFinalize' -count=1
ok github.com/gentleman-programming/gentle-ai/internal/cli

Proposed fix directions and tradeoffs

• Preferred: shared frozen context once at transition level plus per-lens subjects/bindings. Removes O(lenses x diff) parent growth but needs a versioned schema/consumer change.
• Alternative: provider-owned opaque context references resolved directly by the trusted plugin. Keeps parent messages small but needs lifecycle/availability guarantees.
• Tactical mitigation: collect/capture one missing foreground lens at a time. Creates restart checkpoints but adds latency and does not remove each child prompt's required context.
• Do not reconstruct from live Git or broaden reviewer filesystem/shell permissions.

Acceptance criteria

• Canonical 4R restart carries at most one full diff/manifest in parent-visible JSON, or only bounded references.
• Managed OpenCode review does not retain four full context copies in the parent transcript.
• Completed lenses capture immediately and independently; restart launches only missing orders.
• Failure before first completion cannot cause an unbounded identical four-lens loop.
• Lineage, target, subject hash, lens, order, and revision remain strictly bound.
• Restart creates no new lineage or budget.
• Windows/OpenCode regression uses at least 1,700 lines / 25 paths, interrupts before and after individual captures, and proves bounded payload plus forward progress.
• Unit coverage proves restart payload growth is O(diff x missing lenses).
• Existing capture, artifact validation, and finalization tests remain green.

Shell: PowerShell 5.1 (Other where a shell dropdown exists).

Related but not duplicate: #1250 (candidate scope), #1454 (artifact availability), #1411 (capture incidents), #1037 (generic OpenCode context snowballing), and #1051 (optional pruning).

[doblas]

Follow-up production evidence confirms two compounding boundaries.

Exact duplicate: capture contract drift

The four installed OpenCode reviewer prompts require only top-level findings and evidence and explicitly prohibit every other field, while gentle-ai review schema reviewer requires subject_hash, inspection, findings, and evidence. All four lenses therefore returned prompt-compliant JSON, then managed capture failed with:

reviewer artifact admission incomplete: reviewer result omitted the provider-owned artifact subject

The plugin preserved each raw result. Native recovery succeeded only after adding the exact preflight-issued subject hash and inspection.status=completed with every manifest path in order.

This exact defect, version, error, ownership boundary, replay behavior, acceptance criteria, and test plan are already tracked by #1689: #1689. No duplicate issue is needed.

Current-main evidence at 48c428f7930373d38daed267f15caa46617e29ba:

• internal/cli/review_schema.go (reviewReviewerSchema) requires all four fields.
• internal/reviewtransaction/artifact_admission.go:114 rejects a missing provider subject.
• internal/components/sdd/boundedreview.go:13-15,117-154 now renders all four fields into reviewerPrompt.
• internal/components/sdd/bounded_review_contract_test.go:74-87 pins that corrected rendered shape.
• The installed opencode.json still contains the old findings/evidence-only prompt even though installed commit 8881b60b01c7 contains prompt-fix commit bd34d8cf. This proves generated-config/runtime drift in production, while fix(opencode): enrich reviewer output with provider-owned capture subject #1689 remains the canonical capture-contract issue.

Direct #1710 addition: frozen context can be injected twice

One reliability launch contained GENTLE_AI_FROZEN_CANDIDATE_CONTEXT twice because the parent task prompt already carried the frozen context and the managed plugin appended it again. Current main still does this unconditionally in internal/assets/opencode/plugins/review-result-artifacts.ts:172-184: injectReviewerContext always runs preflight and returns the original prompt plus a new marker. There is no equality, mismatch, or existing-marker guard. internal/assets/assets_test.go:422-503 checks source fragments only; no behavioral test asserts exactly one frozen context.

Minimal reproduction:

1. Build a bound review task prompt containing one valid GENTLE_AI_FROZEN_CANDIDATE_CONTEXT from native START/STATUS.
2. Execute it through the managed OpenCode task before-hook.
3. Observe preflight succeed and injectReviewerContext append a second full diff/manifest.
4. The child receives duplicate immutable payloads and the parent transcript grows again, worsening the context amplification reported here.

Expected: exactly one authoritative frozen context reaches each lens. If an existing context is byte/semantically identical to preflight, reuse it. If it differs, fail before reviewer launch. Actual: the plugin always appends another copy.

Acceptance and regression additions for #1710:

• A bound task prompt contains exactly one GENTLE_AI_FROZEN_CANDIDATE_CONTEXT after the before-hook.
• An identical existing provider context is reused without another append or another parent-visible full payload.
• A conflicting existing subject, diff, or manifest fails before consuming the lens.
• A behavioral plugin test covers absent, identical, malformed, and conflicting existing markers.
• End-to-end Windows/OpenCode coverage combines corrected reviewer schema output, exactly-one context injection, successful per-lens capture, and restart with only genuinely missing lenses.
• The fix(opencode): enrich reviewer output with provider-owned capture subject #1689 fix and this issue do not independently add different ownership rules for subject_hash or inspection; one tested contract must govern generated prompts, plugin enrichment/replay, and native admission.

This strengthens #1710 rather than changing its root verdict: #1689 explains why completed reviewers still failed to checkpoint, while duplicate marker injection adds another deterministic context multiplier before capture.

[dnlrsls]

Design decision needed: define versioned bounded 4R context transport and restart semantics, and explicitly retire or amend the stale duplicate-marker subclaim.