Files
PaperClipAI/server/src/__tests__
DottaandClaude Opus 5.5 b2b2c1e60b fix(issues): release a done blocker whose ended run already finalized (#21948)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A parent task can wait for its subtasks through "blocks" relations.
When the last blocker is done, the parent wakes with
`issue_children_completed` or `issue_blockers_resolved`
> - A done blocker with workspace work also passes a workspace-finalize
barrier. The barrier holds dependents until the blocker's run saves its
workspace
> - The barrier reads the blocker's latest workspace operation. A save
that starts inside the run's finalize and ends after it, or any
operation that the same run records after its finalize, makes the
barrier look unsaved
> - That run has ended, so it records no further finalize. Nothing
clears the barrier, every wake for the parent becomes a skipped
`issue_dependencies_blocked` wait, and the periodic backstop also sees
the blocker as unresolved
> - This pull request treats a settled operation as saved when its run
has ended and that run recorded a successful finalize for the blocker
issue
> - The benefit is that the parent gets its children-completed run, and
parents that are stuck now are released by the existing dependency
backstop with no manual step

## Linked Issues or Issue Description

Refs #19219, #17206, #18665. #19219 releases the barrier when a terminal
run recorded no finalize at all. This change is narrower: the run must
have recorded a successful finalize for the blocker issue. A failed
finalize with no later success still holds the gate (#17206 owns that
recovery).

**What happened?**

A parent task created two subtasks. Subtask 1 finished and its run saved
the workspace. Then the parent run bound both subtasks as blockers and
moved the parent to `blocked` (`durable_dependency_blocker_bound`).
Subtask 2 finished 30 seconds later. The `issue_children_completed` wake
for the parent was skipped and recorded as `issue_dependencies_blocked`
with `unresolvedBlockerIssueIds` set to subtask 1, which had been done
for 2.5 minutes. The parent showed `pendingFinalizeBlockerIssueIds:
[subtask 1]` and `canRetry: false`. No later wake came. The parent
stayed blocked until a person changed it by hand.

**Expected behavior**

When every blocker is done and each blocker's run has finished with a
successful workspace finalize, the parent gets one children-completed
run.

**Steps to reproduce**

1. Create a parent with two subtasks on separate execution workspaces.
2. Finish subtask 1. Its run records a successful `workspace_finalize`,
and a `remote_workspace_snapshot` of the same run ends after the
finalize ends. The incident run had a failed copy-back that was retried
during a restart overlap.
3. Bind both subtasks as blockers of the parent, then block the parent.
4. Finish subtask 2 and dispatch the native `issue_children_completed`
intent.
5. Before this change, the wake is skipped as
`issue_dependencies_blocked` and no run starts.

**Paperclip version or commit**

master `6205b24d54`.

## What Changed

- `pendingFinalizeBlockerCondition` (`server/src/services/issues.ts`)
has one more release rule. The latest blocker operation is settled
(`succeeded`, `failed` or `skipped`). Its heartbeat run is terminal.
That run recorded a successful `workspace_finalize` for the blocker
issue on the same workspace (or with no workspace id). Readiness, the
queue dependency gate, blocker attention and the periodic backstop all
read this condition.
- Live runs keep the old behavior. A save that ends after its finalize,
or an operation that starts after it, still holds dependents while the
run is running.
- Foreign-run operations, unfinished operations and failed finalizes
with no success still hold dependents.

## Verification

- New regression test `heartbeat-dependency-scheduling.test.ts` › "runs
the parent's children-completed wake when a child it bound after
completion saved after its finalize". It replays the incident order:
child 1 done and finalized, its snapshot ends after the finalize, the
parent binds both children and blocks, child 2 finishes, the native
children-completed intent dispatches. Red before the fix (no run starts;
the wake becomes `issue_dependencies_blocked`). Green after the fix (a
run starts with the intent's context, and no dependency wait is
recorded).
- `issues-service.test.ts` nested-snapshot matrix: `late-finish` and
`later-operation` now run with a live owner run (still pending) and with
a terminal owner run (released). `covered`, `foreign-run`, `unfinished`
and `failed-finalize` stay as before.
- `cd server && npx vitest run
src/__tests__/heartbeat-dependency-scheduling.test.ts
src/__tests__/issues-service.test.ts` passes (207 tests).
- `pnpm verify` and `tsc --noEmit` for `server` pass locally.

## Risks

- Low risk. The change only releases a barrier for a run that has
already ended after a successful finalize for the issue. That run cannot
write another finalize, so the old rule held dependents forever with no
path to release them.
- An operation that a terminal run recorded after its finalize is no
longer a reason to hold dependents. Such work can never be saved by that
run. Holding the parent forever does not protect it.
- No schema, API or UI contract change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, test execution) and extended
reasoning.

## 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
- [x] All Paperclip CI gates are green
- [x] 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>
2026-11-16 19:59:48 -06:00
..
…

Server Tests

Server tests that need a real PostgreSQL process must use ./helpers/embedded-postgres.ts instead of constructing embedded-postgres directly.

The shared helper creates a throwaway data directory and a reserved-safe loopback port for each test database. This protects the live Paperclip control-plane Postgres from server vitest runs; see PAP-2033 for the incident that introduced this guard.