perf(wake-queue): reuse the task row locked by admission (#22280)

## Thinking Path

> - Paperclip schedules agent work for a task.
> - Admission locks the task before it decides what to run.
> - The lock query returned only the identifier. The policy and recovery
check then read the same task again.
> - Return the fields those decisions need from the lock query.
> - Refresh the task after a callback that can change it. Keep recovery
and workspace authority current.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Admitting board assignments and saved task comments.

**Subsystem affected**

Server task admission.

**Current behavior**

Admission reads the task again while it holds the row lock. A comment
also queries the bound workspace when the locked task has none.

**Proposed behavior**

Use the company-scoped locked row. Check workspace preservation when the
task has a bound workspace.

**Additional context**

Builds on #22272 and #22279. Related work in #21954 changes workspace
binding.

## What Changed

- Return the admission projection from the row lock. Repeat the locking
read after durable authorization or an initial miss.
- Use the task projection only for the same company and task. Keep every
recovery-action, ownership and lease read.
- Cover changes inside durable authorization and a concurrent insert
after the initial lock missed.

## Verification

All 261 tests passed in the wake-queue Postgres adapter,
execution-blocker-read and heartbeat queue suites. On 64ca436676 a local
PostgreSQL benchmark retained every saved input. Warm median statements
for assignment, one comment and two separately posted comments fell from
38/40/82 on its parent to 36/37/76. Server declaration and
colocated-test typechecks and the module-boundary check passed.

## Risks

A stale task can authorize work after the task changes. The tests use a
callback that writes through the transaction, plus a competing
connection that attempts to acquire the issue lock.

## Model Used

OpenAI GPT-6.2 Sol (gpt-6.2-sol) implemented the change. OpenAI Codex
reviewed 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
This commit is contained in:
Nicky Leach authored and GitHub committed 2026-11-18 20:05:16 -08:00
1 parent 5506359bbb
commit 3dc6ccd8d8
6 files changed
+128 -46

No files matched your search

@@ -202,7 +202,8 @@ describeEmbeddedPostgres("wake-queue postgres adapter", () => {
const blocker = vi.spyOn(executionBlocker, "getExecutionBlocker");
const admit = createPostgresIssueWakeAdmission(db);
try {
await admit({ companyId, issueId }, async (tx, { fresh }) => {
await admit({ companyId, issueId }, async (tx, { fresh, lockedIssue }) => {
expect(lockedIssue).toMatchObject({ id: issueId, companyId, assigneeAgentId: agentId });
await expect(db.execute(sql`select id from issues where id = ${issueId} for update nowait`))
.rejects.toMatchObject({ cause: { code: "55P03" } });
const input = { issueId, agentId, handoffRunId, checkExecutionBlocker: true };
@@ -218,6 +219,16 @@ describeEmbeddedPostgres("wake-queue postgres adapter", () => {
await expect(fresh.readCommentCandidates({ ...input, receiptScope, checkExecutionBlocker: false }))
.resolves.toMatchObject({ handoffAgentId: formerAgentId, candidates: [{ id: wakeId }] });
expect(blocker).toHaveBeenCalledTimes(1);
const select = vi.spyOn(tx, "select");
try {
expect(await executionBlocker.getExecutionBlocker(tx as unknown as Db, companyId, issueId, {
lockedIssue: lockedIssue!,
})).toMatchObject({ cause: "legacy_execution_requires_reconciliation" });
expect(select).not.toHaveBeenCalledWith(expect.objectContaining({ conversationAgentId: issues.conversationAgentId }));
} finally {
select.mockRestore();
}
return { kind: "skipped" };
});
} finally {
@@ -225,6 +236,21 @@ describeEmbeddedPostgres("wake-queue postgres adapter", () => {
}
});
it("locks an issue added after the initial admission lock missed", async () => {
const companyId = await seedCompany();
const issueId = randomUUID();
const admit = createPostgresIssueWakeAdmission(db);
await admit({ companyId, issueId }, async (_tx, { lockedIssue, lockIssue }) => {
expect(lockedIssue).toBeNull();
await seedIssue({ companyId, issueId });
expect(await lockIssue()).toMatchObject({ id: issueId, companyId });
await expect(db.execute(sql`select id from issues where id = ${issueId} for update nowait`))
.rejects.toMatchObject({ cause: { code: "55P03" } });
return { kind: "skipped" };
});
});
function recordReleaseRunReads() {
const rows: unknown[][] = [];
function recordSelects<T extends Pick<Db, "select">>(executor: T): T {
@@ -1278,10 +1278,39 @@ export function createWakeAdmissionWriter(rawTx: IssueAdmissionDbTransaction, ad
};
}
const issueAdmissionFields = {
id: issues.id,
companyId: issues.companyId,
identifier: issues.identifier,
conversationBoundaryCommentId: issues.conversationBoundaryCommentId,
conversationAgentId: issues.conversationAgentId,
conversationUserId: issues.conversationUserId,
conversationState: issues.conversationState,
status: issues.status,
statusVersion: issues.statusVersion,
projectId: issues.projectId,
projectWorkspaceId: issues.projectWorkspaceId,
executionWorkspaceId: issues.executionWorkspaceId,
executionWorkspacePreference: issues.executionWorkspacePreference,
executionWorkspaceSettings: issues.executionWorkspaceSettings,
assigneeAgentId: issues.assigneeAgentId,
assigneeUserId: issues.assigneeUserId,
monitorNextCheckAt: issues.monitorNextCheckAt,
monitorWakeRequestedAt: issues.monitorWakeRequestedAt,
checkoutRunId: issues.checkoutRunId,
executionRunId: issues.executionRunId,
executionAgentNameKey: issues.executionAgentNameKey,
createdAt: issues.createdAt,
};
export type IssueAdmissionRow = Pick<IssueRow, keyof typeof issueAdmissionFields>;
export function createPostgresIssueWakeAdmission(db: Db) {
return async function withIssueAdmission(
{ companyId, issueId, durableChatRequest }: IssueAdmissionTarget,
evaluate: (tx: IssueAdmissionDbTransaction, stores: {
lockedIssue: IssueAdmissionRow | null;
lockIssue: () => Promise<IssueAdmissionRow | null>;
reader: WakeAdmissionReader;
writer: WakeAdmissionWriter;
fresh: FreshIssueRunStore<HeartbeatRunRow>;
@@ -1290,8 +1319,15 @@ export function createPostgresIssueWakeAdmission(db: Db) {
try {
return await db.transaction(withDurableChatAdmission(durableChatRequest, async (tx) => {
// Mentions may target another agent, but every admission must share the issue lock.
await tx.execute(sql`select id from issues where id = ${issueId} and company_id = ${companyId} for update`);
const lockIssue = async () => {
const [issue] = await tx.select(issueAdmissionFields).from(issues)
.where(and(eq(issues.id, issueId), eq(issues.companyId, companyId))).for("update");
return issue ?? null;
};
const lockedIssue = await lockIssue();
return evaluate(tx, {
lockedIssue,
lockIssue,
reader: createWakeAdmissionReader(tx, companyId),
writer: createWakeAdmissionWriter(tx, companyId),
fresh: createFreshIssueRunStore(tx, companyId),
+6 -1
View File
@@ -3,6 +3,7 @@ import {
createPostgresIssueWakeAdmission,
createPostgresWakeQueueAdapter,
type IssueAdmissionDbTransaction,
type IssueAdmissionRow,
type IssueAdmissionTarget,
} from "./adapters/postgres.js";
import { createQueuedCommentIssueLockWriter } from "./adapters/queued-comment-postgres.js";
@@ -82,6 +83,8 @@ export type WakeQueueDeps = {
type HeartbeatRun = typeof heartbeatRuns.$inferSelect;
type LockedIssueAdmission = {
lockedIssue: IssueAdmissionRow | null;
lockIssue: () => Promise<IssueAdmissionRow | null>;
admitWakeBehindIssueExecution: ReturnType<typeof createAdmitWakeBehindIssueExecution>;
admitFreshIssueRun: ReturnType<typeof createFreshIssueRunAdmission<HeartbeatRun>>;
};
@@ -103,10 +106,12 @@ export function createWakeQueue(db: Db, deps: WakeQueueDeps) {
evaluateHeartbeatPolicy: (tx: IssueAdmissionDbTransaction, admission: LockedIssueAdmission) => Promise<IssueWakeAdmissionOutcome<HeartbeatRun>>,
effects: IssueWakeAdmissionEffects<HeartbeatRun>,
) {
return admitIssueWake(() => withIssueAdmission({ companyId, issueId, durableChatRequest }, (tx, { reader, writer, fresh }) => {
return admitIssueWake(() => withIssueAdmission({ companyId, issueId, durableChatRequest }, (tx, { lockedIssue, lockIssue, reader, writer, fresh }) => {
const admitBusy = createAdmitWakeBehindIssueExecution({ reader, writer, helpers: deps.wakeAdmissionHelpers });
const admitFresh = createFreshIssueRunAdmission(fresh);
return evaluateHeartbeatPolicy(tx, {
lockedIssue,
lockIssue,
async admitWakeBehindIssueExecution(input) {
if (input.companyId !== companyId || input.issueId !== issueId || input.contextSnapshot.issueId !== issueId) {
throw new Error("wake-queue: admission does not match the locked company and issue");
+18 -9
View File
@@ -321,17 +321,26 @@ export function restoreHoldPredicate() {
);
}
const blockerIssueFields = {
id: issues.id, companyId: issues.companyId,
conversationAgentId: issues.conversationAgentId, conversationBoundaryCommentId: issues.conversationBoundaryCommentId,
status: issues.status, assigneeAgentId: issues.assigneeAgentId, statusVersion: issues.statusVersion,
executionRunId: issues.executionRunId, checkoutRunId: issues.checkoutRunId,
};
export async function getExecutionBlocker(db: Db, companyId: string, issueId: string, options?: {
conversationResetCommentId?: string | null;
/** The current issue row held under this transaction's issue lock. */
lockedIssue?: Pick<typeof issues.$inferSelect, keyof typeof blockerIssueFields>;
/** The native run being dispatched; its own scheduled resume does not block it. */
resumingNativeRunId?: string | null;
}): Promise<ExecutionBlocker | null> {
const [conversation] = await db.select({ agentId: issues.conversationAgentId,
boundaryId: issues.conversationBoundaryCommentId, status: issues.status,
assigneeAgentId: issues.assigneeAgentId, statusVersion: issues.statusVersion,
executionRunId: issues.executionRunId, checkoutRunId: issues.checkoutRunId }).from(issues).where(and(
eq(issues.companyId, companyId), eq(issues.id, issueId),
)).limit(1);
const lockedIssue = options?.lockedIssue;
const conversation = lockedIssue?.id === issueId && lockedIssue.companyId === companyId
? lockedIssue
: (await db.select(blockerIssueFields).from(issues).where(and(
eq(issues.companyId, companyId), eq(issues.id, issueId),
)).limit(1))[0];
// Resetting model context cannot repair or recover a workspace. This hold
// survives conversation boundaries until the existing repair/reconciliation path clears it.
const [restoreHold] = await db.select().from(issueRecoveryActions).where(and(
@@ -343,17 +352,17 @@ export async function getExecutionBlocker(db: Db, companyId: string, issueId: st
)).orderBy(desc(issueRecoveryActions.updatedAt)).limit(1);
// A persisted user /new is an ordered context command, not a retry of uncertain work.
// The normal issue execution lock still serializes it behind any active turn.
if (!restoreHold && conversation?.agentId && options?.conversationResetCommentId) {
if (!restoreHold && conversation?.conversationAgentId && options?.conversationResetCommentId) {
const [command] = await db.select().from(issueComments).where(and(
eq(issueComments.companyId, companyId), eq(issueComments.issueId, issueId),
eq(issueComments.id, options.conversationResetCommentId),
)).limit(1);
if (command?.authorUserId && !command.deletedAt && command.body.trim() === "/new") return null;
}
const [boundary] = conversation?.agentId && conversation.boundaryId
const [boundary] = conversation?.conversationAgentId && conversation.conversationBoundaryCommentId
? await db.select({ createdAt: issueComments.createdAt }).from(issueComments).where(and(
eq(issueComments.companyId, companyId), eq(issueComments.issueId, issueId),
eq(issueComments.id, conversation.boundaryId),
eq(issueComments.id, conversation.conversationBoundaryCommentId),
)).limit(1) : [];
const ownership = await getConversationOwnershipBlocker(db, companyId, issueId);
@@ -288,6 +288,7 @@ describe.skipIf(!support.supported)("heartbeat queue database wiring", () => {
const admit = deps.wakeQueue.admitIssueWake.getMockImplementation()!;
deps.wakeQueue.admitIssueWake.mockImplementation((target, evaluate, effects) => admit(target,
(tx, admission) => evaluate(tx, otherIssue ? {
...admission,
admitFreshIssueRun: (input) => admission.admitFreshIssueRun({ ...input,
issue: { ...input.issue, id: otherIssue.id }, contextSnapshot: { ...input.contextSnapshot, issueId: otherIssue.id } }),
admitWakeBehindIssueExecution: (input) => admission.admitWakeBehindIssueExecution({ ...input,
@@ -309,6 +310,34 @@ describe.skipIf(!support.supported)("heartbeat queue database wiring", () => {
expect(await db.select().from(heartbeatRuns)).toHaveLength(kind === "fresh" ? 0 : 1);
});
it("uses issue changes written by durable chat authorization before admission", async () => {
const { user, company, agent, issue, queue } = await waitingConversationFixture();
await db.update(issues).set({ conversationAgentId: null, conversationUserId: null, conversationState: null, status: "todo" })
.where(eq(issues.id, issue.id));
const [comment] = await db.insert(issueComments).values({ companyId: company.id, issueId: issue.id,
authorType: "user", authorUserId: user.id, body: "Please continue" }).returning();
const requestId = randomUUID();
const request = createDurableChatWakeupRequest({
id: requestId, companyId: company.id, issueId: issue.id, agentId: agent.id, commentId: comment.id,
requestedByActorType: "user", requestedByActorId: user.id, requestedAt: new Date(),
authorize: async (tx) => {
await tx.update(issues).set({ status: "blocked" }).where(eq(issues.id, issue.id));
},
});
await expect(queue.enqueueWakeup(agent.id, {
source: "assignment", triggerDetail: "system", reason: "External chat message received",
requestedByActorType: "user", requestedByActorId: user.id, durableChatRequest: request,
payload: { issueId: issue.id, commentId: comment.id, mutation: "chat_message_received" },
issueStateGuard: { assigneeAgentId: agent.id, statuses: ["todo"] },
})).resolves.toBeNull();
const [receipt] = await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.id, requestId));
expect(receipt).toMatchObject({ status: "skipped", reason: "issue_state_guard_mismatch",
payload: { heartbeatSkip: { actualStatus: "blocked" } } });
expect(await db.select().from(heartbeatRuns)).toEqual([]);
});
it("admits the owner's context compaction maintenance request while its conversation waits", async () => {
const f = await waitingCompactionFixture();
const accepted = await f.service.request({ companyId: f.company.id, issue: f.issue, userId: f.user.id });
+11 -34
View File
@@ -3528,7 +3528,7 @@ export function createHeartbeatQueue(db: Db, dependencies: HeartbeatQueueDepende
return wakeQueue.admitIssueWake(
{ companyId: agent.companyId, issueId, durableChatRequest: durableRequest },
async (tx, { admitWakeBehindIssueExecution, admitFreshIssueRun }) => {
async (tx, { lockedIssue, lockIssue, admitWakeBehindIssueExecution, admitFreshIssueRun }) => {
if (executionWaitRequestId) {
const [pending] = await tx.select().from(agentWakeupRequests).where(and(
eq(agentWakeupRequests.id, executionWaitRequestId), eq(agentWakeupRequests.companyId, agent.companyId),
@@ -3781,37 +3781,9 @@ export function createHeartbeatQueue(db: Db, dependencies: HeartbeatQueueDepende
}
}
const issue = await tx
.select({
id: issues.id,
companyId: issues.companyId,
identifier: issues.identifier,
conversationAgentId: issues.conversationAgentId,
conversationUserId: issues.conversationUserId,
conversationState: issues.conversationState,
status: issues.status,
statusVersion: issues.statusVersion,
projectId: issues.projectId,
projectWorkspaceId: issues.projectWorkspaceId,
executionWorkspaceId: issues.executionWorkspaceId,
executionWorkspacePreference: issues.executionWorkspacePreference,
executionWorkspaceSettings: issues.executionWorkspaceSettings,
assigneeAgentId: issues.assigneeAgentId,
assigneeUserId: issues.assigneeUserId,
monitorNextCheckAt: issues.monitorNextCheckAt,
monitorWakeRequestedAt: issues.monitorWakeRequestedAt,
executionRunId: issues.executionRunId,
executionAgentNameKey: issues.executionAgentNameKey,
createdAt: issues.createdAt,
})
.from(issues)
.where(
and(
eq(issues.id, issueId),
eq(issues.companyId, agent.companyId),
),
)
.then((rows) => rows[0] ?? null);
// Durable chat authorization can write through this transaction. A missing
// row has no lock, so the later read can also see a newly inserted issue.
const issue = durableRequest || !lockedIssue ? await lockIssue() : lockedIssue;
if (!issue) {
if (caseRequest) throw conflict("Case handoff task no longer exists");
@@ -4110,11 +4082,16 @@ export function createHeartbeatQueue(db: Db, dependencies: HeartbeatQueueDepende
)).limit(1)
: [];
const verifiedConversationReset = Boolean(resetComment && isConversationReset(resetComment.body));
if (wakeCommentId && opts.requestedByActorType === "user")
const preserveWorkspace = wakeCommentId && opts.requestedByActorType === "user"
&& issue.executionWorkspaceId !== null;
if (preserveWorkspace)
await preserveTaskRemoteWorkspaceWriter(tx as unknown as Db, issue.companyId, issue.id);
const executionBlocker = await getExecutionBlocker(
tx as unknown as Db, issue.companyId, issue.id,
{ conversationResetCommentId: verifiedConversationReset ? wakeCommentId : null },
{
conversationResetCommentId: verifiedConversationReset ? wakeCommentId : null,
lockedIssue: preserveWorkspace ? undefined : issue,
},
);
// Prove eligibility without retiring the hold. Later gates can still
// decline this wake; hold retirement and successor creation stay atomic.