mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The server runs issue recovery queues. The `stranded-assignments` queue checks assigned tasks that have no live run. One check costs about 22 database statements. > - #21729 made the 5-minute backstop re-check only tasks whose own rows changed. A change to the assignee agent's row counts as a change to every task of that agent. #21765 left out the agent's heartbeat writes. > - Execution start in `heartbeat.ts` writes `agents.status = 'running'` and `updated_at`, but not `last_heartbeat_at`. So each run start still makes every task of that agent "changed". The backstop window overlaps the previous one by 5 minutes, so each run start re-checks those tasks in two windows. > - On an almost idle hosted instance with one live run and a new run every few minutes, this gives bursts of about 1,450 checks for about 855 settled tasks, every few minutes. > - This pull request stops counting an agent row whose current status is `running` as a change to its tasks. > - The benefit is no re-checks of settled tasks beside a live run: 540 backstop checks in 30 simulated minutes drop to 6 (only the live task itself), and statements drop from 15,280 to 3,984. ## Linked Issues or Issue Description Refs #21729, #21765, #21795 No issue exists. This describes the problem with the fields of `.github/ISSUE_TEMPLATE/enhancement.yml`. **What existing behavior does this improve?** The changed-tasks backstop of the `stranded-assignments` and `assigned-work-invariant` recovery queues (`server/src/services/recovery/changed-tasks.ts`). **Subsystem affected** Server: issue recovery background work. **Current behavior** On staging at near idle (one live native run, about six new runs in 30 minutes), the stranded-check statement bundle runs in bursts of about 10 checks per second for about 2.5 minutes, then stops, then starts again about 4 minutes later. The tasks do not change. The cause: every run start writes the agent row without a heartbeat time. The backstop then loads every open task of that agent as "changed", in two consecutive windows. **Proposed behavior** An agent row counts as a change to its tasks only when the agent is not `running`. A pause, a resume, a hold or a configuration change of an idle agent still counts. A run's own task still gets its run hints and an immediate targeted check. **Reason and benefit** Recovery work becomes proportional to activity, not to the number of tasks held by an agent that just started a run. ## What Changed - `server/src/services/recovery/changed-tasks.ts`: the assignee-agent clause of `changedTaskCondition` now requires `ag.status <> 'running'`. A comment explains why run lifecycle writes are left out. - `server/src/__tests__/issue-recovery-live-run-agent-census.test.ts` (new): a staging-shaped census on the embedded test database with the real recovery workers and a fake clock. It seeds 800 settled in_review tasks with a succeeded latest run (3 workers, about 266 tasks each), 30 in_progress and 30 todo tasks without live runs, and one live native run. The run's agent gets the execution-start write, and the run publishes a run hint every 10 seconds for 30 simulated minutes. It also has three correctness guards: a task of the live agent whose own row changes without a hint is checked within the backstop bound; a resumed agent's task is checked within the backstop bound when the resume sends no hint; and the hourly full pass still checks every settled task while the run stays live. - `server/src/__tests__/issue-recovery-deadlines.test.ts`: a fast test that a run-start write is not a change and a pause during the run is a change. ## Verification Red on `origin/master` (fix reverted), green with the fix: | 30 simulated minutes beside one live run | before | after | | --- | --- | --- | | stranded checks, backstop wake | 540 | 6 | | stranded checks, hint wake (the live task's own run hints) | 178 | 174 | | checks of settled tasks | 534 | 0 | | database statements | 15,280 | 3,984 | | work signals beyond the run's own hints | 0 | 0 | - `npx vitest run src/__tests__/issue-recovery-live-run-agent-census.test.ts` (4 tests): the census fails on master with `expected 534 to be less than or equal to 50` and passes with the fix. The three guards pass. - `npx vitest run src/__tests__/issue-recovery-deadlines.test.ts -t "run start"`: fails on master, passes with the fix. - `npx vitest run src/__tests__/issue-recovery-deadlines.test.ts src/__tests__/issue-recovery-idle-backstop.test.ts src/__tests__/issue-recovery-activity-hints.test.ts src/__tests__/issue-recovery-signal-fanout.test.ts`: 31 passed, 1 skipped. - `tsc --noEmit -p server/tsconfig.json`: clean. ## Risks - Low risk. The change narrows one clause of the backstop query. No schema change. - If an agent is resumed and then starts a run in the same window, the resume no longer counts through the agent row. A resume already sends its own `pause_lifted` hint (`agent-lifecycle-driver.ts`), and the hourly full pass still covers every task. Before this change, a run finish already hid a resume the same way, because the finish writes a heartbeat time. - A configuration change of an agent while it runs is caught by its next idle write or by the hourly full pass, not by the 5-minute backstop. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used in Claude Code with tool use (shell, file edit, test runs). ## 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>