feat: add agent task report endpoint

[joryirving]

Closes #396

[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: Agent Task Report Endpoint (PR PR 405)

Summary

This PR adds a new POST /api/agents/[agentName]/tasks/report endpoint for agent harnesses to report task outcomes. The endpoint validates incoming task reports and returns them as JSON.

Change-by-Change Findings

New endpoint: src/app/api/agents/[agentName]/tasks/report/route.ts

• Adds a POST handler that validates task reports with taskType and outcome (required) plus optional fields (repoFullName, issueNumber, pullRequestNumber, pullRequestUrl, summary, error)
• Implements comprehensive input validation (type checking, enum validation for taskType/outcome, integer validation for numbers)
• Returns validated report as JSON on success

New test file: src/app/api/agents/[agentName]/tasks/report/route.test.ts

• 351 lines of test coverage including happy paths, validation failures, and edge cases
• Tests verify validation behavior (400 for bad inputs) and response structure

---

Required Checks

✅ verify route access controls are in place

FAILED: The endpoint does NOT implement any authentication. The route handler:

1. Has no bearer token validation for DISPATCH_AGENT_TOKEN
2. Does not call any auth middleware or verification helper
3. Accepts any valid POST request without credentials

Per the repository's AGENTS.md:

• "DISPATCH_AGENT_TOKEN for agent API bearer auth"
• "Bearer token authentication for API calls from agents, MCP clients, and scheduled workers. This is required for all mutating API endpoints."

The related /api/agent-runs endpoint requires DISPATCH_AGENT_TOKEN bearer auth per the contract in AGENTS.md. This report endpoint, which also receives data from agent harnesses, should follow the same pattern.

✅ check for unintended public endpoints

CONFIRMED: This endpoint is publicly accessible. Per README.md:

• "Setting DISPATCH_AUTH_MODE=disabled disables all authentication enforcement... This means every endpoint is publicly accessible without any credentials."

Without authentication in the route handler, this endpoint will be publicly accessible even when DISPATCH_AUTH_MODE is not explicitly disabled, as the route handler itself performs no auth check.

---

Standards Compliance

Standard	Status	Notes
Agent API bearer auth	❌ Violated	No DISPATCH_AGENT_TOKEN validation in handler
Input validation	✅ Compliant	Comprehensive type/enum validation implemented
Error handling	✅ Compliant	Returns appropriate 400 for invalid inputs

---

Linked Issue Fit (Issue PR 396)

The linked issue acceptance criteria states:

• "report updates Dispatch state consistently" → Not yet implemented (endpoint just echoes back data)
• "worker reports do not trigger another task" → ✅ Verified (no side effects)
• "groomer reports can update issue status/lane metadata" → Not yet implemented
• "errors are visible in Dispatch for later follow-up" → Partial (error field validated but not persisted)

The acceptance criteria imply state updates, which this basic implementation doesn't provide. The PR description says "Closes PR 396" but the acceptance criteria are not fully addressed.

---

Unknowns / Needs Verification

1. Was bearer auth intentionally omitted? The git_grep searches for DISPATCH_AGENT_TOKEN, Authorization, Bearer, and verifyAgentToken returned no matches in the codebase—suggesting no auth pattern exists in this route path. However, other agent API routes documented in AGENTS.md require bearer auth.

2. Should the report endpoint persist state? The issue mentions "report updates Dispatch state consistently" but the implementation only validates and echoes. This may be intentional (stateless ingestion), but contradicts the acceptance criteria wording.

---

Recommendation

Request changes: The endpoint requires bearer token authentication (DISPATCH_AGENT_TOKEN) to match repository conventions for agent API endpoints. Without authentication, this is an unintended public endpoint that violates the repository's security model.

[its-saffron]

🛑 Blocker (security): Missing bearer token authentication: POST /api/agents/[agentName]/tasks/report accepts requests without DISPATCH_AGENT_TOKEN validation, making it publicly accessible contrary to repository conventions for agent API endpoints.

Automated finding from AI PR review.