Add control-plane DB for atomic LLM work assignment, leases, and session coordination #613

New Issue

2026-07-09T18:50:45-05:00

jcwalker3 commented

2026-07-09 18:50:45 -05:00

Problem

The current Gitea/MCP workflow allows multiple LLMs to independently inspect the queue and choose the same issue or PR. Existing leases and guards often catch unsafe actions after work has already started, but they do not prevent duplicate work up front. This causes reviewer collisions, stale lease confusion, duplicate comments, contested approvals, and wasted validation.

Goal

Add a small MCP Control Plane database that provides transactional coordination for sessions, assignments, leases, heartbeats, terminal locks, and Sentry-linked incidents. Gitea remains the durable source of truth for issue/PR history, comments, reviews, and labels.

Related work (do not treat as duplicates)

#600 — controller-owned work allocator API and assignment routing (gitea_allocate_next_work). This issue is the durable DB substrate that makes #600 atomic under concurrency.
#612 — multi-project Sentry/GlitchTip incident bridge with Gitea linking. The control-plane sentry_links / incident work-item kinds should integrate with that bridge; Gitea remains the durable work record.

Recommended backend

MVP may use SQLite if the control plane is single-process.
Long-term server deployment should use Postgres, especially if running on Proxmox with multiple concurrent LLM sessions.
Do not use the DB to bypass Gitea workflow rules.

Required architecture

LLM workers ask the allocator for work.
Allocator uses the DB to atomically reserve exactly one safe work item.
Gitea is updated with durable comments/labels/handoffs after assignment or state changes.
Sentry issues/events may be linked into the DB and mirrored to Gitea issues.
No LLM self-selects work outside allocator assignment.

Authority model

