## Thinking Path
> - Paperclip agents take work from assigned tasks and from user
comments.
> - A fresh task run can include saved comments when the current agent
or a confirmed former assignee owns them.
> - Connected chat messages and resolved interactions have separate
authority and session requirements.
> - Heartbeat previously decided which receipts to adopt between the
three calls that saved a new run.
> - One wake-queue use case now selects the receipts and commits the
same run and comment lineage.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
Assignment and comment continuation when a task needs a fresh run.
**Subsystem affected**
Server task admission.
**Current behavior**
Heartbeat chooses the comment receipts to consume, reads their source,
and builds the final run context.
**Proposed behavior**
One application operation admits the run. Its Postgres adapter loads
eligible company and agent receipts under the issue lock. The caller
supplies the responsible user and records the specialized continuation.
**Additional context**
Builds on #22266. The existing release and queued-comment boundaries are
in #13136 and #13145.
## What Changed
- Keep exact resumed receipts separate from ordinary board comments.
Adopt a prior assignee’s comments only when the interrupted run proves a
handoff.
- Use the same canonical comment ID codecs for admission and dispatch.
- Test the assignment path with one or two saved comments and
independent chat and interaction receipts.
## Verification
On c957f8529c, 260 tests passed across the four admission, liveness and
responsible-user suites. The saved Grok interrupt route passed its
exactly-once continuation test. A separate Postgres run passed the
ordered comment and rollback checks, both reassignment cases, and the
company isolation test. Server typecheck and module boundaries passed.
Check the fresh admission and handoff cases in
`server/src/services/heartbeat/queue.test.ts`. Run `pnpm exec vitest run
server/src/__tests__/heartbeat-comment-wake-batching.test.ts
server/src/services/issue-queued-comment-queue.test.ts`, `pnpm --filter
@paperclipai/server typecheck`, and `node
scripts/check-module-boundaries.mjs`.
## Risks
Receipt selection controls which user input reaches the next agent. The
store requires the same company, issue and executor or a verified
handoff. Chat and interaction receipts preserve their independent
delivery.
## Model Used
OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.
## 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>
## Thinking Path
> - Paperclip manages AI agents at work.
> - Assigning a task or resuming it from a comment can create a queued
run.
> - The wake-queue module handles admission behind an active execution.
Heartbeat also writes the receipt and run when a new execution is
needed.
> - These writes share the issue lock. Splitting them across
transactions would allow duplicate or partially bound work.
> - This change puts the fresh writes in the wake-queue module under the
existing lock.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
Creating a queued run for an assigned or continued task.
**Subsystem affected**
Server task admission.
**Current behavior**
Heartbeat constructs the receipt and run, handles retry lineage, and
ties adopted receipts to the run.
**Proposed behavior**
Wake-queue owns receipt promotion, fresh-run construction, and receipt
binding. Heartbeat still selects saved comments and orders recovery
effects inside the same transaction.
**Additional context**
Earlier module boundaries were introduced in #13136 and #13145.
## What Changed
- Move fresh receipt, run, and binding writes to a transaction-bound
Postgres adapter.
- Keep explicit continuation and reconciled retry lineage in the
application layer.
- Scope receipt updates by company and durable promotion by agent. Cover
both predicates with a database test.
## Verification
On commit 7479acbd22, all 104 heartbeat queue tests passed using the
repository Postgres command runner. All 297 assertions passed in the
six-file sweep. The standalone cluster cleanup timeout also reproduced
on pristine base 92dbf39e6f after all 103 base tests passed.
`node cli/node_modules/tsx/dist/cli.mjs
packages/db/src/test-postgres-command.ts -- node
node_modules/vitest/vitest.mjs run
server/src/services/heartbeat/queue.test.ts`
Run `pnpm exec vitest run server/src/services/heartbeat/queue.test.ts
server/src/__tests__/heartbeat-comment-wake-batching.test.ts
server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts`. Run
`pnpm --filter @paperclipai/server typecheck` and `node
scripts/check-module-boundaries.mjs`.
## Risks
Changing write order can attach the wrong receipt or lose retry lineage.
The caller retains the transaction and the interleaved chat and recovery
effects. This is a structural change. No latency improvement is claimed.
## Model Used
OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.
## 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>