Files
PaperClipAI/server
Nicky LeachandPaperclip f324238f73 Move fresh issue run and receipt writes into wake-queue (#22266)
## 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>
2026-11-18 19:24:39 -08:00
..