mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:20:22 +01:00
## Thinking Path > - Paperclip runs agents in response to work on a task. > - A person can leave a comment while execution recovery holds that task. > - Wake-queue checks the recovery gate under the task lock. Heartbeat used to choose how to save the blocked input. > - The deferred-work worker later retries the saved receipt by ID. > - This change gives wake-queue responsibility for saving the input before it confirms deferral. ## Linked Issues or Issue Description **Current behavior** The gate and the write that makes a blocked wake recoverable have different owners. Heartbeat also reports an admitted deferral when an update to an existing receipt matches no row. **Proposed behavior** Let the recovery admission operation save the first receipt or update the existing one in the same transaction. Confirm admission only when the write succeeds. Keep replaceable automatic signals on their existing diagnostic path. **Reason and benefit** Changes to recovery admission can now be checked against one rule. A blocked comment must have a durable receipt and remain recoverable across delivery attempts. Related changes include [#22292](https://github.com/paperclipai/paperclip/pull/22292) and [#22290](https://github.com/paperclipai/paperclip/pull/22290). ## What Changed - Added a transaction-bound deferral operation to wake-queue recovery. It handles existing receipts, saved input, and replaceable system signals. - Scoped retry updates to the company, issue, agent, deferred status, and receipt ID. A stale receipt cannot confirm admission or cause a new receipt to be inserted. - Kept case refusals and issue state callbacks in heartbeat. A saved comment uses the existing delivery worker and post-commit effects. ## Verification - Retried a saved comment by receipt ID through the real heartbeat and run-control entry points. While the hold remained, no run started. After the hold cleared, repeated retry delivered the comment to exactly one run. - Forced a rollback after the wake-queue Postgres adapter saved a receipt. The test observed the receipt within the transaction and confirmed its absence after rollback. Tested missing receipts and receipts for another issue or agent. The admission application test covers error propagation and post-commit effects when the transaction fails. - The test-only revision `9f443f9e6b` passed 9 focused PostgreSQL and recovery checks and all 15 issue-wake admission application tests. - The preceding production revision `eb37328472` passed the server TypeScript check, the module boundary check, and 498 tests across five queue and recovery suites. Twelve pairs of ordinary comments issued the same SQL before and after that production change (42 statements for a fresh wake and 35 for a join). - Both updated test files passed in full (249 tests). [CI attempt 3](https://github.com/paperclipai/paperclip/actions/runs/44572369812/attempts/3) passed on `9f443f9e6b` after retrying interrupted jobs. [Standard Greptile review](https://github.com/paperclipai/paperclip/pull/22332#issuecomment-7014835241) scored the same commit 5/5 with no open findings. ## Risks The affected path handles blocked admissions that may race a retry or a reassignment. Existing recovery gates, saved comment IDs, receipt identity, and notifications must survive that race. This change has no migration or new worker. The healthy admission path is expected to issue the same SQL. ## Model Used OpenAI Codex with GPT-6.2 Sol for implementation and verification. Codex directed and reviewed the change. ## 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>