feat: FIT-1304: Allow strict task overlap enforcement (#9273)

Co-authored-by: bmartel <bmartel@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: bmartel

label_studio/projects/functions/next_task.py

@@ -225,6 +225,38 @@ def get_not_solved_tasks_qs(
             _, not_solved_tasks = _try_tasks_with_overlap(not_solved_tasks)
             queue_info += (' & ' if queue_info else '') + 'Show overlap first'
 
+    # Strict task overlap enforcement: filter out tasks where overlap is already reached
+    # This prevents NEW annotators/reviewers from getting tasks that are already at their annotation limit
+    # Note: Only applies to annotators and reviewers - managers and admins can access all tasks
+    # Note: Postponed tasks are NOT filtered here - they are served with overlap_reached flag
+    # so users can see their work and understand why they can't submit
+    if flag_set('fflag_feat_all_fit_1304_strict_overlap', user=user):
+        lse_project = getattr(project, 'lse_project', None)
+        is_restricted_role = getattr(user, 'is_annotator', False) or getattr(user, 'is_reviewer', False)
+        if lse_project and getattr(lse_project, 'strict_task_overlap', False) and is_restricted_role:
+            # Calculate effective overlap limit
+            # When agreement_threshold is set, allow additional annotators up to max_additional_annotators_assignable
+            max_additional = 0
+            if lse_project.agreement_threshold is not None:
+                max_additional = lse_project.max_additional_annotators_assignable or 0
+
+            # Exclude tasks where distinct annotator count >= effective overlap
+            # Ground truth annotations don't count toward overlap
+            tasks_at_overlap = (
+                Task.objects.filter(project=project)
+                .annotate(
+                    distinct_annotators=Count(
+                        'annotations__completed_by',
+                        filter=Q(annotations__was_cancelled=False, annotations__ground_truth=False),
+                        distinct=True,
+                    )
+                )
+                .filter(distinct_annotators__gte=F('overlap') + max_additional)
+                .values_list('pk', flat=True)
+            )
+
+            not_solved_tasks = not_solved_tasks.exclude(pk__in=tasks_at_overlap)
+
     return not_solved_tasks, user_solved_tasks_array, queue_info, prioritized_on_agreement
 
 

web/apps/labelstudio/src/pages/DataManager/DataManager.jsx

@@ -139,8 +139,12 @@ export const DataManagerPage = ({ ...props }) => {
       api.handleError(response);
     });
 
-    dataManager.on("toast", ({ message, type }) => {
-      toast.show({ message, type });
+    dataManager.on("toast", ({ message, type, id, duration }) => {
+      toast.show({ message, type, id, duration });
+    });
+
+    dataManager.on("toast:dismiss", ({ id } = {}) => {
+      toast.dismiss(id);
     });
 
     dataManager.on("navigate", (route) => {

web/libs/datamanager/src/sdk/dm-sdk.js

@@ -45,7 +45,6 @@ import { unmountComponentAtNode } from "react-dom";
 import camelCase from "lodash/camelCase";
 import { instruments } from "../components/DataManager/Toolbar/instruments";
 import { APIProxy } from "../utils/api-proxy";
-import { FF_LSDV_4620_3_ML, isFF } from "../utils/feature-flags";
 import { objectToMap } from "../utils/helpers";
 import { serializeJsonForUrl, deserializeJsonFromUrl } from "@humansignal/core";
 import { isDefined } from "../utils/utils";
@@ -453,9 +452,7 @@ export class DataManager {
   }
 
   destroy(detachCallbacks = true) {
-    if (isFF(FF_LSDV_4620_3_ML)) {
-      this.destroyLSF();
-    }
+    this.destroyLSF();
     unmountComponentAtNode(this.root);
 
     if (this.store) {

web/libs/datamanager/src/sdk/lsf-sdk.js

@@ -1,4 +1,13 @@
-import { FF_DEV_1752, FF_DEV_2186, FF_DEV_2887, FF_DEV_3034, FF_LSDV_4620_3_ML, isFF } from "../utils/feature-flags";
+import { Button } from "@humansignal/ui";
+import {
+  FF_DEV_1752,
+  FF_DEV_2186,
+  FF_DEV_2887,
+  FF_DEV_3034,
+  FF_LSDV_4620_3_ML,
+  FF_FIT_1304_STRICT_OVERLAP,
+  isFF,
+} from "../utils/feature-flags";
 import { isDefined } from "../utils/utils";
 import { Modal } from "../components/Common/Modal/Modal";
 import { CommentsSdk } from "./comments-sdk";
@@ -32,13 +41,24 @@ const resolveLabelStudio = () => {
 };
 
 // Returns true to suppress (swallow) the error, false to bubble to global handler.
-// We allow 403 PAUSED to bubble so the app-level ApiProvider can show the paused modal
-const errorHandlerAllowPaused = (result) => {
+// We allow certain errors to bubble so the app-level ApiProvider can show modals:
+// - 403 PAUSED: User is paused in the project
+// - 400 OVERLAP_REACHED: Annotation overlap limit has been reached (only when feature flag is enabled)
+const errorHandlerAllowSpecialErrors = (result) => {
   const isPaused =
     result?.status === 403 &&
     typeof result?.response === "object" &&
     result?.response?.display_context?.reason === "PAUSED";
-  return !isPaused;
+
+  // Only handle OVERLAP_REACHED when feature flag is enabled
+  const isOverlapReached =
+    isFF(FF_FIT_1304_STRICT_OVERLAP) &&
+    result?.status === 400 &&
+    typeof result?.response === "object" &&
+    result?.response?.display_context?.reason === "OVERLAP_REACHED";
+
+  // Return false to allow these errors to bubble up to the global handler
+  return !(isPaused || isOverlapReached);
 };
 
 // Support portal URL constants used to construct error reporting links
@@ -47,6 +67,10 @@ const errorHandlerAllowPaused = (result) => {
 export const SUPPORT_URL = "https://support.humansignal.com/hc/en-us/requests/new";
 export const SUPPORT_URL_REQUEST_ID_PARAM = "tf_37934448633869"; // request_id field ID in ZD
 
+// Toast ID for overlap reached message - used to dismiss this specific toast
+// without affecting other toasts like "Annotation Saved"
+const OVERLAP_TOAST_ID = "overlap-reached-toast";
+
 export class LSFWrapper {
   /** @type {HTMLElement} */
   root = null;
@@ -106,6 +130,16 @@ export class LSFWrapper {
     this.interfacesModifier = interfacesModifier;
     this.isInteractivePreannotations = isInteractivePreannotations ?? false;
 
+    // Listen for overlap error modal events (only when feature flag is enabled)
+    if (isFF(FF_FIT_1304_STRICT_OVERLAP)) {
+      this.handleOverlapNextTask = () => this.loadTask();
+      this.handleOverlapCloseTask = () => this.closeTask();
+      this.handleOverlapExitStream = () => this.exitStream();
+      window.addEventListener("overlap-error-next-task", this.handleOverlapNextTask);
+      window.addEventListener("overlap-error-close-task", this.handleOverlapCloseTask);
+      window.addEventListener("overlap-error-exit-stream", this.handleOverlapExitStream);
+    }
+
     let interfaces = [...DEFAULT_INTERFACES];
 
     if (this.project.enable_empty_annotation === false) {
@@ -343,6 +377,10 @@ export class LSFWrapper {
   setLSFTask(task, annotationID, fromHistory, selectPrediction = false) {
     if (!this.lsf) return;
 
+    if (isFF(FF_FIT_1304_STRICT_OVERLAP)) {
+      this.dismissOverlapToast();
+    }
+
     const hasChangedTasks = this.lsf?.task?.id !== task?.id && task?.id;
 
     this.setLoading(true, hasChangedTasks);
@@ -383,10 +421,74 @@ export class LSFWrapper {
     // undefined or true for backward compatibility
     this.lsf.toggleInterface("postpone", this.task.allow_postpone !== false);
     this.lsf.toggleInterface("topbar:task-counter", true);
+
+    if (isFF(FF_FIT_1304_STRICT_OVERLAP)) {
+      // Handle strict task overlap - disable submission controls when overlap is reached
+      // Only process when feature flag is enabled
+      const overlapReached = this.task.overlap_reached === true;
+      this.overlapReached = overlapReached;
+      this.overlapReachedMessage =
+        this.task.overlap_reached_message ||
+        "Annotation overlap has been reached for this task. Your draft is preserved but cannot be submitted.";
+
+      // Set overlap state on LSF store - this will disable buttons with tooltips
+      this.lsf.setFlags({
+        overlapReached,
+        overlapReachedMessage: this.overlapReachedMessage,
+      });
+    } else {
+      this.overlapReached = false;
+      this.overlapReachedMessage = "";
+    }
+
     this.lsf.assignTask(task);
     this.lsf.initializeStore(lsfTask);
     this.setAnnotation(annotationID, fromHistory || isRejectedQueue, selectPrediction);
     this.setLoading(false);
+
+    if (isFF(FF_FIT_1304_STRICT_OVERLAP) && this.overlapReached) {
+      // Show informational message if overlap is reached (only when feature flag is enabled)
+      this.showOverlapReachedMessage();
+    }
+  }
+
+  /**
+   * Show informational message when overlap is reached
+   * @private
+   */
+  showOverlapReachedMessage() {
+    // Use info toast to communicate the overlap status
+    // This is informational, not an error, so we use a neutral tone
+    // Use a specific ID so we can dismiss this toast without affecting others
+    this.datamanager.invoke("toast", {
+      id: OVERLAP_TOAST_ID,
+      message: (
+        <div className="flex items-center justify-between">
+          <span>{this.overlapReachedMessage}</span>
+          <Button
+            onClick={() => {
+              this.datamanager.invoke("toast:dismiss", { id: OVERLAP_TOAST_ID });
+              this.handleOverlapNextTask();
+            }}
+            className="ml-4"
+            size="small"
+            look="outlined"
+          >
+            Next Task
+          </Button>
+        </div>
+      ),
+      type: "info",
+      duration: -1,
+    });
+  }
+
+  /**
+   * Dismiss the overlap reached toast if it's showing
+   * @private
+   */
+  dismissOverlapToast() {
+    this.datamanager.invoke("toast:dismiss", { id: OVERLAP_TOAST_ID });
   }
 
   /** @private */
@@ -597,6 +699,28 @@ export class LSFWrapper {
     if (status === 200 || status === 201) {
       this.datamanager.invoke("toast", { message: successMessage, type: "info" });
     } else if (status !== undefined) {
+      // Skip toast for errors that are handled by global modal handlers via display_context
+      // These errors bubble up to ApiProvider which shows appropriate modals
+      // Note: display_context is in result.response for API error responses
+      const displayReason = result?.response?.display_context?.reason;
+      const isPausedError = displayReason === "PAUSED";
+      const isOverlapError = isFF(FF_FIT_1304_STRICT_OVERLAP) && displayReason === "OVERLAP_REACHED";
+      if (isPausedError || isOverlapError) {
+        // Also update local state for overlap reached (only when feature flag is enabled)
+        if (isOverlapError) {
+          this.overlapReached = true;
+          this.overlapReachedMessage =
+            result?.response?.detail ||
+            "Annotation overlap has been reached for this task. Your draft is preserved but cannot be submitted.";
+          // Set overlap state on LSF store - this will disable buttons with tooltips
+          this.lsf.setFlags({
+            overlapReached: true,
+            overlapReachedMessage: this.overlapReachedMessage,
+          });
+        }
+        return;
+      }
+
       const requestId = result?.$meta?.headers?.get("x-ls-request-id");
       const supportUrl = requestId ? `${SUPPORT_URL}?${SUPPORT_URL_REQUEST_ID_PARAM}=${requestId}` : SUPPORT_URL;
 
@@ -623,6 +747,12 @@ export class LSFWrapper {
 
   /** @private */
   onSubmitAnnotation = async () => {
+    // Prevent submission if overlap is reached (only when feature flag is enabled)
+    if (isFF(FF_FIT_1304_STRICT_OVERLAP) && this.overlapReached) {
+      this.showOverlapReachedMessage();
+      return;
+    }
+
     const exitStream = this.shouldExitStream();
     const loadNext = exitStream ? false : this.shouldLoadNext();
     const result = await this.submitCurrentAnnotation(
@@ -633,7 +763,7 @@ export class LSFWrapper {
           { taskID },
           { body },
           // errors are displayed by "toast" event - we don't want to show blocking modal
-          { errorHandler: errorHandlerAllowPaused },
+          { errorHandler: errorHandlerAllowSpecialErrors },
         );
       },
       false,
@@ -667,7 +797,7 @@ export class LSFWrapper {
           body: serializedAnnotation,
         },
         // errors are displayed by "toast" event - we don't want to show blocking modal
-        { errorHandler: errorHandlerAllowPaused },
+        { errorHandler: errorHandlerAllowSpecialErrors },
       );
     });
     const status = result?.$meta?.status;
@@ -804,6 +934,12 @@ export class LSFWrapper {
   };
 
   onSkipTask = async (_, { comment } = {}) => {
+    // Prevent skipping if overlap is reached (only when feature flag is enabled)
+    if (isFF(FF_FIT_1304_STRICT_OVERLAP) && this.overlapReached) {
+      this.showOverlapReachedMessage();
+      return;
+    }
+
     // Manager roles that can force-skip unskippable tasks (OW=Owner, AD=Admin, MA=Manager)
     const MANAGER_ROLES = ["OW", "AD", "MA"];
     const task = this.task;
@@ -814,7 +950,9 @@ export class LSFWrapper {
     const canSkip = !skipDisabled || hasForceSkipPermission;
     if (!canSkip) {
       console.warn("Task cannot be skipped: allow_skip is false and user lacks manager role");
-      this.showOperationToast(400, null, "This task cannot be skipped", { error: "Task cannot be skipped" });
+      this.showOperationToast(400, null, "This task cannot be skipped", {
+        error: "Task cannot be skipped",
+      });
       return;
     }
     const result = await this.submitCurrentAnnotation(
@@ -832,7 +970,7 @@ export class LSFWrapper {
           id === undefined ? "submitAnnotation" : "updateAnnotation",
           params,
           options,
-          { errorHandler: errorHandlerAllowPaused },
+          { errorHandler: errorHandlerAllowSpecialErrors },
         );
       },
       true,
@@ -1082,10 +1220,28 @@ export class LSFWrapper {
   }
 
   destroy() {
+    // Clean up overlap error event listeners and dismiss toast (only when feature flag is enabled)
+    if (isFF(FF_FIT_1304_STRICT_OVERLAP)) {
+      window.removeEventListener("overlap-error-next-task", this.handleOverlapNextTask);
+      window.removeEventListener("overlap-error-close-task", this.handleOverlapCloseTask);
+      window.removeEventListener("overlap-error-exit-stream", this.handleOverlapExitStream);
+      // Dismiss the overlap toast if it's showing - this ensures the toast doesn't
+      // persist after leaving the labeling interface
+      this.dismissOverlapToast();
+    }
+
     this.lsfInstance?.destroy?.();
     this.lsfInstance = null;
   }
 
+  /**
+   * Close the current task panel (for DataManager context)
+   */
+  closeTask() {
+    // Invoke the data manager's close task action
+    this.datamanager.invoke("closeTask");
+  }
+
   get taskID() {
     return this.task.id;
   }

web/libs/datamanager/src/stores/Assignee.js

@@ -66,13 +66,14 @@ export const Assignee = types
       };
     } else {
       const { user_id, annotated, review, reviewed, ...user } = sn;
+      const id = user_id ?? sn.id;
 
       // When global user fetching is disabled, always create user objects, otherwise use references via user id
       // If we only have user_id and no other user properties, just use the user_id as reference
       const hasUserProperties = Object.keys(user).length > 0;
       result = {
-        id: user_id,
-        user: isFF(FF_DISABLE_GLOBAL_USER_FETCHING) && hasUserProperties ? { id: user_id, ...user } : user_id, // Use user_id as reference
+        id,
+        user: isFF(FF_DISABLE_GLOBAL_USER_FETCHING) && hasUserProperties ? { id, ...user } : id, // Use user_id as reference
         annotated,
         review,
         reviewed,

web/libs/datamanager/src/stores/DataStores/tasks.js

@@ -29,6 +29,8 @@ export const create = (columns) => {
     drafts: types.frozen(),
     source: types.maybeNull(types.string),
     was_cancelled: false,
+    overlap_reached: types.maybeNull(types.boolean),
+    overlap_reached_message: types.maybeNull(types.string),
     assigned_task: false,
     queue: types.optional(types.maybeNull(types.string), null),
     // annotation to select on rejected queue

web/libs/datamanager/src/utils/feature-flags.js

@@ -62,6 +62,12 @@ export const FF_DISABLE_GLOBAL_USER_FETCHING =
  */
 export const FF_INTERACTIVE_JSON_VIEWER = "fflag_feat_front_interactive_json_viewer_short";
 
+/**
+ * Strict task overlap enforcement - prevents annotators from submitting
+ * annotations when task overlap limit has been reached
+ */
+export const FF_FIT_1304_STRICT_OVERLAP = "fflag_feat_all_fit_1304_strict_overlap";
+
 // Customize flags
 const flags = {};