## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The heartbeat and issue-comment routes decide when an assigned agent
wakes up and what context it receives.
> - Passive comments and annotation notes can currently wake assignees
even when no actionable state changed.
> - Accepted planning confirmations also need to preserve recent plan
comments so child-issue creation does not lose board/user constraints.
> - Runtime skill mentions should only send UUID ids into database
lookups, because legacy slug-like ids are not valid runtime skill ids.
> - This pull request tightens those wake and handoff rules in one
server-side branch.
> - The benefit is fewer noisy agent wakeups and better accepted-plan
continuation context without changing the task model.
## Linked Issues or Issue Description
Internal Paperclip task: [PAP-10535](/PAP/issues/PAP-10535).
Problem or motivation:
Passive comments and annotation notes could wake the current assignee
even when no actionable state changed, and accepted plan continuations
needed recent plan comments preserved in the wake handoff. Runtime skill
mentions also needed to ignore non-UUID ids before database lookup.
Proposed solution:
Tighten server-side wake routing so passive comments do not wake
assignees unless they reopen the issue, preserve mention-targeted
wakeups, include recent non-deleted plan comments in accepted
confirmation wake payloads, and guard runtime skill mention lookup to
UUID-like ids.
Alternatives considered:
Leaving passive assignee wakeups in place was rejected because it keeps
generating noisy non-actionable heartbeats. Treating every skill
mention-like token as a runtime skill id was rejected because legacy
slug-like ids are not valid runtime skill ids.
Roadmap alignment:
This aligns with the V1 control-plane heartbeat contract by making
wakeups more intentional and preserving handoff context for approved
plans.
This PR was split from the local `master` branch on June 7, 2026. It
covers server-side heartbeat and comment-wakeup behavior only. I
searched GitHub for duplicate/related PRs; the results were broader
heartbeat/run PRs, not this exact passive-comment and accepted-plan
handoff change.
## What Changed
- Filter runtime skill mention extraction so only UUID-like skill ids
are looked up.
- Stop ordinary issue comments and document annotation comments from
waking the current assignee unless the comment reopens the issue.
- Keep mention-targeted wakeups intact while removing passive assignee
wakeups.
- Include recent non-deleted issue comments in accepted-plan
confirmation wake payloads and task markdown.
- Updated focused server tests for the new wakeup and accepted-plan
behavior.
## Verification
- `git diff --check origin/master..HEAD`
- `NODE_ENV=test pnpm exec vitest run
server/src/__tests__/heartbeat-project-env.test.ts
server/src/__tests__/document-annotation-routes.test.ts
server/src/__tests__/issue-comment-reopen-routes.test.ts
server/src/__tests__/issue-update-comment-wakeup-routes.test.ts
server/src/__tests__/heartbeat-context-summary.test.ts
server/src/__tests__/issue-comment-redaction.test.ts`
- `NODE_ENV=test pnpm exec vitest run
server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
server/src/__tests__/issue-comment-redaction.test.ts
server/src/__tests__/heartbeat-context-summary.test.ts`
- `pnpm --filter /server typecheck`
- PR checks green on head `a379a0264d384510ff8ac4a47fb1e44d7b556f68`
- Greptile rerun green on head
`a379a0264d384510ff8ac4a47fb1e44d7b556f68`: 9 files reviewed, 0 comments
added, 0 unresolved review threads
## Risks
- Medium behavioral risk: agents will no longer wake for passive
comments unless mentioned or unless the comment reopens/resumes the
issue. That is intentional, but any workflow relying on passive assignee
comment wakeups should use explicit mentions or structured resume paths.
- Low migration risk: no schema or migration changes.
> 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
OpenAI Codex coding agent based on GPT-5, with shell, git, GitHub CLI,
and local test execution. Exact hosted model variant and context-window
size were not exposed by the runtime.
## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [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>
Dotta
4da79a88c6