fix(issues): count a blocker covered when its wake already created a queued run (#21731)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A blocked parent task shows "covered" when its blockers have work
that will start by itself, and "needs attention" when a person must act
> - The blocker-attention read counts a blocker as active only through
its current execution run, or through a waiting wake that has not
created a run yet
> - A child whose wake already created a queued run that has not started
matches neither, so the parent shows "needs attention" and lands in the
blocked inbox
> - That work starts by itself when an agent slot frees, so the
attention is false and asks a person to act for no reason
> - This pull request also counts a blocker as active when its waiting
wake points at a queued or running run
> - The benefit is that the board and the blocked inbox stop showing
false attention while queued child work waits for a slot

## Linked Issues or Issue Description

**What happened?**
A parent task was blocked by two child tasks. Each child had a queued
run that a wake had created, and the runs waited for agent slots. The
parent showed `needs_attention` / `attention_required` and appeared in
the blocked inbox. The children started about 25 minutes later and the
parent then finished without a person.

**Expected behavior**
The parent shows `covered` with reason `active_child` while a child's
queued run waits to start.

**Steps to reproduce**
1. Create a blocked parent task with one child blocker that is assigned
to an agent.
2. Insert a queued wake for the child whose `runId` points at a queued
`heartbeat_runs` row, and leave the child's `executionRunId` empty.
3. List blocked tasks. The parent shows `needs_attention`.

**Paperclip version or commit**
`master` at 6400698a8e.

## What Changed

- `server/src/services/issues.ts`: the blocker-attention wake query
left-joins `heartbeat_runs` on the wake's `runId`. A queued or deferred
wake counts as an active path when its `runId` is empty or when its run
is `queued` or `running`.
- `server/src/__tests__/issue-blocker-attention.test.ts`: two tests. One
covers a child whose wake created a queued run that has not started. One
makes sure that a wake whose run already finished does not cover the
blocker.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/issue-blocker-attention.test.ts`: 27 passed.
- Red on master: "classifies a blocked parent as covered when its
child's wake already created a queued run that has not started" fails
with `needs_attention` / `attention_required`. Green with this change.
- Query plan (embedded Postgres, `enable_seqscan = off`): an index scan
on `agent_wakeup_requests_company_payload_issue_idx` (company and
payload issue id), then a nested-loop left join through
`heartbeat_runs_pkey`. The query count does not change, so there is no
N+1.
- `pnpm verify`.

## Risks

- Low risk. The change adds coverage only for a wake whose run is still
`queued` or `running`. A wake whose run finished, failed or was
cancelled stays uncovered, as before.
- The join is a primary-key lookup per wake row, inside the same chunked
query, so the board read cost does not change in a meaningful way.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude
Code with tool use and code 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
- [x] I have updated relevant documentation to reflect my changes
- [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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-15 01:23:38 -06:00
1 parent 9ebc276b42
commit 41a3520a2f
2 files changed
+74 -1

No files matched your search

@@ -194,6 +194,69 @@ describeEmbeddedPostgres("issue blocker attention", () => {
});
});
it("classifies a blocked parent as covered when its child's wake already created a queued run that has not started", async () => {
const { companyId, agentId } = await createCompany("PBQ");
const parentId = await insertIssue({ companyId, identifier: "PBQ-1", title: "Parent", status: "blocked" });
const childId = await insertIssue({
companyId,
identifier: "PBQ-2",
title: "Queued child",
status: "todo",
parentId,
assigneeAgentId: agentId,
});
await block({ companyId, blockerIssueId: childId, blockedIssueId: parentId });
const runId = await activeRun({ companyId, agentId, issueId: childId, status: "queued", current: false });
await db.insert(agentWakeupRequests).values({
companyId,
agentId,
source: "assignment",
status: "queued",
runId,
payload: { issueId: childId },
});
const parent = (await svc.list(companyId, { status: "blocked" })).find((issue) => issue.id === parentId);
expect(parent?.blockerAttention).toMatchObject({
state: "covered",
reason: "active_child",
coveredBlockerCount: 1,
attentionBlockerCount: 0,
});
});
it("does not cover a blocked parent through a wake whose created run already finished", async () => {
const { companyId, agentId } = await createCompany("PBF");
const parentId = await insertIssue({ companyId, identifier: "PBF-1", title: "Parent", status: "blocked" });
const childId = await insertIssue({
companyId,
identifier: "PBF-2",
title: "Finished child run",
status: "todo",
parentId,
assigneeAgentId: agentId,
});
await block({ companyId, blockerIssueId: childId, blockedIssueId: parentId });
const runId = await activeRun({ companyId, agentId, issueId: childId, status: "failed", current: false });
await db.insert(agentWakeupRequests).values({
companyId,
agentId,
source: "assignment",
status: "queued",
runId,
payload: { issueId: childId },
});
const parent = (await svc.list(companyId, { status: "blocked" })).find((issue) => issue.id === parentId);
expect(parent?.blockerAttention).toMatchObject({
state: "needs_attention",
coveredBlockerCount: 0,
attentionBlockerCount: 1,
});
});
it("classifies an assigned backlog blocker leaf without a waiting path as attention-needed", async () => {
const { companyId, agentId } = await createCompany("PBB");
const parentId = await insertIssue({ companyId, identifier: "PBB-1", title: "Parent", status: "blocked" });
+11 -1
View File
@@ -4179,6 +4179,13 @@ async function readIssueBlockerAttentionBatch(
>`${agentWakeupRequests.payload} ->> 'issueId'`,
})
.from(agentWakeupRequests)
.leftJoin(
heartbeatRuns,
and(
eq(heartbeatRuns.id, agentWakeupRequests.runId),
eq(heartbeatRuns.companyId, companyId),
),
)
.where(
and(
eq(agentWakeupRequests.companyId, companyId),
@@ -4186,7 +4193,10 @@ async function readIssueBlockerAttentionBatch(
agentWakeupRequests.status,
BLOCKER_ATTENTION_ACTIVE_WAKE_STATUSES,
),
sql`${agentWakeupRequests.runId} is null`,
or(
sql`${agentWakeupRequests.runId} is null`,
inArray(heartbeatRuns.status, BLOCKER_ATTENTION_ACTIVE_RUN_STATUSES),
),
inArray(
sql<string>`${agentWakeupRequests.payload} ->> 'issueId'`,
chunk,