refactor(session): extract safe recovery gate by Astro-Han · Pull Request #929 · Astro-Han/pawwork

Astro-Han · 2026-05-26T09:53:57Z

Summary

Extracts the safe-recovery replay gate out of retry decision assembly and moves side-effect boundary snapshot construction into run observability.

Why

This is PR 2 for #925. The retry metadata from PR 1 can now depend on a run-incident-owned safety gate instead of interpreting safe-recovery recommendations inline. The processor also stops owning the side-effect boundary proof details needed by recovery safety.

Related Issue

Closes part of #925.

Human Review Status

Approved by -Han

Review Focus

Please focus on whether RunIncident.evaluateReplaySafety owns only replay safety, while technical retryability, retry attempt metadata, and presentation mapping remain in retry classification / retry decision code.

Risk Notes

No behavior change intended. The main risk is accidentally changing safe-recovery replay classification, especially budget exhaustion and reasoning-only replay. Platform, UI, docs, dependency, and generated-file checklist items are not applicable.

How To Verify

bun test test/session/run-incident-safety-gate.test.ts test/session/retry-decision.test.ts: 10 passed
bun test test/session/run-observability-boundary.test.ts test/session/run-incident-safety-gate.test.ts test/session/retry-decision.test.ts: 11 passed
bun test test/session/run-observability.test.ts: 63 passed
bun test test/session/processor-effect.test.ts: 33 passed
bun run typecheck: ok

Screenshots or Recordings

Not applicable. No visible UI or copy changes.

Checklist

coderabbitai · 2026-05-26T09:54:09Z

📝 Walkthrough

Walkthrough

This PR centralizes replay-safety evaluation and side-effect boundary snapshot computation into dedicated modules (RunIncident and RunObservability), removing duplication and establishing a single source of truth for safety gate decisions and boundary proofing used during retry logic and stream processing.

Changes

Centralized Replay Safety and Boundary Snapshot Evaluation

Layer / File(s)	Summary
Replay Safety Evaluation Module `packages/opencode/src/session/run-incident/safety-gate.ts`, `packages/opencode/src/session/run-incident/index.ts`	Introduces `ReplaySafetyDecision` type and `evaluateReplaySafety` function to map `RecoveryDecision` recommendations and safe recovery attempt budget to replay eligibility, blocking reasons, and presentation modes. Exported via `RunIncident.evaluateReplaySafety`.
Side-Effect Boundary Snapshot Extraction `packages/opencode/src/session/run-observability/boundary.ts`, `packages/opencode/src/session/run-observability/index.ts`	Implements `sideEffectBoundarySnapshot` to classify tool boundaries and compute proof completeness by iterating tools, counting effect states, and detecting provider/external boundaries. Exported via `RunObservability.sideEffectBoundarySnapshot`.
Retry Decision Integration `packages/opencode/src/session/retry-decision.ts`	Replaces `buildModelRetryDecision` safety gate branching with a centralized call to `RunIncidentPolicy.evaluateReplaySafety`, sourcing all decision fields from the evaluation result.
Processor Boundary Snapshot Cleanup `packages/opencode/src/session/processor.ts`	Removes local `sideEffectBoundarySnapshot` helper and updates `runAttempt` and retry timeout policy derivation to use `RunObservability.sideEffectBoundarySnapshot`.
Test Coverage `packages/opencode/test/session/run-incident-safety-gate.test.ts`, `packages/opencode/test/session/run-observability-boundary.test.ts`	Adds tests for `evaluateReplaySafety` (replay budget, auto-retry, continuation scenarios) and `sideEffectBoundarySnapshot` (boundary detection and proof classification).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

Astro-Han/pawwork#925: Implements the proposed migration to centralize safe-recovery checks in run-incident and run-observability modules and route safety decisions through the retry pipeline.

Possibly related PRs

Astro-Han/pawwork#914: Also gates automatic retry/replay using side-effect boundary snapshot evidence; the main PR centralizes and re-exports sideEffectBoundarySnapshot while #914 adds a before-first-provider auto-retry fast-path using that same proof.
Astro-Han/pawwork#812: Also modifies packages/opencode/src/session/run-incident/index.ts to extend RunIncident exports; the main PR adds evaluateReplaySafety while #812 organizes core RunIncident diagnostics.
Astro-Han/pawwork#863: Introduced the local sideEffectBoundarySnapshot helper in processor.ts that this PR extracts and centralizes into RunObservability.

Suggested labels

enhancement

Poem

🐰 A boundary found its home at last,
In RunObservability's steadfast grasp,
While safety gates now branch with grace
Through evaluateReplaySafety's embrace,
No more duplication spans the place! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'refactor(session): extract safe recovery gate' clearly and concisely describes the main change: extracting the safe-recovery replay gate. It follows Conventional Commits format and directly relates to the primary refactoring work across multiple files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description is comprehensive, well-structured, and follows the required template with all critical sections complete.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/i925-safe-recovery-gate

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions

Suggested priority: P2 (includes non-doc, non-test paths outside the low-risk bucket).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.

gemini-code-assist

Code Review

This pull request refactors the session retry and observability logic by extracting sideEffectBoundarySnapshot into the RunObservability namespace and introducing a dedicated evaluateReplaySafety function within the RunIncident namespace. Additionally, new unit tests are added to verify these changes. The review feedback suggests simplifying imports in retry-decision.ts by removing the redundant type import and alias, and adding extra test cases to ensure full coverage of the newly extracted safety gate logic.

refactor(session): extract safe recovery gate

22df4c9

Astro-Han added P2 Medium priority harness Model harness, prompts, tool descriptions, and session mechanics task Narrow execution, audit, spike, migration, tracking, or upstream follow-up work labels May 26, 2026

github-actions Bot removed the task Narrow execution, audit, spike, migration, tracking, or upstream follow-up work label May 26, 2026

github-actions Bot reviewed May 26, 2026

View reviewed changes

gemini-code-assist Bot reviewed May 26, 2026

View reviewed changes

Comment thread packages/opencode/src/session/retry-decision.ts Outdated

Comment thread packages/opencode/src/session/retry-decision.ts Outdated

Comment thread packages/opencode/test/session/run-incident-safety-gate.test.ts

Astro-Han added the task Narrow execution, audit, spike, migration, tracking, or upstream follow-up work label May 26, 2026

github-actions Bot removed the task Narrow execution, audit, spike, migration, tracking, or upstream follow-up work label May 26, 2026

test(session): cover recovery confirmation gate

0cad23e

Astro-Han added the enhancement New feature or request label May 26, 2026

refactor(session): keep replay presentation in retry decision

92a0c54

Astro-Han merged commit bafb19b into dev May 26, 2026
29 checks passed

Astro-Han deleted the codex/i925-safe-recovery-gate branch May 26, 2026 10:18

coderabbitai Bot mentioned this pull request May 31, 2026

feat(session): retry safe recovery up to 3 times with exponential backoff #1008

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(session): extract safe recovery gate#929

refactor(session): extract safe recovery gate#929
Astro-Han merged 3 commits into
devfrom
codex/i925-safe-recovery-gate

Astro-Han commented May 26, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 26, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot left a comment

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Astro-Han commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Related Issue

Human Review Status

Review Focus

Risk Notes

How To Verify

Screenshots or Recordings

Checklist

Uh oh!

coderabbitai Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Astro-Han commented May 26, 2026 •

edited

Loading

coderabbitai Bot commented May 26, 2026 •

edited

Loading