claude-foundations/claude/agent-dispatch-preflight.md

Agent Dispatch Pre-flight

When this applies

Before starting /loop ... /orchestrate, /dispatch, or any unattended or overnight agent batch. Run this checklist once, before the loop starts — not mid-run.

Checklist — all must pass before the loop starts

1. CP reachable. curl -fsS "$CP_URL/health" returns 200. CP_URL is defined in claude/agent-runtimes-cp.md — read that file for the correct value and any auth headers required.

2. A dispatcher is polling. Check the CP dispatchers endpoint (see agent-runtimes-cp.md). A queued task with no live dispatcher sits forever — confirm at least one dispatcher is active before queuing work.

3. Scaffolding present.

   • .agent-tasks.json exists and passes jq empty .agent-tasks.json (valid JSON).
   • All templates, repos, and input files referenced by tasks are resolvable from this host.
   • Agent push keys are loaded (ssh-add -l) — container agents push branches back; a missing key silently fails the push.

4. Auth done this session. CLAUDE_CODE_OAUTH_TOKEN is set in the environment or readable from ~/dev/claude/secrets/claude/long_lived_oauth_token. Confirm before launching containers.

Do not start the loop until all four pass. Surface any failure to the user and wait for remediation.

Circuit-breaker

Track task-state changes across invocations. After 5 consecutive invocations with no state change (no task moved from pending→running, running→completed/failed, etc.): stop dispatching, print a stuck-queue report listing each task and its current status, and wait for the user. Never run an unattended loop without this guard.

Recovery

If a dispatch batch needs to be aborted mid-run:

• Drain queued tasks: set pending tasks to cancelled in .agent-tasks.json before the next invocation so the orchestrator does not launch them.
• Let running containers finish or docker stop them explicitly.
• Re-dispatch from a clean state once the root cause is resolved.