mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 06:01:49 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - A person sends a message on a task, an agent run starts, and the
agent answers with a task comment
> - A native run normally finishes in its live heartbeat, which commits
the result and posts the reply in one pass
> - The result commit worker also commits native results. It races the
live heartbeat as soon as the workspace save succeeds, and it often wins
> - That worker skipped reply presentation and left the reply to the
presentation worker, which often posted it many minutes later
> - The task showed its new status (for example "blocked") with no
reply, so the person thought the message did not run
> - This pull request makes the result commit worker post the reply in
the same pass
> - The benefit is that the reply appears when the run finishes,
whichever path finishes it
## Linked Issues or Issue Description
**What happened?**
A person commented on a task. A run started one second later, and the
agent wrote its answer in about one minute. The run finished and the
task changed to "blocked", but no reply appeared for 8.5 minutes. The
person checked the task and saw no answer.
**Expected behavior**
The agent's reply appears on the task when the run finishes.
**Steps to reproduce**
1. Run a native agent on a task. The agent reports a result (for example
`blocked`) with a final reply.
2. The live heartbeat saves the workspace. The result commit worker
commits the result before the heartbeat's own finalizer does.
3. The run is "succeeded" and the task status changes, but the task has
no reply.
4. The reply appears only when the presentation worker later picks up
the run.
**Evidence**
On one staging company, 135 recent succeeded runs had a reply comment:
| Path that finished the run | Runs | Reply delay after the run ended |
| --- | --- | --- |
| Live heartbeat (reply posted inline) | 90 | 1–16 s |
| Result commit worker (reply left to the presentation worker) | 45 | 0
s – 3,864 s; 29 of 45 took over 30 s |
All 45 slow-path runs have no live completion write (no exit code, no
log size). Traces confirm that the live `execution.native_finalize` and
`completion.*` steps did not run for these runs.
**Paperclip version or commit**
`master` at 904c01d1a3
**Deployment mode**
Hosted (staging cloud). The defect is in server finalization, so it
applies to all deployment modes that use the native runtime.
## What Changed
- The result commit worker no longer passes
`skipNativeResponsePresentation`. After it commits and projects the run,
it runs the same idempotent reply presentation step that the live
heartbeat and the retry paths use.
- The presentation worker stays the retry owner. If the inline attempt
fails or is refused, the run stays a presentation candidate, as before.
- Review responses are still left to their own worker
(`skipNativeReviewResponse` is unchanged).
## Verification
- Red/green test in
`server/src/services/native-runtime/native-blocked-reply-recovery.test.ts`:
"posts the agent's reply when the result commit worker finishes the run
instead of the heartbeat". It drives the real `nativeResultCommitWork`
worker for a blocked run whose workspace save succeeded.
- Red on `master`: the task is blocked and the run succeeded, but the
task has no comment.
- Green with this change: the agent's final reply is posted once, and
the presentation worker has no remaining candidate.
- `cd server && npx vitest run
src/services/native-runtime/native-blocked-reply-recovery.test.ts
src/__tests__/native-result-commit-work.test.ts`: 26/26 pass.
- `pnpm verify` on the change.
## Risks
- Low risk. The presentation step is idempotent: it locks the run,
records `presentationDecision.commentId`, and never posts twice. The
live heartbeat and the retry paths already call it inline.
- The result commit worker does slightly more work per committed run
(one presentation transaction, typically 30–500 ms on staging).
- Not addressed here: why the result commit worker wins the race against
the live heartbeat in about a third of runs. The reply no longer depends
on that race.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use (shell,
browser, code execution) in Claude Code.
## 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
Refs #21169
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>