System	Owns
Control-plane DB	Sessions, atomic assignment, leases, heartbeats, terminal lock index, event log
Gitea	Durable issue/PR history, comments, reviews, labels, merge/close
Sentry/GlitchTip	Incidents/events (observed; linked via bridge — see #612)

Rule of thumb: DB coordinates, Gitea records, Sentry observes.

Required tables/entities

1. sessions

session_id
role/profile
namespace
pid
started_at
last_heartbeat_at
status

2. work_items

repo/org
kind: issue/pr/sentry_incident
number
state
priority
current_head_sha
updated_at

3. leases

lease_id
work_item_id
session_id
role
phase
expires_at
heartbeat_at
status

4. assignments

assignment_id
work_item_id
session_id
allowed_action
expected_head_sha
status

5. terminal_locks

repo/org
terminal_pr
review_id
decision
status
cleanup_state

6. events

event_id
work_item_id
type
message
created_at

7. sentry_links

sentry_issue_id
sentry_url
gitea_issue_number
fingerprint
status

Required allocator behavior

gitea_allocate_next_work(apply=true) must atomically assign one safe item or return WAIT.
Two concurrent sessions cannot receive the same issue/PR.
Current-head REQUEST_CHANGES routes to author, not reviewer/merger.
Stale approval routes to reviewer.
Contested/contaminated approval routes to controller/reconciler diagnosis.
Active foreign leases return WAIT or owner-resume.
Terminal-review lock routes to terminal-path resolution before downstream review work.
Merged/closed PRs are never assigned.
Locked issues are never assigned to another worker unless lease cleanup/adoption is sanctioned.

Non-goals

Do not replace Gitea as the durable work/history store.
Do not let the DB authorize merges, approvals, or label transitions that Gitea gates forbid.
Do not allow LLM workers to self-select work outside the allocator.
Do not treat Gitea comments alone as the concurrency lock (they mirror state; DB is authoritative for assignment).

Acceptance criteria

DB-backed allocator prevents two workers from receiving the same assignment.
Assignment creation and lease creation happen in one transaction.
Every assignment includes role, issue/PR number, expected head SHA, lease ID, expiry, allowed actions, and forbidden actions.
Worker mutations require a valid assignment/lease.
Gitea comments/labels mirror assignment state but are not the only lock source.
Heartbeats update the DB and optionally summarize to Gitea without comment spam.
Expired/abandoned leases can be reconciled through sanctioned tooling.
Tests simulate four concurrent LLMs asking for work and prove they receive different assignments or WAIT.
Tests cover active lease, stale lease, terminal lock, stale approval, contested approval, current-head REQUEST_CHANGES, and merge-ready approval.
Documentation states: DB coordinates, Gitea records, Sentry observes.

## Problem The current Gitea/MCP workflow allows multiple LLMs to independently inspect the queue and choose the same issue or PR. Existing leases and guards often catch unsafe actions after work has already started, but they do not prevent duplicate work up front. This causes reviewer collisions, stale lease confusion, duplicate comments, contested approvals, and wasted validation. ## Goal Add a small MCP Control Plane database that provides transactional coordination for sessions, assignments, leases, heartbeats, terminal locks, and Sentry-linked incidents. Gitea remains the durable source of truth for issue/PR history, comments, reviews, and labels. ## Related work (do not treat as duplicates) * **#600** — controller-owned work allocator API and assignment routing (`gitea_allocate_next_work`). This issue is the **durable DB substrate** that makes #600 atomic under concurrency. * **#612** — multi-project Sentry/GlitchTip incident bridge with Gitea linking. The control-plane `sentry_links` / incident work-item kinds should integrate with that bridge; Gitea remains the durable work record. ## Recommended backend * MVP may use SQLite if the control plane is single-process. * Long-term server deployment should use Postgres, especially if running on Proxmox with multiple concurrent LLM sessions. * Do not use the DB to bypass Gitea workflow rules. ## Required architecture * LLM workers ask the allocator for work. * Allocator uses the DB to atomically reserve exactly one safe work item. * Gitea is updated with durable comments/labels/handoffs after assignment or state changes. * Sentry issues/events may be linked into the DB and mirrored to Gitea issues. * No LLM self-selects work outside allocator assignment. ### Authority model | System | Owns | |--------|------| | **Control-plane DB** | Sessions, atomic assignment, leases, heartbeats, terminal lock index, event log | | **Gitea** | Durable issue/PR history, comments, reviews, labels, merge/close | | **Sentry/GlitchTip** | Incidents/events (observed; linked via bridge — see #612) | **Rule of thumb:** DB coordinates, Gitea records, Sentry observes. ## Required tables/entities ### 1. sessions * session_id * role/profile * namespace * pid * started_at * last_heartbeat_at * status ### 2. work_items * repo/org * kind: issue/pr/sentry_incident * number * state * priority * current_head_sha * updated_at ### 3. leases * lease_id * work_item_id * session_id * role * phase * expires_at * heartbeat_at * status ### 4. assignments * assignment_id * work_item_id * session_id * allowed_action * expected_head_sha * status ### 5. terminal_locks * repo/org * terminal_pr * review_id * decision * status * cleanup_state ### 6. events * event_id * work_item_id * type * message * created_at ### 7. sentry_links * sentry_issue_id * sentry_url * gitea_issue_number * fingerprint * status ## Required allocator behavior * `gitea_allocate_next_work(apply=true)` must atomically assign one safe item or return WAIT. * Two concurrent sessions cannot receive the same issue/PR. * Current-head REQUEST_CHANGES routes to author, not reviewer/merger. * Stale approval routes to reviewer. * Contested/contaminated approval routes to controller/reconciler diagnosis. * Active foreign leases return WAIT or owner-resume. * Terminal-review lock routes to terminal-path resolution before downstream review work. * Merged/closed PRs are never assigned. * Locked issues are never assigned to another worker unless lease cleanup/adoption is sanctioned. ## Non-goals * Do not replace Gitea as the durable work/history store. * Do not let the DB authorize merges, approvals, or label transitions that Gitea gates forbid. * Do not allow LLM workers to self-select work outside the allocator. * Do not treat Gitea comments alone as the concurrency lock (they mirror state; DB is authoritative for assignment). ## Acceptance criteria 1. DB-backed allocator prevents two workers from receiving the same assignment. 2. Assignment creation and lease creation happen in one transaction. 3. Every assignment includes role, issue/PR number, expected head SHA, lease ID, expiry, allowed actions, and forbidden actions. 4. Worker mutations require a valid assignment/lease. 5. Gitea comments/labels mirror assignment state but are not the only lock source. 6. Heartbeats update the DB and optionally summarize to Gitea without comment spam. 7. Expired/abandoned leases can be reconciled through sanctioned tooling. 8. Tests simulate four concurrent LLMs asking for work and prove they receive different assignments or WAIT. 9. Tests cover active lease, stale lease, terminal lock, stale approval, contested approval, current-head REQUEST_CHANGES, and merge-ready approval. 10. Documentation states: DB coordinates, Gitea records, Sentry observes.