Files
PaperClipAI/doc
Nicky Leach 7ffc58a612 refactor(wake-queue): enforce recovery before task admission (#22292)
## Thinking Path

> - Paperclip admits assignments and task comments while it holds the
task lock.
> - A task can have a recovery hold. An explicit continuation can
authorize additional work.
> - A wake can join an active execution after a provisional check. A
fresh run must settle the continuation in the transaction that creates
the run.
> - Heartbeat previously received both admission functions before either
check ran.
> - Make the wake-queue module release each function after the
corresponding recovery check passes.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Enforce recovery eligibility at the entry points that attach a wake to
an issue execution or create a fresh run.

**Subsystem affected**

Wake-queue and heartbeat issue admission.

**Current behavior**

Heartbeat selects when to read the blocker and apply the explicit
continuation before invoking the admission writers.

**Proposed behavior**

Wake-queue controls access to its two admission writers after the task
is locked. The same recovery and continuation services decide which work
may proceed.

**Additional context**

Depends on #22289. #22290 changes the storage cost of the blocker check
in a separate layer.

## What Changed

- Bind the recovery read to the issue and transaction selected by
wake-queue. Read the current issue lock again after durable chat
authorization when required.
- Expose the busy writer after the preliminary continuation check
passes. Expose the fresh writer after the transaction applies any
required continuation.
- Preserve heartbeat’s existing ordering for system fallback, budget and
daily limits, task retry, and durable receipts.

## Verification

On bde1778161, 420 tests passed across five suites. Server TypeScript
and the module dependency check passed. Final head f9d44c7728 removes
three inline comment lines. All five affected application and locked
PostgreSQL cases passed again on that commit. End-to-end fixture SQL and
lock counts were identical on the parent and the ownership layer. The
application tests exercise blocked recovery, provisional permission
followed by a refusal, and ordinary fresh admission. The PostgreSQL
tests cover current authorization state, scoped writes, rollback, and
deferred delivery.

GitHub selected middle-stack verification. All applicable checks passed
on f9d44c7728. [CI
run](https://github.com/paperclipai/paperclip/actions/runs/44461026141)
· [Standard Greptile review,
5/5](https://github.com/paperclipai/paperclip/pull/22292#issuecomment-6999993272)

## Risks

An explicit continuation can settle a hold. Settling it before the later
gates could lose work if admission declines the wake. The final check
stays immediately before fresh admission in the same transaction.
Heartbeat still owns specialized receipt and fallback paths.

## Model Used

OpenAI GPT-6.2 Sol (gpt-6.2-sol) implemented the change. OpenAI Codex
directed and qualified it.

## 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
2026-11-19 07:23:03 -08:00
..
…