DottaandPaperclip f6d2a6b79e refactor(heartbeat): extract queue admission and wakeup dispatch (#15626) ...

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The heartbeat service admits and dispatches agent runs.
> - Earlier extractions separated workspaces, preparation, state,
retries, and restart recovery.
> - Queue admission and wakeup dispatch still occupy more than 4,200
lines in the main service.
> - Their transaction, budget, ownership, and concurrency checks must
stay together.
> - This pull request moves those operations into one queue module and
adds boundary tests.
> - Reviewers can inspect queue policy separately from adapter
execution.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The structure and testability of heartbeat queue admission and wakeup
dispatch.

**Subsystem affected**

server/ — orchestration services.

**Current behavior**

Wake coalescing, queued claims, dispatch, daily limits, and native wake
intents live inside `heartbeat.ts`.

**Proposed behavior**

Keep their behavior in `server/src/services/heartbeat/queue.ts`. Bind
lifecycle callbacks and shared ownership with `createHeartbeatQueue`.

**Reason and benefit**

This removes 4,243 lines from `heartbeat.ts`, leaving 14,201 lines. The
queue module has 4,576 lines and keeps related policy together in one
file.

**Breaking changes**

None. The service methods, public exports, database transactions, locks,
and execution gates keep their existing behavior.

**Additional context**

Continues #15622 and the earlier merged heartbeat extractions. A search
of open and closed PRs found no duplicate queue extraction. Related
#15600 adds a new experimental scheduler; this change preserves the
current scheduler policy. This does not add a roadmap feature.

## What Changed

- Move wake coalescing and batching, queue claims, daily caps,
concurrency and priority checks, timer admission, queue resumption, and
native status wake intents into `heartbeat/queue.ts`.
- Pass lifecycle callbacks and the existing process-wide execution and
wakeup sets into the factory. Preserve construction order with three
forwarding callbacks.
- Keep adapter execution, cancellation, and status writes in the
service.
- Add nine tests for inert construction, scheduling suppression, shared
wake tracking, policy wiring, claim release, newer ownership, and budget
gates.
- Document the queue module boundary in `doc/DEVELOPING.md`.

## Verification

- Before extraction: 133 tests passed across nine existing suites.
- After extraction: **150 tests passed across 12 files**, including all
nine new module tests and real PostgreSQL coverage.
  ```sh
pnpm exec vitest run server/src/services/heartbeat/queue.test.ts
server/src/__tests__/heartbeat-queued-run-claim-isolation.test.ts
server/src/__tests__/heartbeat-start-lock.test.ts
server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts
server/src/__tests__/heartbeat-scheduling-suppression.test.ts
server/src/__tests__/heartbeat-comment-wake-batching.test.ts
server/src/__tests__/heartbeat-running-followup.test.ts
server/src/__tests__/heartbeat-dependency-scheduling.test.ts
server/src/__tests__/heartbeat-auto-checkout.test.ts
server/src/__tests__/heartbeat-archived-company-guard.test.ts
server/src/__tests__/heartbeat-task-drain-admission-release.test.ts
server/src/__tests__/heartbeat-worktree-suppression.test.ts
  ```
- Additional control and recovery coverage: **390 tests passed across
five files**. Combined focused coverage is **540 passing tests across 17
files**, with no skips.
  ```sh
pnpm exec vitest run
server/src/__tests__/heartbeat-process-recovery.test.ts
server/src/__tests__/heartbeat-native-cleanup-admission.test.ts
server/src/__tests__/heartbeat-native-status-context.test.ts
server/src/__tests__/heartbeat-task-drain.test.ts
server/src/services/chat-control-admission-retry.test.ts
  ```
- Full `pnpm -r typecheck` and `pnpm build` passed.
- Full local `pnpm test:run` was started and then stopped after the full
CI suite passed. It did not finish and is not counted as a full local
pass.
- All **54 current-head checks passed**; two optional Storybook checks
were skipped. This includes the full general and serialized test matrix,
typechecks, build checks, Runner verification, and canary dry run. [CI
run](https://github.com/paperclipai/paperclip/actions/runs/37847175452).
- Greptile completed on head `cc0001961a052a716d81c136929f89312e0b5dee`
with **5/5 and no actionable findings**. There are no review threads or
merge conflicts.
- Structural comparison confirms 31 moved function bodies and eight
declarations match the originals. Remaining service function bodies and
all 140 public exports are preserved.
- An initial local run skipped database tests because the host had
exhausted its PostgreSQL shared-memory slots. After verified stale
segments were cleared, all 150 focused tests ran and passed with no
skips.

## Risks

Moving closures can break shared ownership or callback construction
order. The factory receives the original sets and explicit callbacks. It
starts no work during construction. Transaction boundaries,
compare-and-set predicates, budget gates, cleanup holds, and lock
ordering stay intact. This PR has no schema or API changes.

## Model Used

OpenAI GPT-6 via Codex. The exact serving model ID and context window
were not exposed in this session. Used reasoning, repository inspection,
shell tools, and code execution.

## 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-10-09 07:59:19 -05:00

..

scripts

feat(runner): add experimental OpenAI Dot provider over MCP Events (#15402)

2026-10-07 19:11:50 -05:00

src

refactor(heartbeat): extract queue admission and wakeup dispatch (#15626)

2026-10-09 07:59:19 -05:00

test-baselines

…

CHANGELOG.md

…

package.json

build(deps): bump @modelcontextprotocol/sdk from 1.30.0 to 1.31.0 (#15361)

2026-10-08 11:05:20 -07:00

tsconfig.json

…

vitest.config.ts

fix: make accounting durable and synchronize cost reporting (#14997)

2026-10-06 22:26:48 -07:00