Files
PaperClipAI/server
4ec1447a67 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>
2026-11-21 19:47:47 -08:00
..