feat: make PR follow-up a first-class next-task source

[joryirving]

Closes #397.

Makes linked PR follow-up work first-class in Dispatch's next-task endpoint.

Behavior

Priority order (highest to lowest):

1. Queued PR-fix items - returns followup-pr task from the PR-fix queue
2. Linked PR follow-up - scans issue queue for first item with linkedPrHealth.needsFollowup === true and a PR number, returns followup-pr
3. Normal issue implementation - returns implement task for highest-ranked issue
4. Idle - returns idle when nothing is available

Linked PR Follow-up Task Mapping

• agentName: route param
• lane: queue item lane
• issue: full issue context (repo, number, title, url)
• pullRequest: linked PR context (repo, number, url if present)
• reasons: from linkedPrHealth.followupReasons, or fallback ["Linked PR needs follow-up"]

Changes

• src/app/api/agents/[agentName]/next-task/route.ts - scans queue for linked PR follow-up before returning implement task
• src/app/api/agents/[agentName]/next-task/route.test.ts - 9 new tests for linked PR follow-up behavior

Validation

• npm run lint
• npm run typecheck
• npm run test (1246 tests, all passing)
• npm run build

[its-saffron]

AI Automated Review

Full PR review.

Analysis engine: MiniMax-M2.7@https://litellm.jory.dev/v1 (anthropic) — routed smart (risk match: public_route_changes)

Review Summary

Recommendation: Approve — The PR implements linked PR follow-up as a first-class task type in the /api/agents/[agentName]/next-task endpoint. Changes are minimal, well-tested, and align with issue PR 397 acceptance criteria.

---

Change-by-Change Analysis

src/app/api/agents/[agentName]/next-task/route.ts (28 additions)

The route handler gains a scan for linked PR follow-up before returning the standard implement task. The logic:

1. Queries the agent queue (already filtered by lane, claimed status, etc.)
2. New: Uses queue.find() to locate the first issue where linkedPrHealth.needsFollowup is true with a PR number
3. Returns a followup-pr task with full issue and PR context
4. Falls back to existing implement task behavior if no follow-up needed

This maintains the documented priority order: PR-fix queue items → linked PR follow-up → normal implementation → idle.

Required Checks:

• ✅ Route access controls in place: Per AGENTS.md and README.md, agent API routes use DISPATCH_AGENT_TOKEN bearer auth via a shared authorizeRequest() helper in src/lib/auth.ts. The GET endpoint is read-only (returns task metadata), and agents authenticate via bearer token.
• ✅ No unintended public endpoints: No new routes added; only an existing endpoint's behavior is modified. No auth mode changes or route exposure.

src/app/api/agents/[agentName]/next-task/route.test.ts (307 additions)

Nine new tests cover:

• Followup task returned when issue has linked PR needing follow-up
• Followup beats normal implement work
• PR-fix queue still takes precedence (correct priority order)
• Task includes full issue context (repo, number, title, url)
• Task includes full PR context (repo, number, url)
• Followup reasons are included when present
• Fallback reason used when reasons array is empty
• Normal implement still works when no follow-up exists
• Idle still works when queue is empty

---

Standards Compliance

• Label conventions: Tests use priority/p0, status/ready, currentLane: "normal" — consistent with repository patterns.
• Code standards: Input validation occurs via Prisma queries; error handling uses the existing pattern; no secrets in output.
• API design: Returns appropriate HTTP 200 with JSON; task structure follows established AgentTask contract from src/lib/agent-task.ts.

---

Linked Issue Fit (PR 397)

Issue PR 397 acceptance criteria:

Criteria	Status
next-task prefers follow-up over new work	✅ First scan finds followup before falling to implement
follow-up task includes issue and PR context	✅ Tests verify body.issue.* and body.pullRequest.* fields
closed or completed PRs are skipped	✅ Filtered by linkedPrHealth.needsFollowup — PRs not needing follow-up are excluded
stale PRs are visible in Dispatch	✅ Depends on linkedPrNeedsFollowup flag; stale detection happens upstream in sync/ingestion
tests cover main follow-up signals	✅ 9 tests covering priority ordering, context inclusion, and fallback behavior

---

Tool Harness Findings

• src/app/api/agents/[agentName]/next-task/route.ts was read successfully; confirms imports and existing structure.
• src/app/api/agents/[agentName]/route.ts does not exist (no parent route file needed; Next.js handles this via file-system routing).
• Auth pattern matches repository conventions: bearer token via DISPATCH_AGENT_TOKEN.

---

Unknowns / Needs Verification

None relevant to this PR.

• No dependency upgrades requiring compatibility matrix verification.
• No Docker image changes.
• No secrets or configuration changes.

---

Evidence Provider Findings

No evidence providers configured for this PR.

---

CI Results

• Docker Build: ✅ Success
• Validate: ✅ Success (lint, typecheck, 1246 tests)

CI confirms the implementation passes all validation gates.