Add agent-agnostic heartbeat orchestration API

[itsmiso-ai]

Problem

Agent heartbeat plumbing still depends on workspace-local scripts and pod-local state. That makes deterministic work harder to operate, harder to audit, and easy to lose on pod restart.

Dispatch already owns most of the authoritative state and APIs for issue sync, reconciliation, grooming actions, and agent run reporting. The remaining heartbeat orchestration should move behind a Dispatch API so any agent can call one stable endpoint instead of carrying local deterministic scripts.

Scope

Add an agent-agnostic heartbeat orchestration API in Dispatch.

Proposed endpoint:

POST /api/agents/{agentName}/heartbeat

Responsibilities:

• authenticate with the existing agent token flow;
• run deterministic Dispatch-side sync/reconciliation steps using shared service code, not by shelling out to local scripts;
• aggregate warnings/errors without failing the whole run for best-effort sync failures;
• record an AgentRun for the heartbeat pass;
• return a compact machine-readable result for the caller.

Suggested response shape:

type AgentHeartbeatResponse = {
  status: "ok" | "warning" | "error";
  agentName: string;
  startedAt: string;
  finishedAt: string;
  summary: string;
  warnings: string[];
  errors: string[];
  touchedIssueUrls: string[];
};

Non-goals

• Do not make model/judgment grooming decisions in this endpoint.
• Do not add Saffron-specific behavior or config.
• Do not depend on workspace-local files or pod-local generated request JSON.

Acceptance criteria

• A generic agent can call the endpoint with agentName and receive a deterministic heartbeat result.
• Existing sync/reconcile/reporting behavior is reused through Dispatch service code.
• Non-critical sync failures are surfaced as warnings in the response and run record.
• Critical failures return status: "error" and an actionable error list.
• Tests cover auth, success, warning aggregation, and failure response behavior.