fix(FN-8004): make AI merge rejections actionable and stranded merges retryable

[gsxdsm]

Two follow-ups to FN-8004. Both were found by watching FN-8004's own merge livelock for 40 minutes — it turned out to be blocked by the very class of bug it was filed to fix.

1. AI merge rejections lost their reasons

The reviewer prompt said both of these:

"End with a single decision line: REVIEW_VERDICT: approve|reject"
"Then list each concrete reason as a bullet."

Those are impossible to satisfy at once. Reviewers obeyed "End with" and wrote their reasoning above the verdict — but extractRejectReasons only scanned lines after it. So every such rejection collapsed to the placeholder reviewer rejected the merge without a stated reason, and that placeholder was then handed to the corrective re-merge pass as its instruction. The pass got no actionable feedback and just re-rolled the merge.

The evidence, from FN-8004's own merge — the pattern repeated across both attempts:

	Attempt A	Attempt B
review pass 1	rejected, no reason (03:46)	rejected, no reason (03:57)
corrective pass	1/3	1/3
review pass 2	approved a3a3cc6a8 (03:49)	approved

A reviewer that rejects and then approves identical content isn't objecting — the reason was being thrown away. Each wasted cycle cost ~7 minutes, stretching the merge past main's ~8-minute churn window so every attempt lost to a concurrent advance and rebuilt. The livelock was caused by the lost-reason bug.

