Files
PaperClipAI/server
DottaandClaude Opus 5.5 61c315ebab perf(chat): keep GitHub review check deadlines on company-wide rebuilds (#21725)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The GitHub chat channel shows a check run on each pull request it
reviews. The review-check sweep (`review-check-work.ts`) keeps one
`github_review_check` action per check. It republishes the check when
its status changes (queued, running, completed) and polls the pull
request head on a saved deadline.
> - Each time the sweep loads its checks, it computes the current check
status of every `received` check (`githubReviewCheckState`: 3–5
statements) to see whether the status changed.
> - Run lifecycle changes anywhere in a company send a company-wide
hint. So the sweep rebuilds every company's checks every 30 s and
recomputes the status of every waiting check, even when nothing about
those checks changed.
> - This pull request keeps the saved poll deadline on a company-wide
rebuild and reads the status only on targeted hints, at startup, and in
`check()`.
> - The benefit is that an idle company with many waiting checks costs
one page read per rebuild instead of 3–5 statements per check.

## Linked Issues or Issue Description

Refs #21705, #21711 (the same class of idle reload in the GitHub
response sweeps).

No issue exists. This describes the problem with the fields of
`.github/ISSUE_TEMPLATE/bug_report.yml`.

**What happened?**

On paperclip.staging at 89de6cbe3e (2026-11-15, 04:47–04:51Z, near idle
at about 0.4 HTTP requests/s), the statements of
`githubReviewCheckState` each ran at about 3/s:

- `select … from chat_github_reviews where endpoint_id … and
repository_id … and pull_number … and head_sha … order by created_at
desc limit 1` (all columns: id, company_id, endpoint_id, issue_id,
run_id, repository_id, …) at 3.04/s;
- `select chat_message_links.comment_id from chat_deliveries join
chat_message_links …` at 3.04/s;
- `select id, status from heartbeat_runs where company_id = $1 and
agent_id = $2 and context_snapshot->>'wakeCommentId' in (…)` at 3.04/s.

Staging has 84 GitHub review checks waiting on runs that have not
started. 84 checks reloaded every 30 s is 2.8 status computations per
second. That matches the observed rate.

**Root cause**

`registerGitHubReviewCheckWork` loads with
`githubReviewCheckReconstructionIntervalMs`, which allows one
company-wide rebuild every 30 s. Run lifecycle changes elsewhere in the
company keep sending `{ companyId }` hints, so the rebuild runs every 30
s. `entry()` calls `githubReviewCheckState` for every `received` row on
every load, only to see whether the status differs from the published
one. A waiting check's status does not change until its review, its run,
its delivery or its connection changes.

**Expected behavior**

A company-wide rebuild reads the waiting checks without recomputing each
status. A change to a check's run or pull request still publishes
promptly.

**Steps to reproduce**

1. Create 30 `received` GitHub review checks whose published status is
`queued`, with a poll deadline 1 hour ahead.
2. Register the review-check sweep. Send a company-wide hint every 30 s.
3. On master, each rebuild runs one page read plus 2–5 statements per
check.

**Paperclip version or commit**

master at 5acf27bc3b.

## What Changed

- `server/src/services/chat-channels/github/review-check-work.ts`:
- A company-wide load (company scope with no endpoint, repository,
number or task) does not call `githubReviewCheckState`. It keeps each
check's saved deadline: the head-poll `retryAt`, or the lease expiry.
Dispatch reads the current status anyway when that deadline comes.
- Startup (no scope) and targeted loads (endpoint, repository, pull
request or task) still read every status, as before. So do `check()` and
dispatch.
- Run lifecycle changes send `{ companyId, issueId }` for the run's
task, and publication lease releases send the pull request scope. Both
still publish a status change at once.
- New `mergeEntry`: an entry from a rebuild that did not read the status
keeps an earlier due time that a status read found. A company-wide
rebuild never postpones a pending publication. `check()` reads the
status again before it dispatches.
- `server/src/services/chat-channels/github/review-check-work.test.ts`
(new, real PostgreSQL):
- `does not recompute the status of every waiting check on each company
rebuild`
- `still publishes a check promptly when its review run starts` (a
task-scoped hint after a review run starts makes only that check due)

- `server/src/__tests__/chat-channels.integration.test.ts`:
- `publishes a local change at once and still recovers a missed head
after backing off` used a company-wide hint to stand for the review run
starting. It now sends the task-scoped hint that a run milestone sends,
and still expects the `in_progress` publication at once.
- `rebuilds GitHub review checks for company-wide hints at most once per
interval` is now `reads no GitHub review check status for company-wide
hints and still reads it for the check's task`. Company-wide hints read
0 statuses. Hints for the check's task still read 1, and hints for
another task or company read 0.

No GitHub check content changes. The published status, title and
conclusion are computed as before.

## Verification

- `pnpm vitest run
src/services/chat-channels/github/review-check-work.test.ts` (server),
30 waiting checks, 4 company rebuilds:
  - master: 244 statements, with 120 check status computations (red).
- this branch: 4 statements (one page read each), with 0 status
computations (green). A task-scoped hint still makes the started check
due at once.
- `pnpm vitest run src/services/chat-channels/github/`: 8 files, 62
passed.
- Related suites (`chat-channels.integration.test.ts`,
`app-private-hostname-gate.test.ts`, `idle-completed-history.test.ts`,
`chat-github-review-repair.test.ts`) filtered to review-check, GitHub,
history and hostname tests: 702 passed before the integration-test
updates below; after updating the two review-check tests, the 15
review-check tests pass.
- `pnpm typecheck` (server): passed.

## Risks

- A status change that sends only a company-wide hint is now published
at the check's next poll deadline, not at the next company rebuild. The
poll backs off to at most 5 minutes. Run lifecycle changes for a review
run carry its task, and connection or configuration changes are also
checked by dispatch, so this affects only hints that name no task or
pull request.
- Startup still reads every status, so recovery after a restart is
unchanged.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, local PostgreSQL tests) and
extended reasoning.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 23:56:53 -06:00
..