feat(mcp): implement graceful maintenance-drain mode (Closes #659)

Add durable per-repo drain state, allocator assignment stop, mutation
deferral with a safety allowlist, observable status, and capability-gated
enter/exit tools. Drain proof/restart gate remain #661.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

allocator_service.py

@@ -25,6 +25,7 @@ import uuid
 from dataclasses import dataclass, field
 from typing import Any, Mapping, Sequence
 
+import maintenance_drain
 from control_plane_db import (
     ControlPlaneDB,
     ControlPlaneError,
@@ -885,6 +886,46 @@ def allocate_next_work(
             "allocation_mode": (allocation_mode or "").strip() or None,
         }
 
+    # #659 AC2: while maintenance drain is active, no new work is assigned —
+    # for dry-run and apply alike, so a preview can never be read as evidence
+    # that work was assignable during the drain. Checked before session
+    # registration so a drained allocator leaves no new state behind.
+    try:
+        drain_record = db.read_maintenance_drain(remote=remote, org=org, repo=repo)
+    except Exception as exc:  # noqa: BLE001 — unreadable drain state fails closed
+        return {
+            "success": False,
+            "outcome": OUTCOME_NO_SAFE,
+            "reasons": [
+                f"maintenance-drain state lookup failed: {exc} (fail closed, #659)"
+            ],
+            "skipped": [],
+            "assignment": None,
+            "substrate": "control_plane_db",
+        }
+
+    drain_decision = maintenance_drain.classify_assignment(drain_record)
+    if not drain_decision["assignment_allowed"]:
+        return {
+            "success": True,
+            "outcome": OUTCOME_WAIT,
+            "apply": apply,
+            "role": role_norm,
+            "allocation_mode": mode,
+            "remote": remote,
+            "org": org,
+            "repo": repo,
+            "selected": None,
+            "reasons": list(drain_decision["reasons"]),
+            "reason_code": drain_decision["reason_code"],
+            "skipped": [],
+            "assignment": None,
+            "substrate": "control_plane_db",
+            "maintenance_drain": maintenance_drain.status_payload(
+                drain_record, remote=remote, org=org, repo=repo
+            ),
+        }
+
     session_id = (session_id or "").strip() or f"alloc-{uuid.uuid4().hex[:12]}"
     try:
         db.upsert_session(