mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## 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` ata722935dbcand 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`a722935dbcplus 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>