refactor(wake-queue): own blocked admission deferral (#22332)

## Thinking Path

> - Paperclip runs agents in response to work on a task.
> - A person can leave a comment while execution recovery holds that
task.
> - Wake-queue checks the recovery gate under the task lock. Heartbeat
used to choose how to save the blocked input.
> - The deferred-work worker later retries the saved receipt by ID.
> - This change gives wake-queue responsibility for saving the input
before it confirms deferral.

## Linked Issues or Issue Description

**Current behavior**

The gate and the write that makes a blocked wake recoverable have
different owners. Heartbeat also reports an admitted deferral when an
update to an existing receipt matches no row.

**Proposed behavior**

Let the recovery admission operation save the first receipt or update
the existing one in the same transaction. Confirm admission only when
the write succeeds. Keep replaceable automatic signals on their existing
diagnostic path.

**Reason and benefit**

Changes to recovery admission can now be checked against one rule. A
blocked comment must have a durable receipt and remain recoverable
across delivery attempts. Related changes include
[#22292](https://github.com/paperclipai/paperclip/pull/22292) and
[#22290](https://github.com/paperclipai/paperclip/pull/22290).

## What Changed

- Added a transaction-bound deferral operation to wake-queue recovery.
It handles existing receipts, saved input, and replaceable system
signals.
- Scoped retry updates to the company, issue, agent, deferred status,
and receipt ID. A stale receipt cannot confirm admission or cause a new
receipt to be inserted.
- Kept case refusals and issue state callbacks in heartbeat. A saved
comment uses the existing delivery worker and post-commit effects.

## Verification

- Retried a saved comment by receipt ID through the real heartbeat and
run-control entry points. While the hold remained, no run started. After
the hold cleared, repeated retry delivered the comment to exactly one
run.
- Forced a rollback after the wake-queue Postgres adapter saved a
receipt. The test observed the receipt within the transaction and
confirmed its absence after rollback. Tested missing receipts and
receipts for another issue or agent. The admission application test
covers error propagation and post-commit effects when the transaction
fails.
- The test-only revision `9f443f9e6b` passed 9 focused PostgreSQL and
recovery checks and all 15 issue-wake admission application tests.
- The preceding production revision `eb37328472` passed the server
TypeScript check, the module boundary check, and 498 tests across five
queue and recovery suites. Twelve pairs of ordinary comments issued the
same SQL before and after that production change (42 statements for a
fresh wake and 35 for a join).

- Both updated test files passed in full (249 tests). [CI attempt
3](https://github.com/paperclipai/paperclip/actions/runs/44572369812/attempts/3)
passed on `9f443f9e6b` after retrying interrupted jobs. [Standard
Greptile
review](https://github.com/paperclipai/paperclip/pull/22332#issuecomment-7014835241)
scored the same commit 5/5 with no open findings.

## Risks

The affected path handles blocked admissions that may race a retry or a
reassignment. Existing recovery gates, saved comment IDs, receipt
identity, and notifications must survive that race. This change has no
migration or new worker. The healthy admission path is expected to issue
the same SQL.

## Model Used

OpenAI Codex with GPT-6.2 Sol for implementation and verification. Codex
directed and reviewed the change.

## 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>
This commit is contained in:
Nicky LeachandPaperclip authored and GitHub committed 2026-11-19 10:16:52 -08:00
1 parent 417802ca87
commit 87ef7097b6
13 files changed
+256 -71

No files matched your search

@@ -313,6 +313,62 @@ describeEmbeddedPostgres("wake-queue postgres adapter", () => {
});
});
it("saves the blocked comment receipt inside admission and rolls it back when admission fails", async () => {
const companyId = await seedCompany();
const agentId = await seedAgent({ companyId });
const issueId = await seedIssue({ companyId, assigneeAgentId: agentId });
const authorUserId = randomUUID();
const [comment] = await db.insert(issueComments).values({
companyId, issueId, authorType: "user", authorUserId, body: "Please continue.",
}).returning();
const condition = { recoveryActionId: randomUUID(), reason: "execution_recovery", message: "Waiting for recovery." };
const failure = new Error("Admission failed before commit");
await expect(createPostgresIssueWakeAdmission(db)({ companyId, issueId }, async (tx, { deferBlockedWake }) => {
await expect(deferBlockedWake({
commentId: comment.id, contextSnapshot: { issueId }, condition,
coalesce: false, publications: [], nextAction: "Inspect the stopped run.",
request: { agentId, source: "automation", triggerDetail: "system", reason: "issue_commented",
payload: { issueId, commentId: comment.id }, requestedByActorType: "user",
requestedByActorId: authorUserId, idempotencyKey: null },
})).resolves.toEqual({ kind: "deferred", admitted: true });
const [receipt] = await tx.select().from(agentWakeupRequests);
expect(receipt).toMatchObject({ companyId, agentId, status: "deferred_issue_execution", runId: null,
payload: { issueId, commentId: comment.id, executionWait: condition,
_paperclipWakeContext: { wakeCommentIds: [comment.id] } } });
throw failure;
})).rejects.toBe(failure);
expect(await db.select().from(agentWakeupRequests)).toEqual([]);
});
it.each(["issue", "agent", "missing"])("ignores a recovery retry with a %s receipt mismatch", async mismatch => {
const companyId = await seedCompany();
const agentId = await seedAgent({ companyId });
const issueId = await seedIssue({ companyId, assigneeAgentId: agentId });
const receipt = {
companyId,
issueId: mismatch === "issue" ? await seedIssue({ companyId }) : issueId,
agentId: mismatch === "agent" ? await seedAgent({ companyId, name: "Other agent" }) : agentId,
};
const requestId = await seedDeferredWake(receipt);
const [before] = await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.id, requestId));
await createPostgresIssueWakeAdmission(db)({ companyId, issueId }, async (_tx, { deferBlockedWake }) => {
const publications: Parameters<typeof deferBlockedWake>[0]["publications"] = [];
const outcome = await deferBlockedWake({
existingRequestId: mismatch === "missing" ? randomUUID() : requestId, contextSnapshot: {}, coalesce: false, publications,
condition: { recoveryActionId: null, reason: "execution_recovery", message: "Waiting." }, nextAction: "Wait.",
request: { agentId, source: "automation", triggerDetail: "system", reason: "issue_commented",
payload: null, requestedByActorType: "user", requestedByActorId: null, idempotencyKey: null },
});
expect(outcome).toEqual({ kind: "deferred" });
expect(publications).toEqual([]);
return outcome;
});
expect(await db.select().from(agentWakeupRequests)).toEqual([before]);
expect(await db.select().from(activityLog)).toEqual([]);
});
it("checks conversation reset eligibility using the row refreshed under the admission lock", async () => {
const companyId = await seedCompany();
const agentId = await seedAgent({ companyId });