refactor(server): move the admission half of the deferred wake state machine into the wake-queue module (#13136)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The heartbeat service admits wake requests while an issue has an
active execution run.
> - That admission branch mixes wake policy, database reads, and
database writes in one service.
> - This structure makes the wake-queue boundary hard to test and
extend.
> - This pull request moves the admission policy and its database
adapter into the wake-queue module.
> - The result keeps heartbeat orchestration small and makes the
admission behavior testable in isolation.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The heartbeat service now delegates deferred wake admission to the
wake-queue module. The module keeps the existing merge, defer, and
ordinary-wake outcomes.

**Subsystem affected**

server/ — REST API and orchestration services.

**Current behavior**

The heartbeat service contains a 146-line branch that reads wake state,
chooses an outcome, and writes the result.

**Proposed behavior**

The wake-queue module owns the pure admission decision and the adapter
reads and writes. The heartbeat service calls one module method.

**Reason and benefit**

This boundary reduces service coupling and lets module tests cover the
admission policy. The change keeps the existing reason strings and
outcomes.

**Breaking changes**

None. The change preserves the current behavior and public API.

**Additional context**

This pull request follows [PR
#13132](https://github.com/paperclipai/paperclip/pull/13132), which
merged the first slice of this refactor. I searched GitHub for duplicate
and related pull requests before opening this pull request.

## What Changed

- Move deferred wake admission policy into
`server/src/modules/wake-queue`.
- Add module ports and a PostgreSQL adapter for the admission reads and
writes.
- Keep the existing wake outcomes and stored reason strings.
- Extend the module boundary check to reject service imports from the
application layer.
- Add unit and adapter tests for the moved behavior.

## Verification

- `node --test scripts/check-module-boundaries.test.mjs` passes.
- The `server/src/modules/wake-queue` suite passes 58 tests.
- The eight pinned heartbeat and queued-comment tests remain unchanged
and require CI verification.
- Every continuous-integration check must reach a terminal green state
before merge.

## Risks

The refactor changes the location of wake admission logic. A missed
adapter condition could change deferred wake behavior. The tests cover
the policy outcomes and the adapter writes. The residual tenant-scope
risk remains documented in the review record.

## Model Used

OpenAI Codex, GPT-5, tool use and code execution. The implementation
author ran the tests and prepared the commit set.

## 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>

server/src/modules/wake-queue/domain/policy.test.ts

@@ -3,6 +3,7 @@ import {
   decidePreDrain,
   decideQueuedCommentAction,
   decideReleaseRecovery,
+  decideWakeAdmission,
   decideWakeOutcome,
   deriveImmediateRecoveryContextLabels,
   type DeferredWakeOutcomeFacts,
@@ -10,6 +11,7 @@ import {
   type ImmediateRecoveryContextLabels,
   type PreDrainFacts,
   type ReleaseRecoveryFacts,
+  type WakeAdmissionFacts,
 } from "./policy.js";
 
 const basePreDrainFacts: PreDrainFacts = {
@@ -495,3 +497,50 @@ describe("deriveImmediateRecoveryContextLabels", () => {
     });
   }
 });
+
+const baseWakeAdmissionFacts: WakeAdmissionFacts = {
+  isSameExecutionAgent: true,
+  shouldDeferFollowupWake: false,
+  shouldQueueFollowupForRunningWake: false,
+  availableActiveExecutionRunPresent: true,
+};
+
+describe("decideWakeAdmission", () => {
+  const cases: Array<{
+    name: string;
+    facts: WakeAdmissionFacts;
+    expected: ReturnType<typeof decideWakeAdmission>;
+  }> = [
+    {
+      name: "coalesce: same execution agent, no defer condition, and a live coalesce target",
+      facts: baseWakeAdmissionFacts,
+      expected: { kind: "coalesce" },
+    },
+    {
+      name: "defer: same execution agent, but the running agent needs a fresh session",
+      facts: { ...baseWakeAdmissionFacts, shouldDeferFollowupWake: true },
+      expected: { kind: "defer" },
+    },
+    {
+      name: "defer: same execution agent, but the running turn must finish first",
+      facts: { ...baseWakeAdmissionFacts, shouldQueueFollowupForRunningWake: true },
+      expected: { kind: "defer" },
+    },
+    {
+      name: "defer: a different agent already holds the execution lock",
+      facts: { ...baseWakeAdmissionFacts, isSameExecutionAgent: false },
+      expected: { kind: "defer" },
+    },
+    {
+      name: "proceed: the zombie-run filter leaves no live coalesce target",
+      facts: { ...baseWakeAdmissionFacts, availableActiveExecutionRunPresent: false },
+      expected: { kind: "proceed" },
+    },
+  ];
+
+  for (const testCase of cases) {
+    it(testCase.name, () => {
+      expect(decideWakeAdmission(testCase.facts)).toEqual(testCase.expected);
+    });
+  }
+});

server/src/modules/wake-queue/domain/policy.ts

@@ -1,5 +1,7 @@
-// Pure decision rules for the release half of the deferred issue-execution
-// wake state machine:
+// Pure decision rules for the deferred issue-execution wake state machine:
+//   - the admission decision (decideWakeAdmission), applied to a new wake
+//     that arrives while an active execution run already holds the issue's
+//     execution lock
 //   - the pre-drain decision (decidePreDrain), applied once per lock
 //     acquisition, before the caller touches the deferred-wake queue at all
 //   - the per-wake decision, split into decideQueuedCommentAction and
@@ -11,6 +13,47 @@
 // This file only branches on that facts object; it never queries a
 // database, reads the clock, or reads the wake context payload directly.
 
+export type WakeAdmissionFacts = {
+  /** True when the active execution run's agent and this wake's own agent share an execution-agent-name key. */
+  isSameExecutionAgent: boolean;
+  /** True when a same-agent, still-running execution run must not absorb this wake and needs a new run boundary instead. */
+  shouldDeferFollowupWake: boolean;
+  /** True when a same-agent, running execution run must finish its current turn before this wake runs. */
+  shouldQueueFollowupForRunningWake: boolean;
+  /** True when the active execution run still stands as a live coalesce target after the zombie-run filter runs. */
+  availableActiveExecutionRunPresent: boolean;
+};
+
+export type WakeAdmissionDecision =
+  | { kind: "proceed" }
+  | { kind: "coalesce" }
+  | { kind: "defer" };
+
+/**
+ * Decides what a new wake does when an active execution run already holds
+ * the issue's execution lock: run into that run (coalesce), wait behind it
+ * (defer), or proceed as an ordinary wake because no run currently holds the
+ * lock. The caller reads whether a deferred wake already exists only after
+ * this function returns `defer`, so that read never runs on the coalesce
+ * path.
+ */
+export function decideWakeAdmission(facts: WakeAdmissionFacts): WakeAdmissionDecision {
+  if (
+    facts.isSameExecutionAgent &&
+    !facts.shouldDeferFollowupWake &&
+    !facts.shouldQueueFollowupForRunningWake &&
+    facts.availableActiveExecutionRunPresent
+  ) {
+    return { kind: "coalesce" };
+  }
+
+  if (facts.availableActiveExecutionRunPresent) {
+    return { kind: "defer" };
+  }
+
+  return { kind: "proceed" };
+}
+
 export type PreDrainFacts = {
   /** True when the transaction found the issue row the lock is for. */
   issueRowPresent: boolean;