Fix: the parser recovers reasons from either side of the verdict (inline → after → before, nearest-first so the closing argument leads, capped at 8 so a long transcript can't flood the corrective prompt), skipping severity/verdict/markdown scaffolding. The prompt ordering is now unambiguous — reasons first, verdict last, nothing after it.

2. An orphaned merge-active stamp was un-retryable by hand

The Retry gate refused every merge-active status (Task is not in a retryable state (current status: landing)), while self-healing cleared stale stamps automatically minutes later. So a merger killed mid-flight — crash, engine restart, operator SIGTERM — blocked the operator's own escape hatch at exactly the moment they'd reach for it. FN-8004 hit this: a killed merge left landing stamped and Retry 400'd for the full sweep delay.

isStaleMergeActiveStatus now lives in the leaf merge-active-status.ts, shared by recoverStaleMergingStatus and the Retry gate — so the manual path can never be stricter than the automatic one. This is the same one-concept-two-definitions bug as FN-8004's transient classifier, which is why it's worth fixing structurally rather than adding another special case.

A live merge stays protected by two independent signals: it holds the in-process lease and refreshes updatedAt each phase. Staleness fails closed on an unparseable timestamp.

One subtlety worth reviewing: the bypass feeds isInReviewRetry rather than only the gate. A bare gate bypass would fall through to the generic branch and move fully-executed work to todo, re-running finished work — a bug this fix could easily have introduced.

Verification

• Gate green (294 + 122 + 63) · lint clean · engine + dashboard typecheck clean · verify:fast PASS
• 70 merger-suite tests green; all 7 pre-existing verdict-parser tests still pass (backward compatible — none of them covered the verdict-last layout, which is exactly why this shipped)
• The route regression test was confirmed non-vacuous: neutralizing the fix fails the two "now retryable" cases while the three live-merge-protection cases still pass, proving they guard real behavior rather than the new code.
• Regression tests assert the invariant across every surface per Fix the Invariant, Not the Repro: all five ACTIVE_MERGE_STATUSES (a merger can die in any phase, not just the reported landing), both live-merge signals, boundary conditions, fail-closed paths, and that pre-existing retry paths are unchanged. Test files carry the required ## Symptom Verification and ## Surface Enumeration sections.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • AI merge rejections now reliably include concrete, correctly ordered reasons, even when provided before the verdict line.
  • Manual retry can recover tasks stuck in stale merge-processing states.
  • Retry is still blocked for tasks tied to active merge activity or recently updated/advancing merges.
  • Existing failed-merge retry behavior remains unchanged.

• Reliability

  • Improved shared handling of “orphaned” merge-active detection across the engine and dashboard.

• Tests

  • Added/expanded coverage for merge-active staleness, retry eligibility, and verdict/reason parsing.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: cfb07a88-4283-4997-aac5-e474acdf8b2f

📥 Commits

Reviewing files that changed from the base of the PR and between 6fa8ae0 and 45838e6.

📒 Files selected for processing (7)

• packages/dashboard/src/__tests__/routes-task-retry-stale-merge-status.test.ts
• packages/dashboard/src/routes.ts
• packages/dashboard/src/routes/register-task-workflow-routes.ts
• packages/dashboard/src/server.ts
• packages/engine/src/__tests__/merger-ai-prompts.test.ts
• packages/engine/src/merger-ai-prompts.ts
• packages/engine/src/self-healing.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/engine/src/tests/merger-ai-prompts.test.ts
• packages/engine/src/merger-ai-prompts.ts
• packages/dashboard/src/tests/routes-task-retry-stale-merge-status.test.ts

---

📝 Walkthrough

Walkthrough

The PR centralizes merge-active staleness detection for self-healing and dashboard retries, allowing orphaned merge-active tasks to retry while protecting active or recently updated tasks. It also improves AI rejection-reason recovery and clarifies review prompt output ordering.

Changes

Stale merge retry

Layer / File(s)	Summary
Shared merge status contract packages/engine/src/merge-active-status.ts, packages/engine/src/index.ts, packages/engine/src/self-healing.ts	Defines canonical active statuses, staleness thresholds, ownership and timestamp checks, and shared exports.
Retry and self-healing integration packages/dashboard/src/routes/..., packages/dashboard/src/server.ts, packages/engine/src/self-healing.ts, packages/dashboard/src/__tests__/routes-task-retry-stale-merge-status.test.ts, packages/engine/src/__tests__/merge-active-status.test.ts, .changeset/...	Dashboard retry and stale-merge recovery use the shared predicate, with coverage for orphaned, active, fresh, threshold, and failed states.

AI verdict recovery

Layer / File(s)	Summary
Rejection reason parsing packages/engine/src/merger-ai-prompts.ts	Recovers, filters, orders, and caps rejection reasons from lines surrounding the verdict.
Prompt contract and regression coverage packages/engine/src/merger-ai-prompts.ts, packages/engine/src/__tests__/merger-ai-prompts.test.ts	Requires reasons before severity and the final verdict, with regression tests for parsing and prompt consistency.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant DashboardRetryRoute
  participant SelfHealingManager
  participant StaleMergePredicate
  participant TaskStore
  Operator->>DashboardRetryRoute: POST task retry
  DashboardRetryRoute->>SelfHealingManager: read active merge lease and age floor
  DashboardRetryRoute->>StaleMergePredicate: evaluate status, owner, and age
  StaleMergePredicate-->>DashboardRetryRoute: retryable or blocked
  DashboardRetryRoute->>TaskStore: clear status and error
  TaskStore-->>DashboardRetryRoute: updated task
  DashboardRetryRoute-->>Operator: HTTP response

Loading

Suggested reviewers: plarson, automata-intelligentsia

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures both main changes: actionable AI merge rejections and retryable stranded merges.
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.

✨ 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 fix/merge-review-reasons-and-landing-retry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

This PR improves recovery for stalled merge workflows. The main changes are:

• Recovers actionable rejection reasons from either side of the review verdict.
• Clarifies the required ordering of review reasons, severity, and verdict.
• Shares stale merge-status detection between automatic recovery and manual Retry.
• Preserves live merge protection through lease and timestamp checks.
• Adds coverage for merge phases, staleness settings, and retry behavior.

Confidence Score: 5/5

The latest changes look safe to merge.

• The manual Retry path now uses the same configured staleness floor as automatic recovery.
• Live merges remain protected by ownership and freshness checks.
• No additional blocking issue met the follow-up review scope.

Important Files Changed

Filename	Overview
packages/engine/src/merger-ai-prompts.ts	Recovers rejection reasons around the verdict and makes the reviewer output order explicit.
packages/engine/src/merge-active-status.ts	Defines the shared merge-active status set and conservative staleness predicate.
packages/engine/src/self-healing.ts	Uses the shared predicate and exposes the configured staleness floor.
packages/dashboard/src/routes/register-task-workflow-routes.ts	Allows stale merge-active tasks to use the existing in-review retry path.
packages/dashboard/src/routes.ts	Passes the configured staleness floor into workflow routes.
packages/dashboard/src/server.ts	Extends server wiring with the stale merge-status age getter.

_{Reviews (2): Last reviewed commit: "fix(FN-8004): align manual merge recover..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/engine/src/__tests__/merger-ai-prompts.test.ts`:
- Around line 134-158: Extend the parseReviewVerdict regression coverage to
include a genuine reason before the REVIEW_VERDICT_MARKER and a closing code
fence after it, asserting that reasons excludes the fence and retains the real
reason. Keep the existing scaffolding, severity, and verdict-line filtering
assertions, and ensure the test covers both post-verdict and surrounding
markdown boundaries.

In `@packages/engine/src/merger-ai-prompts.ts`:
- Around line 131-145: Filter scaffolding consistently in the post-verdict loop
of the reason-extraction logic by applying isNonReasonLine before cleaning or
collecting lines, allowing valid preceding feedback to trigger fallback. Add a
regression case in packages/engine/src/__tests__/merger-ai-prompts.test.ts
covering a preceding reason followed by a trailing code fence, and assert the
invariant across both post-verdict and preceding-reason recovery surfaces.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 44e27a83-b91f-4c49-8771-f12c19b0cc5d

📥 Commits

Reviewing files that changed from the base of the PR and between a048a61 and 6fa8ae0.

📒 Files selected for processing (9)

• .changeset/fn-8004-merge-review-reasons-and-landing-retry.md
• packages/dashboard/src/__tests__/routes-task-retry-stale-merge-status.test.ts
• packages/dashboard/src/routes/register-task-workflow-routes.ts
• packages/engine/src/__tests__/merge-active-status.test.ts
• packages/engine/src/__tests__/merger-ai-prompts.test.ts
• packages/engine/src/index.ts
• packages/engine/src/merge-active-status.ts
• packages/engine/src/merger-ai-prompts.ts
• packages/engine/src/self-healing.ts