forked from farhoodlabs/paperclip
Dotta
1266954a4e
## Thinking Path > - Paperclip orchestrates AI agents through issue-driven heartbeats, checkouts, and wake scheduling. > - This change sits in the server heartbeat and issue services that decide which queued runs are allowed to start. > - Before this branch, queued heartbeats could be selected even when their issue still had unresolved blocker relationships. > - That let blocked descendant work compete with actually-ready work and risked auto-checking out issues that were not dependency-ready. > - This pull request teaches the scheduler and checkout path to consult issue dependency readiness before claiming queued runs. > - It also exposes dependency readiness in the agent inbox so agents can see which assigned issues are still blocked. > - The result is that heartbeat execution follows the DAG of blocked dependencies instead of waking work out of order. ## What Changed - Added `IssueDependencyReadiness` helpers to `issueService`, including unresolved blocker lookup for single issues and bulk issue lists. - Prevented issue checkout and `in_progress` transitions when unresolved blockers still exist. - Made heartbeat queued-run claiming and prioritization dependency-aware so ready work starts before blocked descendants. - Included dependency readiness fields in `/api/agents/me/inbox-lite` for agent heartbeat selection. - Added regression coverage for dependency-aware heartbeat promotion and issue-service participation filtering. ## Verification - `pnpm run preflight:workspace-links` - `pnpm exec vitest run server/src/__tests__/heartbeat-dependency-scheduling.test.ts server/src/__tests__/issues-service.test.ts` - On this host, the Vitest command passed, but the embedded-Postgres portions of those files were skipped because `@embedded-postgres/darwin-x64` is not installed. ## Risks - Scheduler ordering now prefers dependency-ready runs, so any hidden assumptions about strict FIFO ordering could surface in edge cases. - The new guardrails reject checkout or `in_progress` transitions for blocked issues; callers depending on the old permissive behavior would now get `422` errors. - Local verification did not execute the embedded-Postgres integration paths on this macOS host because the platform binary package was missing. > I checked `ROADMAP.md`; this is a targeted execution/scheduling fix and does not duplicate planned roadmap feature work. ## Model Used - OpenAI Codex via the Paperclip `codex_local` adapter in this workspace. Exact backend model ID is not surfaced in the runtime here; tool-enabled coding agent with terminal execution and repository editing capabilities. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge