fix: coordinate task pull request sync consumers (#3090)

This commit is contained in:
Carlos Florêncio
2026-08-27 12:59:30 +00:00
committed by GitHub
parent d851ff7ca1
commit 6599a3b714
9 changed files with 1412 additions and 167 deletions
@@ -0,0 +1,144 @@
---
created: 2026-08-27
updated: 2026-08-27
status: implemented
requirements:
- REQ-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001
system_design:
- ../../specs/integrations/system-design/github-task-pr-sync-coordination.md
legacy_specs: []
---
# Implementation Plan: GitHub task pull request sync coordination
## Overview
Replace per-hook task pull request synchronization state with one shared,
store-scoped resource per workspace context and task. The resource coordinates
the initial request, in-flight work, retry timer, reconnect edge, loaded state,
and cleanup while `useTaskPR` preserves its current public API.
The confirmed root cause is that every mounted `useTaskPR` instance owns its
own effects and refs. A task page can mount several consumers, so it sends
several identical `github.task_pr.sync` requests and creates several retry
schedules. Backend behavior is not the source of the duplication.
## Scope
### In scope
- Add a shared task PR sync resource keyed by store, workspace ID, workspace
generation, and task ID.
- Share automatic and manual in-flight synchronization requests.
- Give each scoped entry one retry timer and one reconnect observer.
- Reference-count consumers and clean up after the last release.
- Preserve task PR store writes, loaded outcomes, retries, reconnect recovery,
manual refresh, and unlink behavior.
- Add deterministic resource and hook regression tests.
### Out of scope
- Backend request coalescing.
- WebSocket protocol or GitHub provider changes.
- Changes to task PR rendering, copy, or interactions.
- Refactoring tooltip hydration, workspace-wide loading, or Git status
subscriptions.
## Technical approach
### Shared synchronization resource
Create `apps/web/hooks/domains/github/task-pr-sync-resource.ts` with a testable
factory. Keep registries in a `WeakMap` keyed by Zustand store. Key each entry by
workspace ID, workspace-context generation, and task ID.
Each entry exposes a stable snapshot and subscription for
`useSyncExternalStore`. The subscription owns a consumer lease. The first lease
starts freshness synchronization; the last release stops timers and observers
and invalidates stale completions.
The entry joins all active refresh calls to one promise. It owns one bounded
five-second retry schedule and detects one transition edge into `connected`.
Before publishing a result, it verifies the resource generation and active
workspace context.
### Hook integration
Refactor `useTaskPR` to obtain the current Zustand store API and scoped resource
entry. Replace local retry, permanent, request, reconnect, and loaded state with
the resource snapshot and delegated `refresh`.
Keep `pr` and `prs` selected from the current workspace's task PR slice. Keep
the existing `unlink` callback and return shape unchanged. No component caller
changes are expected.
## Test-first sequence
1. Add a failing multi-consumer hook regression. Two consumers for one scoped
task must send one initial request and one request on a retry tick.
2. Add failing resource tests for concurrent manual refresh, consumer release,
separate scope keys, reconnect recovery, permanent responses, retry
exhaustion, and stale workspace completion.
3. Implement the shared resource and integrate `useTaskPR` until the focused
tests pass.
4. Run the existing hook suite to prove unlink, loading, retry, and reconnect
behavior remains unchanged.
## Tests
- `AC-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001.1` and `.2`: two
consumers share initial, retry, and concurrent manual refresh requests.
- `.3`: different stores, tasks, workspaces, and workspace generations use
separate entries.
- `.4`: one unmount preserves the shared lifecycle; the last unmount cancels
future retries and observers.
- `.5`: empty, transient, permanent, discovered-PR, exhausted, and reconnect
cases retain their current outcomes.
- `.6`: a stale context response cannot write associations or publish loaded
state for the active context.
- `.7`: all consumers observe the same loaded result; existing unlink tests
remain green.
## Verification commands
Run from the repository root unless a command changes directory:
```bash
(cd apps/web && pnpm exec vitest run hooks/domains/github/task-pr-sync-resource.test.ts hooks/domains/github/use-task-pr.test.tsx)
(cd apps/web && pnpm run typecheck)
(cd apps && pnpm --filter @kandev/web lint)
git diff --check
```
If `apps/node_modules` is absent in a fresh worktree, first run
`cd apps && pnpm install --frozen-lockfile`.
## Work orders
- [x] [Task 01: Coordinate task PR sync consumers](task-01-coordinate-task-pr-sync-consumers.md)
## Implementation waves and parallel candidates
Wave 1 is sequential:
- Task 01 owns the resource, hook integration, and shared regression boundary.
There are no parallel-safe work orders. Splitting the resource from the hook
would require both tasks to edit the same lifecycle contract and tests.
## Risks
- React Strict Mode can subscribe, release, and subscribe again during mount.
The resource must rejoin an unresolved entry instead of sending a second
freshness request.
- A workspace can be reloaded with the same ID but a new generation. Omitting
the generation from the key could apply stale synchronization state.
- Stopping only the in-flight request duplication would leave duplicate retry
schedules. The shared resource must own timers and reconnect transitions.
- Cleanup must not let one consumer stop retries required by another consumer.
- The change normalizes data ownership only. It must not alter desktop or
mobile rendering, touch targets, or navigation behavior.
## Open questions
None.
@@ -0,0 +1,150 @@
---
id: "01-coordinate-task-pr-sync-consumers"
title: "Coordinate task PR sync consumers"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001
acceptance_criteria:
- AC-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001.1
- AC-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001.2
- AC-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001.3
- AC-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001.4
- AC-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001.5
- AC-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001.6
- AC-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001.7
system_design:
- ../../specs/integrations/system-design/github-task-pr-sync-coordination.md
---
# Task 01: Coordinate task PR sync consumers
## Summary
Add one shared synchronization resource for each store, workspace context, and
task. Refactor `useTaskPR` to lease that resource while preserving its current
return contract and task PR store behavior.
## In scope
- Add the task PR sync resource and its test factory.
- Share initial, retry, reconnect, and manual refresh requests.
- Publish one loaded snapshot to all consumers.
- Reference-count consumers and clean up timers, observers, and stale entries.
- Guard response writes by resource generation and active workspace context.
- Integrate the resource with `useTaskPR` without changing callers.
- Add focused resource and multi-consumer hook regression tests.
## Out of scope
- Backend or protocol changes.
- UI component changes.
- Task PR unlink or tooltip hydration redesign.
- Session Git status subscription deduplication.
## Acceptance
- Two mounted `useTaskPR` consumers for the same scoped task send one initial
request and one request on each retry tick.
- Concurrent manual refresh calls return the same active completion and send
one request.
- Different task or workspace-context keys remain independent.
- One consumer release preserves the lifecycle; the final release stops later
retries and prevents stale publication.
- Permanent results stop retries. Reconnect starts one immediate request and
one fresh bounded retry window.
- Empty results, transient failures, terminal failures, discovered pull
requests, loaded state, and unlink behavior match the current hook contract.
## TDD sequence
### Red
- Extend `use-task-pr.test.tsx` with two consumers under one `StateProvider` and
assert that the current implementation sends duplicate initial and retry
requests.
- Add `task-pr-sync-resource.test.ts` cases for request joining, lease cleanup,
scope isolation, reconnect transitions, retry terminal states, and stale
responses. Confirm they fail before the resource exists.
### Green
- Implement the smallest store-scoped resource that satisfies the tests.
- Delegate `useTaskPR` synchronization and loaded state to the resource.
- Keep store selectors and unlink behavior unchanged.
### Refactor
- Keep resource state transitions explicit and separate from the React hook.
- Reuse `isCurrentWorkspaceContext` and the existing TaskPR scope types.
- Remove the superseded per-hook retry, request, reconnect, and loaded refs and
effects.
## Verification
```bash
cd apps/web && pnpm exec vitest run hooks/domains/github/task-pr-sync-resource.test.ts hooks/domains/github/use-task-pr.test.tsx
cd apps/web && pnpm run typecheck
cd apps && pnpm --filter @kandev/web lint
git diff --check
```
## Files likely touched
- `apps/web/hooks/domains/github/task-pr-sync-resource.ts`
- `apps/web/hooks/domains/github/task-pr-sync-resource.test.ts`
- `apps/web/hooks/domains/github/use-task-pr.ts`
- `apps/web/hooks/domains/github/use-task-pr.test.tsx`
## Dependencies
None.
## Risks
- Strict Mode effect replay can expose cleanup and re-acquisition races.
- A stale request can write into a later workspace context if either the store
or generation guard is missing.
- Ref-count errors can stop a needed retry or keep an orphan timer alive.
- A promise-only solution can pass concurrent-call tests while still producing
duplicate requests on later retry ticks.
## Parallelism
`sequential`
The resource and hook integration share one lifecycle contract and one focused
regression suite.
## Inputs
- `REQ-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001` and its system design.
- The confirmed per-instance state in
`apps/web/hooks/domains/github/use-task-pr.ts`.
- The store-scoped request registry in
`use-task-pr-tooltip-hydration.ts` and external-resource pattern in
`pr-commits-resource.ts`.
- The repeated `github.task_pr.sync` requests in the reported browser trace.
## Output contract
Report the files changed, the RED failure, GREEN and regression test outcomes,
typecheck and lint results, and any remaining lifecycle risk in the primary
session. Keep the requirement, design, plan, and work-order statuses in sync.
## Results
- Added the store-scoped task PR sync resource and deterministic resource tests.
- Refactored `useTaskPR` to lease the resource while preserving its return
contract, loaded behavior, refresh operation, and unlink behavior.
- RED: the multi-consumer regression observed two initial requests from the
previous per-hook implementation instead of one.
- GREEN: the focused resource and hook suites pass with 21 tests.
- The web typecheck and lint pass, and no rendered or mobile interaction changed.
- The resource invalidates publication when its lease is gone or its workspace
context is no longer current. WebSocket request timeouts remain owned by the
existing client.
- Unlink invalidates the scoped request generation after local removal, so an
in-flight response cannot restore the removed association.