fix(sync): stop re-opening a blocked issue while the PR state is unchanged

[alvarosanchez]

The loop

shouldPreserveBlockedExternalPullRequestWait preserves blocked for exactly two pull-request shapes — unfinished CI, and green CI waiting on maintainer approval. Neither covers ciState === 'red'.

So an issue blocked on a red required check that nobody in the company can clear gets pulled back into active work on every sync pass:

1. the assignee cannot clear the check (a contributor CLA gate needs a human signature), so it sets the issue blocked;
2. the next sync pass sees red CI, moves it to in_progress and wakes the assignee;
3. the assignee re-establishes that it is still externally blocked and blocks it again;
4. go to 2.

On the cliponaut instance this produced 3,233 blocked -> in progress transition comments across 40 issues. The agents left the evidence themselves — "PR #N remains blocked only by the external CLA gate" ×71, and "GitHub Sync moved DEV-N back to N, but the linked PR …" ×119. One issue alone (DEV-83) carried 335 machine comments, cycling roughly every 17 minutes.

An upstream baseline failure or an unreleased dependency behave identically; the CLA is just the common case here.

The existing effective-state fingerprint cannot suppress this, because the issue status genuinely changes each round — sync writes in_progress, the agent writes blocked — so every pass compares against a different state and mutates again.

The fix

blocked is a deliberate decision by an agent or a human, and GitHub Sync owns changes in GitHub, not steady state.

Once sync has moved an issue out of blocked, it may not do so again until the externally observable state of the linked pull requests actually changes. buildExternalPullRequestStateHash hashes repository, number, head SHA, CI state, mergeability, merge state status, review decision and the unresolved-review-thread flag (order-independent); shouldPreserveDeliberateBlockedWait holds blocked while the current hash equals the recorded one.

The hash is persisted on the registries that already exist per issue — ImportedIssueRecord for the issue-linked path, RemoteActionRecord for the direct-PR path — and written at the mutation point, because the registry writes further down both paths are conditional and would otherwise drop it. The direct-PR path re-resolves its record after persisting, since that path re-reads the registry.

Deliberately narrow:

• it only ever keeps an issue in blocked; it can never force one into it;
• an issue with no linked PR has no external state and is never held back;
• a fresh block clears the recorded hash, so the next external change can unblock normally;
• any change sync can see — a push, a CI result, a review, a resolved conflict — resumes routing on the very next pass.

Tests

Two new cases in tests/plugin.spec.ts, built on the exact PR shape that caused the loop (PR #1281, red CI, mergeStateStatus: blocked, review_required):

• the first pass unblocks, the second pass on identical state does not, and a new head SHA or the CLA going green unblocks again; the guard never forces blocked, and an issue with no PR is never held;
• the hash is order-independent and every field sync reacts to is covered.

npm test 363/363 green, npm run typecheck clean.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new logic clears unblockedExternalStateHash whenever nextStatus === 'blocked' (even when already blocked), which can erase the recorded hash without any external PR change and allow the re-opening loop to recur.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR addresses a sync-loop where GitHub Sync repeatedly transitions Paperclip issues from blocked back to active work when a linked PR remains externally blocked (e.g., permanently red required checks like a CLA gate), causing excessive status-transition comments and noisy wakeups.

Changes:

• Introduces an “external PR state hash” and a guard (shouldPreserveDeliberateBlockedWait) so once sync unblocks an issue, it won’t do so again until the observable PR state changes.
• Persists the last “unblocked” hash on the per-issue registries (ImportedIssueRecord / RemoteActionRecord) at the mutation point to avoid losing it through conditional registry writes.
• Adds targeted tests and updates SPEC/README to document the new blocked preservation rule.

File summaries

File	Description
src/worker.ts	Adds external PR state hashing + deliberate-block preservation guard and persists the hash on relevant registries.
tests/plugin.spec.ts	Adds regression coverage for the “don’t re-open blocked on unchanged PR state” behavior and hash field coverage/order-independence.
SPEC.md	Documents the new invariant for not repeatedly moving issues out of blocked without external PR changes.
README.md	Explains the user-facing behavior and rationale for preventing repeated re-openings from blocked.

Review details

Suppressed comments (1)

src/worker.ts:16097

• Same as the issue-linked path: remoteAction.unblockedExternalStateHash is cleared whenever nextStatus === 'blocked', even when the issue is already blocked and no fresh block occurred. This can drop the recorded external-state hash without any observable PR change and allow sync to re-open the issue again on an unchanged PR state. Clear the hash only when transitioning into blocked from a non-blocked status.

      } else if (paperclipIssue.status === 'blocked' && nextStatus !== 'blocked') {
        remoteAction.unblockedExternalStateHash = currentExternalStateHash;
      } else if (nextStatus === 'blocked') {
        delete remoteAction.unblockedExternalStateHash;
      }

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.