8.4 KiB
status, system, requirements, created, owners
| status | system | requirements | created | owners | |||
|---|---|---|---|---|---|---|---|
| draft | integrations |
|
2026-09-11 |
|
GitHub PR discovery health design
Ownership and mapping
REQ-INTEGRATIONS-GITHUB-PR-DISCOVERY-001 maps to query validation and association
below. REQ-INTEGRATIONS-GITHUB-PR-DISCOVERY-HEALTH-001 maps to failure state,
admission, projection, and recovery. Integration services own both outcomes.
Existing workspace authentication and frontend synchronization coordination
remain authoritative for credential selection and consumer leases.
Query validation and association
internal/github/graphql.go:prFieldsBlock supplies both branch and known-PR
batch queries. Select headRepository { id name nameWithOwner url }, not
cloneUrl. Decode url explicitly and derive the HTTPS clone URL through a
shared mapping that preserves host, owner, repository, and existing null rules.
Keep GH CLI JSON fields separate from GraphQL schema fields: CLI output is not
a schema authority. Do not rewrite checkout remotes or change clone policy.
Use the existing watch and association writers in service_pr_watch_batched.go,
service_pr_watch.go, and poller.go. Preserve fork-network resolution,
workspace-group attribution, explicit detached tombstones, and event publication.
The definitive-empty batch result must retain its existing no-repeat behavior.
Tests must inspect generated selections against a checked, minimal Repository field contract, in addition to exercising response conversion and persistence. Record the upstream schema reference in the fixture. A canned response that accepts any query cannot detect this defect.
Watch target reconciliation
Discovery AC .4 uses the same session repository/worktree target resolution
for watch creation and refresh. In internal/github/poller.go,
TaskBranchProvider.ResolveBranchForWatch carries session, repository, and
current branch identity. The orchestrator implementation lives in
event_handlers_github_watch_reconciliation.go; the poller does not choose a
task's primary branch for every watch.
The session inventory can contain one row per distinct worktree branch without repository identity. Expand each session once and do not pass an inventory row's branch as the primary repository fallback; load branches from the session's per-repository worktrees instead.
Resolve targets from the source session's task through
resolveSessionWatchTargets, matching creation's fallback and worktree rules.
watch.TaskID may name a workspace-group owner and remains the association
destination, not a substitute source of checkout identity. Reuse target
resolution without invoking effective-owner redirection for branch selection.
Keep an exact repository/branch match. Only select a replacement when there is exactly one distinct branch target for that repository and the current branch is absent. Missing session or repository identity, lookup failure, no matching targets, or multiple unmatched candidates leaves the watch unchanged. Never use a sibling repository as a fallback. Preserve single-repository checkout-branch precedence and real unambiguous rename handling.
Keep the existing pr_number = 0 atomic writer and collision handling.
Numbered watches, associations, detached tombstones, and attribution remain
unchanged. No migration or live database cleanup is required. Reconciliation
must reach a stable set of watch IDs and branches across repeated cycles;
tests include mixed numbered/searching watches and multi-branch sessions.
Delivery: watch reconciliation repair.
Failure state and admission
Add a service-owned runtime discovery-health component. Key each target by workspace ID, resolved credential cache scope/generation, repository identity, and branch. Multiple session watches for that target share admission and health. Keep a monotonic attempt generation and one active attempt per target. A batch claims each participating target; failure affects only targets in that batch. Unknown or unresolved aliases remain failures, not definitive empty results.
Store a bounded, sanitized category (invalid_query, rate_limited, or
unavailable), failure time, attempt generation, and optional retry deadline.
Do not retain raw provider payloads, query bodies, or credentials in UI state.
Remove target entries when no live watch needs them; clear the connection's
entries on credential replacement or workspace deletion. Service shutdown owns
any cleanup mechanism. No SQL migration or new perpetual polling loop is needed.
Classify GraphQL errors even on HTTP 200 at the shared decoded-error boundary. Do not rely only on GH CLI stderr or HTTP status. Keep generic authentication state separate: a valid login does not prove discovery works.
Use provider Retry-After/reset evidence when available. If a rate-limit error has no reliable deadline, allow a coalesced probe after 60 seconds, doubling the pause on continued failure up to 15 minutes. Invalid-query failures retry at most once per minute. The existing poller performs due probes; manual sync obeys the same admission rule. Do not retry an invalid or throttled batch by immediately issuing the same query once per watch. Transport fallback remains available when it can succeed and admission permits it.
Quota snapshots remain numerical observations in RateTracker; they do not
own discovery recovery. A /rate_limit refresh may replace a reported number
but cannot clear the separate failure or retry deadline. This avoids asserting
that a full budget is proof of availability. A later successful query for the
same target clears its failure, including a definitive empty result. A success
from an older attempt cannot clear newer evidence. One target's success does
not clear another target's failure.
Projection and presentation
Add optional pr_discovery_health to workspace GitHub status: state
(unknown, healthy, degraded), failed_target_count, last_failure_at,
category, and optional retry_at. Summarize the newest outstanding failure;
retain degraded state while any current target has an unresolved failure.
Absence means unknown, not confirmed healthy. Do not expose target details
outside existing repository authorization.
Publish a scoped discovery-health event with credential generation and a
monotonic revision. Update Go wire types and the corresponding frontend types
in lib/types/github.ts and lib/types/backend.ts. HTTP status and WS projections must share revisions;
an older HTTP refresh cannot overwrite a newer event. Reject mismatched workspace
or credential generations in github-slice.ts and lib/ws/handlers/github.ts.
Existing quota events keep their meaning.
Render a localized warning under the workspace identity summary in
github-status.tsx. Show the same operation, category, and timestamp before
quota numbers in github-rate-limit.tsx. During refresh, preserve existing
content and indicate busy state through the current refresh control. Do not
label authentication invalid merely because discovery failed.
Reuse GitHubAccessHelp: desktop focus/hover disclosure and coarse-pointer
Drawer. This is the closest shipped mobile exemplar and matches the mobile
language's temporary-details surface. Keep one internal scroll owner for long
drawer content, safe-area spacing, focus return, and 44px touch targets.
The inline warning wraps within the settings column on both viewports.
Validation and operational boundaries
Use deterministic clocks and attempt gates to prove error, full quota refresh, continued degradation, due probe, and actual recovery. Include mixed targets, credential replacement, out-of-order HTTP/WS completion, and nullable fork data. Backend integration tests prove persistence and event identity. Browser tests prove a warning survives disclosure refresh and clears only with newer recovery. They must assert the phone drawer, not a tooltip opened by a simulated tap.
No live task is repaired by this package. After deployment, normal discovery can link eligible PRs. Waiting for quota reset cannot repair invalid code.