mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The wake queue holds new input for a task while an agent run is active, and releases it when the run ends > - A person's comment on a task always reopens the task when the run that closed it did not receive the comment > - A restart test found a person's comment that was posted while the run was finishing. The run marked the task done and no later run started. The comment was lost > - The comment joined a deferred child-completion wake that a system actor requested. The release step only looked at the wake requester, which was "system", so it did not see the person > - This pull request makes the release step look at who wrote the undelivered comments in the wake > - The benefit is that a person's comment is never dropped because it shares a queued wake with system work ## Linked Issues or Issue Description **What happened?** A person posted a comment on a task while the assigned agent's run was active. The run then marked the task done. The task stayed done, and no run received the comment. The deferred wake that held the comment was cancelled with "Deferred execution wake no longer applies to a terminal task". **Expected behavior** The task reopens and a new run receives the person's comment. **Steps to reproduce** 1. Start a run for a task. 2. While the run is active, let the system defer a wake for the same task (for example, a child task completes). 3. Post a comment as a person. The comment wake merges into the deferred system wake. 4. Let the run mark the task done. 5. The task stays done. No run receives the comment. **Paperclip version or commit** `master` atb4fa1c7fb1(first seen atc5218f5ec4). **Relevant logs or output** The merged deferred wake had `reason = issue_execution_deferred` and `requestedByActorType = system`. Its payload held the person's comment id. The coalesced comment receipt had `requestedByActorType = user`. Release cancelled the merged wake as terminal-task work. ## What Changed - `getCommentSelfAuthorship` in the wake-queue Postgres adapter also returns `includesPersonComment`. This value is true when one of the wake's undelivered comments was written by a person and not by an agent run. - `promoteDeferredWake` reopens a done or cancelled task when `includesPersonComment` is true, also when the wake requester is the system. - The delivered-comment filter is not changed. A comment that a run already received does not reopen the task. - New embedded-Postgres tests in `heartbeat-comment-wake-batching.test.ts`: - A person's comment merges into a deferred child-completion wake during a run. The run closes the task. The task reopens and the next run receives the comment. This test is red on `master` with the exact production cancel reason. - Negative: the person's comment in the merged wake is the comment that the closing run received as its input. The task stays done and no new run starts. ## Verification - `cd server && npx vitest run src/__tests__/heartbeat-comment-wake-batching.test.ts src/modules/wake-queue` passes (15 files, 391 tests). - `cd server && npx vitest run src/__tests__/heartbeat-held-comment-wake.test.ts src/__tests__/heartbeat-issue-rewake-throttle.test.ts src/__tests__/heartbeat-answer-behind-settling-run.test.ts` passes (57 tests). - `cd server && npx tsc --noEmit` passes. - Red check: with only the source change reverted, the new positive test fails with `expected 'Deferred execution wake no longer app…' to be null`. - `pnpm verify` exits 2 (an opaque setup dependency). Required CI supplies broad coverage. ## Risks - Low risk. The change only adds a reopen reason for a done or cancelled task. The comment must be live, undelivered, not written by the finishing run, and written by a person. - A comment from a local CLI agent can carry a user id. The check excludes comments that have a creating run or an agent author, so these comments do not count as person comments. > 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 - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude Code with tool use (shell, file edits, 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>