mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 20:12:20 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The GitHub chat channel keeps each unresolved "Paperclip Review" check in step with its task and run. A background queue (`chat-github-review-checks`) rebuilds its checks when a hint arrives > - Each run milestone (`notifyChatRunMilestones`) sends this queue a company-wide hint, also when the milestone knows the issue. Each company-wide hint rebuilds every unfinished check of the company and reads its full state again. Passes are limited to one a second > - So in a company with a steady stream of run milestones, each unresolved check reads its whole state about once a second, although nothing about it changed > - On a hosted test database the five state statements of a review check ran 10.3 times a second each. #21608 removes the endless 5-second head poll. This is the second cause > - This pull request sends the issue with the hint, rebuilds only the checks of that issue, and rebuilds for a company-wide hint at most once every 30 seconds > - The benefit is that run activity no longer makes every unresolved check of the company read its state each second. A run change of the check's own task still publishes at once ## Linked Issues or Issue Description Refs #21608 (backs off the head poll of an unresolved check; the other cause of the same hosted load). Refs #21580 (the same 30-second rule for the GitHub response sweeps). Refs #18384 (the same rule for external objects). **What happened?** On a hosted test database with zero active runs, the five statements of `githubReviewCheckState` (`chat_endpoints`, `chat_github_reviews`, `chat_message_links`, the `heartbeat_runs` `wakeCommentId` lookup and `chat_deliveries`) ran 10.3 times a second each. One source is the rebuild of the review check queue for company-wide hints. **Current behavior** `notifyChatRunMilestones` sends `{"companyId": ...}` to `chat-github-review-checks` for every milestone, also when its scope has an issue. The queue scope has no issue field. So each milestone rebuilds every received and retryable check of the company, and calls `githubReviewCheckState` for each received check. **Proposed behavior** A milestone with an issue sends `{"companyId", "issueId"}`. The queue matches a check to an issue through the issue of its latest review for the pull request head. This is the same review that `githubReviewCheckState` reads. A company-wide hint (company ID only) rebuilds at most once every 30 seconds. All narrower hints, the startup scope (`*`) and saved deadlines are not changed. **Steps to reproduce** 1. Admit a GitHub review check that stays unresolved (a review with no run that the check can find). 2. Send a run milestone for the company once a second (for example, status changes of other runs). 3. Count statements. Each hint rebuilds the check and reads its full state. ## What Changed - `review-check-work.ts`: the scope has an optional `issueId`. `page()` reads the issue of the latest review for the check head (`reviewIssueId`, through the existing `chat_github_reviews_pull_idx` index) and filters on it for an issue scope. `matches()` uses the same value. - `review-check-work.ts`: set `reconstructionIntervalMs` to `githubReviewCheckReconstructionIntervalMs`: 30 seconds for a company-only scope, 0 for all other scopes. - `chat-run-milestone-notifications.ts`: send the issue with the review check hint when the milestone has one. - `chat-channels.integration.test.ts`: two regression tests on the real queue, the real `dispatch` and embedded PostgreSQL with a controlled clock. The test helper now counts only the state read of `chat_github_reviews`, not the new subquery in `page()`. ## Verification Red/green regression tests: - `cd server && npx vitest run src/__tests__/chat-channels.integration.test.ts -t "company-wide hints at most once per interval|at once from its issue milestone"` - Red (without the fix): `expected [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ] to deeply equal [ 1, +0, +0, +0, +0, +0, +0, +0, …(2) ]`. Each of 10 company-wide hints read the check state. The milestone hint was `{"companyId"}` only. - Green: 2 of 2 pass. The first company-wide hint reads the state once. The next 9 read nothing. After 30 seconds the waiting hint reads it once. A hint for the check's issue reads it at once each time. A hint for another issue or another company reads nothing. A real `notifyChatRunMilestones` with the check's issue publishes `in_progress` on the next pass and resets the head poll interval. Statement counts for one unresolved check with one company-wide hint each second (120 simulated seconds, real queue and `dispatch`, embedded PostgreSQL): | | Statements a second | Check state reads a second | | --- | --- | --- | | Before | 6.0 | 1.0 | | After | 0.2 | 0.033 | In the real-coordinator reproduction of #21608, one hint each second raised one stuck check from 0.70 to 1.67 state reads a second and from 8.4 to 15.2 statements a second. Other checks: - `cd server && npx vitest run src/__tests__/chat-channels.integration.test.ts -t ithub`: passed, including all review check queue tests. - `cd server && npx vitest run src/__tests__/native-status-reassessment-work.test.ts src/__tests__/chat-run-milestone-work.test.ts src/services/native-runtime/external-chat-wait.integration.test.ts src/services/chat-github-review-repair.test.ts src/__tests__/idle-completed-history.test.ts src/__tests__/chat-admission-condition.test.ts src/__tests__/app-private-hostname-gate.test.ts`: 518 passed. - `cd server && node ../scripts/run-tsc.mjs` and `node scripts/typecheck-layers.mjs` (with test layers): passed. - `pnpm verify --explain` retains 2,718 test files conservatively, so I did not run it locally. Required CI supplies that coverage. ## Risks - A change that only a company-wide hint reports can take up to 30 seconds to reach a check. Company-wide hints now come from milestones without an issue (a run with no task, a comment merged into an active run) and from company authority changes. A run with no task cannot be the run of a review check. For a merged comment, the run's next status change sends an issue hint. The saved head poll deadline still applies. Each dispatch reads the full state again before it publishes. - An issue hint finds a check through the issue of its latest review for the head. If a run of another issue were the check's run, its change would wait for the next company-wide rebuild (30 seconds at most) or the next head poll. Run status and run identity milestones use the run's task issue, which is the review's issue for a GitHub review task. - The deadline reconciliation snapshot reports the queue as not reconciled while a company-wide hint waits (up to 30 seconds). This is the same as the GitHub response sweeps and the external-object refresh sweep. - `page()` reads one more indexed subquery for each row. It uses `chat_github_reviews_pull_idx`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic. Used through Claude Code with tool use (shell, file edits, and local embedded PostgreSQL reproductions). ## 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 - [x] 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>