epic: make Dispatch the harness-agnostic agent control plane

[joryirving]

Goal

Make Dispatch usable by any harness with the same simple loop:

1. ask Dispatch for one task
2. if idle, stop before starting a model
3. execute exactly that task
4. report the result
5. stop

Harnesses include OpenClaw, Hermes, Claude Code, Codex, OpenCode, and manual/CLI runners.

Problem

Too much required behavior currently lives outside Dispatch: cron prompts, helper scripts, heartbeat state, workflow repos, and harness-specific glue. That makes the product hard to explain and harder to run.

Non-goals

• Do not require upstream changes to any harness.
• Do not make Dispatch an agent runner.
• Do not make this OpenClaw-specific.
• Do not require a second runtime repo.
• Do not let worker tasks merge PRs.

Target contract

Dispatch owns task selection, queue state, claims, follow-up detection, stop conditions, and allowed/forbidden actions.

A harness only executes the returned task.

Child issues

Child issues will cover:

• task contract/schema
• next-task endpoint
• report endpoint
• PR follow-up detection
• groomer task mode
• harness docs/examples
• runtime sprawl cleanup

Acceptance criteria

• A generic harness can integrate with Dispatch using documented HTTP calls.
• A worker can get implement, followup-pr, or idle.
• A groomer can get groom or idle.
• Idle is cheap and does not require starting an LLM.
• Runtime prompts/scripts are no longer required from a second repo.
• Worker task contract explicitly forbids merge/groom/claim-another-issue actions.
• Existing queue behavior remains compatible while the new contract is introduced.

[itsmiso-ai]

All acceptance criteria for the harness-agnostic agent control plane epic are satisfied.

Verified acceptance criteria:

1. ✅ A generic harness can integrate with Dispatch using documented HTTP calls — docs/generic-harness-loop.md provides a complete harness-agnostic integration guide with curl, Python, and pseudo-code examples.

2. ✅ A worker can get implement, followup-pr, or idle — The GET /api/agents/{agentName}/next-task endpoint returns all four task types. Extensively tested in next-task/route.test.ts (40+ test cases).

3. ✅ A groomer can get groom or idle — The mode=groom parameter is fully supported and tested (20+ groom-mode test cases).

4. ✅ Idle is cheap and does not require starting an LLM — shouldRun: false on idle tasks signals harnesses to exit immediately before model work.

5. ✅ Runtime prompts/scripts are no longer required from a second repo — docs/generic-harness-loop.md explicitly states: "No custom runtime scripts, no second runtime repo, and no OpenClaw-specific logic are required."

6. ✅ Worker task contract explicitly forbids merge/groom/claim-another-issue actions — Enforced in src/lib/agent-task.ts task descriptions (lines 65, 71) and documented in AGENTS.md Worker Boundaries section.

7. ✅ Existing queue behavior remains compatible — The legacy GET /api/agents/{agentName}/queue endpoint continues to work alongside next-task. Both now share queue-fetching logic via src/lib/agent-queue-fetch.ts (PR refactor: share agent queue fetching logic #440).

Supporting work completed in this release cycle:

• Shared queue-fetching logic extracted (PR refactor: share agent queue fetching logic #440, issue Extract shared queue-fetching logic between agents/[agentName]/queue/route.ts and agents/[agentName]/next-task/route.ts #414)
• Route test coverage for all API endpoints including auth/data-leak regression (PR test: add route coverage for API data access #441, issue Add co-located route.test.ts for the 17 routes currently uncovered, prioritized by data-leak risk (/api/audit, /api/auto #416)
• next-task smoke checks documented (PR docs: add next-task smoke checks #437, issue Add a smoke check to docs/smoke-checklist.md that exercises the next-task end-to-end happy path and an idle path (mirror #422)
• MCP startup warning for unset agent name (PR fix: warn when MCP agent name is unset #436, issue Add a startup-time warning in the MCP server entrypoint if DISPATCHAGENTNAME is unset (mirror the DISPATCHAUTHMODE=disab #421)
• Configurable lanes fully documented (PR docs: document configurable lane setups #435, issue docs: document configurable lane setups #388)

Closing this epic.