From 4ec1447a671774b3c921ffd4ae4bbe383fbbff9b Mon Sep 17 00:00:00 2001 From: paperclipbugbot Date: Sat, 21 Nov 2026 19:47:47 -0800 Subject: [PATCH] fix(heartbeat): deliver a saved answer on a reviewed task with open blockers (#22525) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - An agent can ask a person a question on a task. The saved answer wakes the agent. > - Dependencies stop task work until the blocker tasks finish. #20363 lets a verified human answer reach the assignee in a bounded turn while blockers stay open. That turn does not check out the task. > - Run preparation used the bounded path only when the task status was `blocked`. A task can wait in review (`in_review`) and still have open blockers. > - For such a task, dispatch admitted the answer turn. Then preparation tried the normal resolved-interaction checkout. The checkout refused the run with "Issue is blocked by unresolved blockers" (HTTP 422). > - The run failed `setup_failed`. The answer did not reach the agent, and Sentry received the refusal as an unexpected run failure. > - This pull request keeps a verified answer in the bounded turn whenever the task still has open blockers. > - The benefit is that the person's answer reaches the agent, and the task and its blockers do not change. ## Linked Issues or Issue Description Refs #20363 (deliver saved answers to dependency-blocked tasks). This change covers the same answer on a task that is not in `blocked` status. **What happened?** A parent task waited in review. Some of its child blocker tasks were still blocked. The assignee had asked a question on the parent. A person answered it. Dispatch admitted the answer turn with `dependencyBlockedInteraction: true`. Run preparation then called the resolved-interaction checkout, because the task status was `in_review`, not `blocked`. The checkout dependency check threw "Issue is blocked by unresolved blockers". The run failed `setup_failed` about one second after it started. The adapter did not run. Sentry received the error. **Expected behavior** The saved answer reaches the assignee as a bounded answer turn. The task stays `in_review`. Its blockers and dependency edges do not change. When the last blocker has already finished, the task checks out normally, as before. **Steps to reproduce** 1. Assign a task to an agent and set its status to `in_review`. 2. Add a `backlog` task that blocks it. 3. Save an agent question on the task and answer it as a person. 4. Dispatch the resolved-interaction wake. 5. Observe that the run fails `setup_failed` with "Issue is blocked by unresolved blockers". **Paperclip version or commit** Seen on a hosted staging server. The new regression case fails on `master` at a722935dbc and passes with this change. ## What Changed - `server/src/services/heartbeat.ts`: run preparation treats a verified dependency-blocked answer as a bounded turn without checkout when the task is `blocked` (unchanged) or when its dependencies are still not ready. Before this change, only the `blocked` status qualified. - The answer still needs the same proof as before: the stored interaction is human-resolved, belongs to this task and agent, and matches the wake's status and kind. - `server/src/__tests__/heartbeat-dependency-scheduling.test.ts`: the existing saved-response matrix gets two cases: - `in_review_answered`: a reviewed task with an open blocker receives the answer once and stays `in_review`. - `in_review_blocker_finishes`: when the blocker finishes before preparation, the reviewed task checks out normally and becomes `in_progress`. The answer is delivered once. ## Verification - Red before the fix, green after: `delivers only a saved human response while dependencies remain blocked: in_review_answered`. Before the fix the run ended `{ status: "failed", errorCode: "setup_failed", error: "Issue is blocked by unresolved blockers" }`, which is the staging failure. After the fix it succeeds. - Safety case `in_review_blocker_finishes` passes before and after the fix. A reviewed task with no open blockers keeps its normal checkout. - The existing cases still pass. They cover a pending, missing, wrong-task, or agent-resolved response that stays blocked, a response that changes before dispatch, workspace waits, and a blocked task whose blocker finishes. - Commands (local, Node 25, embedded Postgres, branch at `master` a722935dbc plus this change): - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/heartbeat-dependency-scheduling.test.ts src/__tests__/heartbeat-agent-directory-busy.test.ts src/modules/run-dispatch/domain/wake-context.test.ts src/modules/run-dispatch/domain/policy.test.ts src/__tests__/deferred-execution-receipt-work.test.ts src/services/explicit-native-continuation.test.ts` (613 passed) - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/heartbeat-clean-continuation-dispatch.test.ts src/__tests__/heartbeat-isolated-continuation-hold.test.ts src/__tests__/issue-thread-interactions-service.test.ts src/__tests__/agent-interaction-acceptance.test.ts` (148 passed) - `pnpm --filter @paperclipai/server typecheck` (passed) ## Risks - Low risk. The change applies only to a wake that dispatch already admitted as a verified dependency-blocked answer, and only while the task still has open blockers. Before this change, that run always failed at checkout. - The bounded turn does not check out the task, change its status, or resolve a blocker. Pause, ownership, approval, budget, and execution gates are unchanged. - No migration. No change to the API or to stored data. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use (shell, file edit, and test 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 - [ ] I have updated relevant documentation to reflect my changes (no doc change: the code comment and tests record the contract) - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 --- .../heartbeat-dependency-scheduling.test.ts | 31 ++++++++++++++----- server/src/services/heartbeat.ts | 8 ++++- 2 files changed, 30 insertions(+), 9 deletions(-) diff --git a/server/src/__tests__/heartbeat-dependency-scheduling.test.ts b/server/src/__tests__/heartbeat-dependency-scheduling.test.ts index e7d912cf9b9..c42166f6196 100644 --- a/server/src/__tests__/heartbeat-dependency-scheduling.test.ts +++ b/server/src/__tests__/heartbeat-dependency-scheduling.test.ts @@ -654,9 +654,16 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () = }); it.each(["answered", "accepted", "rejected", "pending", "missing", "wrong_issue", "agent_resolved", "changed_before_dispatch", - "workspace_wait", "workspace_wait_changed", "blocker_finishes"] as const)( + "workspace_wait", "workspace_wait_changed", "blocker_finishes", "in_review_answered", "in_review_blocker_finishes"] as const)( "delivers only a saved human response while dependencies remain blocked: %s", async response => { const companyId = randomUUID(), agentId = randomUUID(), blockerId = randomUUID(), issueId = randomUUID(); + // A task waiting in review can still have open blockers. The answer must + // reach its assignee without a checkout that the blockers would refuse. + // Once its last blocker finishes, the reviewed task resumes through its + // normal checkout instead of staying in a bounded turn. + const reviewed = response === "in_review_answered" || response === "in_review_blocker_finishes"; + const blockerFinishes = response === "blocker_finishes" || response === "in_review_blocker_finishes"; + const parentStatus = reviewed ? "in_review" : "blocked"; await db.insert(companies).values({ id: companyId, name: "Response fixture", issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`, requireBoardApprovalForNewAgents: false, defaultResponsibleUserId: "responsible-user" }); @@ -666,7 +673,7 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () = adapterType: "codex_local", adapterConfig: {}, runtimeConfig: { heartbeat: { wakeOnDemand: true, maxConcurrentRuns: 1 } }, permissions: {} }); await db.insert(issues).values([ { id: blockerId, companyId, title: "Parked trial", status: "backlog", responsibleUserId: "responsible-user" }, - { id: issueId, companyId, title: "Finish trial prerequisites", status: "blocked", assigneeAgentId: agentId, + { id: issueId, companyId, title: "Finish trial prerequisites", status: parentStatus, assigneeAgentId: agentId, responsibleUserId: "responsible-user" }, ]); await db.insert(issueRelations).values({ companyId, issueId: blockerId, relatedIssueId: issueId, type: "blocks" }); @@ -692,9 +699,9 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () = .mockRejectedValueOnce(new WorkspaceBusyDeferral({ holder: { runId: randomUUID(), agentId, issueId: blockerId, issueIdentifier: null }, executionWorkspaceId: randomUUID(), wasIssueAssignee: true, deferralAttempt: 0 })) : null; - const service = response === "changed_before_dispatch" || resourceWait || response === "blocker_finishes" ? heartbeatService(db, { + const service = response === "changed_before_dispatch" || resourceWait || blockerFinishes ? heartbeatService(db, { beforeChatControlRecoveryCheck: async ({ stage }) => { - if (response === "blocker_finishes" && stage === "claim") + if (blockerFinishes && stage === "claim") await db.update(issues).set({ status: "done" }).where(eq(issues.id, blockerId)); }, beforeResolvedInteractionContinuationDispatchCheck: async ({ runId }) => { @@ -720,7 +727,8 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () = expect((await service.promoteDueScheduledRetries(new Date(Date.now() + 5 * 60_000))).runIds).toContain(retry.id); await service.resumeQueuedRuns(); } - const shouldDeliver = ["answered", "accepted", "rejected", "workspace_wait", "blocker_finishes"].includes(response); + const shouldDeliver = ["answered", "accepted", "rejected", "workspace_wait", "blocker_finishes", "in_review_answered", + "in_review_blocker_finishes"].includes(response); if (shouldDeliver) { expect(wake).not.toBeNull(); await service.drainActiveRunExecutions(); @@ -731,7 +739,13 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () = interactionId: interaction.id, interactionStatus: status, dependencyBlockedInteraction: true, unresolvedBlockerIssueIds: [blockerId], } }); - expect(mockAdapterExecute).toHaveBeenCalledTimes(1); + const answerRuns = (await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.agentId, agentId))) + .filter((row) => row.status === "succeeded" + && (row.contextSnapshot as Record | null)?.interactionId === interaction.id); + expect(answerRuns.map((row) => row.id)).toEqual([run.id]); + // The checked-out task's ordinary disposition repair may follow; the + // saved answer itself is delivered once. + if (response !== "in_review_blocker_finishes") expect(mockAdapterExecute).toHaveBeenCalledTimes(1); if (response === "answered") { // A resource wait keeps the same bounded interaction and must not // strand the answer again at scheduled promotion. @@ -761,8 +775,9 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () = } expect(await db.select().from(issueRelations).where(eq(issueRelations.relatedIssueId, issueId))).toHaveLength(1); expect((await db.select().from(issues).where(eq(issues.id, blockerId)))[0].status) - .toBe(response === "blocker_finishes" ? "done" : "backlog"); - expect((await db.select().from(issues).where(eq(issues.id, issueId)))[0].status).toBe("blocked"); + .toBe(blockerFinishes ? "done" : "backlog"); + expect((await db.select().from(issues).where(eq(issues.id, issueId)))[0].status) + .toBe(response === "in_review_blocker_finishes" ? "in_progress" : parentStatus); expect(await db.select().from(heartbeatRuns).where(sql`${heartbeatRuns.contextSnapshot}->>'issueId' = ${blockerId}`)).toHaveLength(0); }, ); diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts index be7c0cf9ea1..af4ed40565d 100644 --- a/server/src/services/heartbeat.ts +++ b/server/src/services/heartbeat.ts @@ -2374,7 +2374,13 @@ export function heartbeatService( .listDependencyReadiness(agent.companyId, [issueId]) .then((rows) => rows.get(issueId) ?? null)) : null; - const dependencyResponse = issueId && issueContext?.status === "blocked" + // A verified human answer on a task with open blockers is a bounded turn + // without checkout. A blocked task keeps that turn even if its last + // blocker finished during preparation. An active task (for example one + // waiting in review) checks out normally once its blockers are resolved; + // while they are open, checkout would refuse the answer with a 422. + const dependencyResponse = issueId && (issueContext?.status === "blocked" + || issueDependencyReadiness?.isDependencyReady === false) && context.dependencyBlockedInteraction === true && await isVerifiedDependencyInteractionResponse(db, { companyId: agent.companyId, issueId, agentId: agent.id, context });