fix(heartbeat): deliver a saved answer on a reviewed task with open blockers (#22525)

## 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 <noreply@anthropic.com>
This commit is contained in:
authored and GitHub committed 2026-11-21 19:47:47 -08:00
1 parent 7a4a5bba8a
commit 4ec1447a67
2 files changed
+30 -9

No files matched your search

@@ -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<string, unknown> | 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);
},
);
+7 -1
View File
@@ -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 });