Work coordinator
A durable unit of work belongs to one GLOBAL or org coordinator. Lanes contain the build/review/fix/ship DAG, real ticket links, blockers and an append-only event log. Ticket lists derive from real issue state. A worker leases ready work within its class capacity, heartbeats, and completes with evidence. Expired workers retry with backoff; exhausted attempts and failed close-out go to one coordinator/day digest with a human owner.
Author/fix success queues review; first FAIL queues fix, second FAIL close-out; PASS queues integration/shipping according to policy. A ship/install receipt marks work live and attempts linked ticket closure through normal issue permissions. Failed closure remains an owned pending action. The queue grants no deployment, machine-control or new agent-dispatch authority.
Default ON; the existing platform setting workCoordinator.enabled=false stops REST, MCP and feed. Org administrators configure their own queue. GLOBAL needs verified platform administrators. An org persona may name GLOBAL as parent, but an explicit expiring/revocable grant is required even for summaries. A parent gets only IDs, kinds, states, priority, next-action labels and timestamps; it cannot open org bodies or lease org work.
Agent keys need explicit work scope and coordinator principal capabilities, plus write on mutations. Creator privileges never carry through a key. Project/person-scoped credentials, runner keys and user tokens cannot cover coordinator data. Every request and live feed catch-up rechecks current authority.
The admin page is /admin/work-coordinator; an org page is /o/<slug>/work-coordinator. REST starts at /v1/work-coordinators; view is its HTTP materialized mirror, why is its event explanation, and ws?since=<revision> uses hello/snapshot/delta/ping/resync. Committed PostgreSQL events drive subscriptions; catch-up repairs missed notifications. Work inputs and lease tokens are omitted from feed views.
The design maps every supplied lane field. The installation plan describes import, the default-on staged engine write-through switch, worker adapters and rollback. Local browser acceptance and org phone acceptance use fake principals on a throwaway stack. Production deployment, notification delivery and harness switch-over belong to the orchestrator after review.
Capacity belongs to each coordinator and worker class. New coordinators get the shared class defaults (codex 4, claude 4, machine 2, agent 4, person 1). A tenant holding its slots cannot consume another tenant's capacity. Queued work stays queued while awaiting capacity, dependencies, a block or a paused lane. Those gates also postpone overdue escalation for unleased work.
Before leased work can become running, the action must include runIdentity: positive integer pid, nonempty agentId, engine, account, hostname, absolute worktreePath, branch, and ISO startedAt at or before server time. These are worker-reported metadata; the authenticated principal is recorded separately. Account means a nonsecret account label, never a token. REST and MCP share this contract. why returns immutable attempt identities and their running/completed/failed/dead/released status, withholding lease tokens.
Heartbeats preserve the requested lease duration (5–300 seconds). Stale heartbeat or expired lease fences writes immediately. The API checks every 15 seconds and marks dead attempts, releases leases, and requeues with backoff or dead-letters exhausted attempts. This recovery keeps working if every worker has died and obeys workCoordinator.enabled. The foreground worker's PID identifies the supervisor that owns its command and descendants; it records actual hostname, checkout branch, path and start time before spawning the command. CLI workers require GOODQA_AGENT_ID, GOODQA_AGENT_ENGINE and GOODQA_AGENT_ACCOUNT (nonsecret labels). An execution worker records its monitoring supervisor identity and grants no new dispatch authority.
Migration 11746 introduces the coordinator tables after observed open-lane reservations through 11743. Migration 11747 adds identities and attempts. Existing unidentified running/review/shipping attempts are requeued before the working-state identity constraint is added. Run-history acceptance is materialized by the local host proof; use authorized fixture IDs and a browser storage state after deployment.
- API reference: /v1/openapi.json
- MCP tools: tool reference;
work_coordinatorslists the coordinators this explicit work credential may read. - Runbook: installation and rollback
A verified administrator uses POST /v1/work-coordinators/{coordinatorId}/maintain to run recovery immediately. Parent coordination uses /v1/work-coordinators/{coordinatorId}/children/{childId}/summary for a redacted view and the sibling escalations, assign, steer and escalate routes for authorized parent actions. Each action requires its own live parent grant; a parent relationship alone gives no access.
Worker inventory stores server-timed capability, toolchain and CPU/RAM/disk observations. Placement comes from explicit inputs.placement, validated on both creation and assignment; checkout paths, notes and words in a brief never imply locality. Malformed legacy queued placements are skipped. A malformed active placement fences its worker and exclusive-resource requests until corrected or expired, while unrelated workers remain available. Heartbeats evict workers last observed more than seven days ago only when they hold no current lease; the pool remains capped at 256 entries. Wake capability stays unavailable.
For lane worktrees outside the CLI directory, the operator sets GOODQA_WORKER_REPOSITORY_ROOTS to a JSON array of absolute trusted directory roots, for example ["/srv/qa/lanes"]. It accepts at most 64 roots and uses canonical paths with directory boundaries; queue inputs cannot add authority, and a symlink outside those roots is refused. Exact identity.repositories entries with git.inspect remain supported by the worker adapter. The CLI directory remains the default registered repository. Unknown repositories are inspected only as bounded regular-file data; registered Git reads disable hooks and fsmonitor. CLI cleanup takes an exact owned artifact manifest and uses the host clock for retention checks.
Monitor configuration and cursors persist in the existing worker pool and advance through /v1/cron/drain-acks. A failed inventory tick is logged and returns workerInventory: { processed: 0, failed: true }; the existing Slack, federation and error-monitor drains still run.