mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - A person can add a comment to a task while the agent's run on that task is still working > - The comment must reach the agent once: in the running turn, or in one later turn > - In a restart-chaos wave, a comment that the running turn already read reopened the finished task, and the agent did the completion turn a second time 15 minutes later > - This pull request makes a read by the running turn count as delivery, and holds the comment behind the running run so the run's own release settles it > - The benefit is no reopened done task, no repeated completion turn, and an unread comment that is delivered when its run finishes, not after a slot wait and a stale cancellation ## Linked Issues or Issue Description **What happened?** Restart-chaos wave `w-20261112T181948-s7101`, task t005 (OpenCode, native Runner), during a two-server overlap deploy (K15). - 18:26:56 run A started on the old server. 18:26:55 traffic switched to the new server. - 18:27:03.953 a board user posted a follow-up comment. The new server handled it. Run A was not in that process's `activeRunExecutions`, so `filterZombieCoalesceTarget` treated it as a zombie. Admission returned `proceed`, and the comment got its own queued run B (18:27:04.252). The queued run is not part of the release drain. - 18:33:32 run A called `get_task_history`, received the comment, applied it, and finished the task (`done`, 18:34:20). - Run B waited for an agent slot until 18:41:49 and was cancelled as `continuation_task_ownership_changed`. - `deferUndeliveredCommentsOfStaleRun` then saved the comment again. Its "unread" test is only "a run started before the comment and finished after it". `deliveredQueuedCommentIds` had no record of run A's read. The release drain reopened the task (done to todo, 18:41:51), and run C (18:49:22) posted a second "Task complete" summary. The harness grade `done_comment_once` failed. **Expected behavior** - A comment that the running turn received is consumed. No queued work outlives that run, and the task stays done. - A comment that the running turn did not receive is delivered once, through the normal comment-on-done-task path, when that run finishes. - A stale continuation is never re-issued for a comment that a completed run already read. **Steps to reproduce** 1. Start a native run on a task. 2. Post a person's comment while another server instance executes the run (or seed a queued comment run behind it). 3. Let the run read `get_task_history`, then finish the task. 4. Before this change, the queued comment run is cancelled as stale, the task reopens, and the agent runs a second completion turn. **Paperclip version or commit** `master` atef6d347f79. ## What Changed - `server/src/services/queued-comment-delivery.ts`: new run-log event `task_history.read` and `recordTaskHistoryRead`. `deliveredQueuedCommentIds` also counts a comment as delivered when a succeeded run of the assignee on that task read the comment's current revision (`historyReadDeliveredSql`). All existing consumers use this one check: the release drain liveness check, the stale-continuation save (`saveUndeliveredUserComments`), the ownership reconciler, and first-turn queued input. - `paperclip-runner-tool-authority.ts` and `runner-semantic-authority.ts`: `get_task_history` records the returned comment IDs and `updatedAt` values. The tool output does not change. A failed record is logged and leaves the comment owed, so it is delivered again. - `server/src/modules/wake-queue/application/use-cases.ts`: a comment follow-up for the same agent's `running` run is held as a deferred wake even when this process does not track that run. Before, a run executed by another server instance was treated as a zombie, and the comment got its own queued run that bypassed the release drain. Coalescing into an untracked run is still refused. - `doc/run-log-events.md`: documents `task_history.read`. - Regression tests in `server/src/__tests__/heartbeat-held-comment-wake.test.ts`. Intended behaviour chosen: in t005 run A received the comment mid-turn through its own `get_task_history` call (run events at 18:33:32 show the comment ID in the tool result, and the result says it added the follow-up line), so (a) applied. The fix makes that read the durable proof of delivery. A comment that no run read still follows the existing outbox: it is held behind the run and delivered once at the run's release, reopening the done task as a person's comment does. Envelope task history of another message's turn still does not count (unchanged doctrine and test). ## Verification - RED on master (`ef6d347f79`), `npx vitest run src/__tests__/heartbeat-held-comment-wake.test.ts -t "mid-turn|another server|held message"`: 3 failed, 1 passed. - "consumes a message the closing run read mid-turn, so its stale queued run reopens nothing": delivered 1, expected 0. - "holds a message behind a run another server is executing instead of queueing a run of its own": a queued run was created. - "settles a held message as soon as its run closes the task (read mid-turn: true)": delivered 1, expected 0. - The unread variant (delivered once, no cancelled stale run) passes on both, as intended. - GREEN with this change: all 4 pass. - Review follow-up (f43e79c3): a history read counts as delivery only for a succeeded run on the read revision. Tests cover an edit after the read (the stale queued run delivers the comment once) and reads by an edited or failed run (the comment stays owed). Full file: 37/37 pass. - Security-scan follow-up (239f0597): the delivery check probes each run binding (`native_issue_id`, `context_snapshot->>'issueId'`) through its own existing index with `offset 0`. It reads only the assignee's succeeded runs of the task with `finished_at >= ` the comment's current revision. It does not use `started_at`, because the t005 reader started before the comment. It stops at the first matching `task_history.read` event of each run through `heartbeat_run_events_company_run_idx`. No migration is needed. - Seeded plan (local PostgreSQL: 200 tasks, 4,000 runs, 1.2M run events, one comment read by one run), `EXPLAIN (ANALYZE, BUFFERS)`: - Before: 1.202 ms, 6,097 shared buffers. It scanned every event of all 21 runs of the task. - After: 0.030 ms, 23 shared buffers. It reads one index-matched run and one event. The full `deliveredQueuedCommentIds` call takes 1.55 ms. - New case: a succeeded run's read is not delivery when the comment was edited after that run finished. Full held-comment file: 38/38 pass. - `muse-control.test.ts` compared the whole run row after a `get_task_history` call. It now allows that read's own run-log append (`nextEventSeq` +1, `updatedAt`), and every other column must be unchanged. That CI failure (General tests server 2/12) came from this PR. "e2e shard (5/8)" failed because the self-hosted runner lost communication; that is not related to this PR. - Runner and Muse suites (`dot-runner`, `paperclip-control-plane-port`, `runner-prp-coordinator`, `historical-task-questions`, `paperclip-runner-tool-authority`, `muse-native-follow-up`, `muse-control`): 509/509 pass. Server `tsc` is clean. - Neighbouring suites: `heartbeat-held-comment-wake`, `src/modules/wake-queue/**`, `execution-continuation`, `paperclip-runner-tool-authority`, `first-turn-queued-input`, `heartbeat-comment-wake-batching`, `ownership-reconciliation-report`, `heartbeat-zombie-guard`: 555/556 passed in one loaded run. The 2 timeouts (one batching test, one reconciler `afterAll` hook) pass when run alone (1/1, 44/44). - `server` `tsc --noEmit`: clean. - The restart-chaos harness already grades this class (`done_comment_once` in staging-mix). No new cell is necessary. ## Risks - Product choice: a comment counts as delivered when a succeeded run read it through `get_task_history`, even if the model ignored it. This is the same trust that applies to a comment delivered as wake input. The alternative fails worse: it reopens a done task and repeats a completed turn. An edit after the read, or a reader run that fails, leaves it owed. - Legacy (non-native) adapters that read comments through the REST API do not write the record. Their behavior does not change. - A comment follow-up behind a truly dead running run now waits as a deferred wake until recovery releases that run. Before, its queued run also could not start until the lock was released. - Each `get_task_history` call appends one small run-log row. This is not in the path before `turn.start`. - Upgrade-safe: continuations queued by older builds still go through the dispatch stale check, and that path now reads the same delivery record. > 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, via Claude Code with tool use (shell, file edit, test execution). ## 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>