gate(eligibility): hold PRs against a priority issue until its window opens (#9738)

Priority issues carry the highest payout, so assignment fairness matters most there -- and first-come
pickup is only fair if everyone can SEE the issue before anyone can act on it. A PR opened moments
after the label lands means the window between "issue becomes valuable" and "issue is claimed" was
effectively zero for everyone else watching the repo.

A PR closing a `gittensor:priority` issue is now gate-eligible only once the label has been publicly
present for `gate.priorityEligibilityWindow` minutes (default 30, per repo, `0` disables it). A PR
arriving inside the window is NOT rejected: it is HELD with a neutral comment naming the moment it
becomes eligible, and proceeds normally once the window elapses. No penalty beyond waiting.

Two decisions worth stating:

- The clock is anchored to the EARLIEST labeling event, not the most recent. The spec requires that
  re-applying the label not reset the window for already-open PRs; an earliest anchor gives that to
  everyone and makes "when does this issue open for work" a single knowable instant nothing can move.
- Every unknown FAILS OPEN -- an unreadable timestamp, an absent label, a GraphQL error, a missing
  token. Holding a contributor's PR on a fact we could not read is a penalty for our own gap.

The hold reuses the existing merge-hold rail (`heldForManualReview`), so it can never close a PR.

Merge holds become DATA rather than a widening list of booleans. `MERGE_HOLD_INPUTS` is the one
table; the input type (`Record<MergeHoldInput, boolean>`), the `heldForManualReview` fold, and both
test fixtures all derive from it. Adding a hold was three independent edits that could each be
forgotten -- declaring one and not folding it into the decision compiled fine. It is now one entry,
and omitting the wiring is a compile error at the single call site.

`normalizeOptionalNonNegativeInteger` exists because `0` is meaningful here (it turns the rule off)
and the positive-integer normalizer would have discarded it as invalid and silently applied the
default -- an operator's explicit "off" becoming "on".

100% statements and branches on both changed source files.

Author: JSONbored

.loopover.yml.example

@@ -407,6 +407,22 @@ gate:
   # DB-backed (dashboard-settable too); this overrides the stored value.
   requireFreshRebaseWindow: 10
 
+  # Priority-issue eligibility window (#9738) — minutes a `gittensor:priority` label must have been publicly
+  # present before a PR that closes that issue is gate-eligible.
+  #
+  # Priority carries the highest payout, so assignment fairness matters most there, and first-come pickup is
+  # only fair if everyone can SEE the issue before anyone can act on it: a PR opened moments after the label
+  # lands means the window between "issue becomes valuable" and "issue is claimed" was effectively zero for
+  # everyone else watching the repo.
+  #
+  # A PR arriving inside the window is NOT rejected. It is HELD, with a neutral comment naming the moment it
+  # becomes eligible, and proceeds normally once the window elapses — no penalty beyond waiting, and the
+  # contributor keeps their work. The clock is anchored to the EARLIEST time the label was applied, so
+  # re-applying it never resets the window for anyone.
+  #
+  # Whole number of minutes, 0 to 1440. `0` turns the rule off. Default: 30. Config-as-code only.
+  priorityEligibilityWindow: 30
+
   # Stale-base auto-rebase threshold. When the repository's current default branch is at least this many
   # commits ahead of a PR's own base commit, the pre-review readiness gate forces an update_branch before
   # review runs — independent of GitHub's own mergeable_state "behind" signal, which only fires when the

apps/loopover-ui/public/openapi.json

@@ -10191,6 +10191,12 @@
           "guardrailEscalationSelfConsistencyRuns": {
             "type": "number",
             "nullable": true
+          },
+          "priorityEligibilityWindowMinutes": {
+            "type": "integer",
+            "nullable": true,
+            "minimum": 0,
+            "maximum": 1440
           }
         },
         "required": [

config/examples/loopover.full.yml

@@ -421,6 +421,22 @@ gate:
   # DB-backed (dashboard-settable too); this overrides the stored value.
   requireFreshRebaseWindow: 10
 
+  # Priority-issue eligibility window (#9738) — minutes a `gittensor:priority` label must have been publicly
+  # present before a PR that closes that issue is gate-eligible.
+  #
+  # Priority carries the highest payout, so assignment fairness matters most there, and first-come pickup is
+  # only fair if everyone can SEE the issue before anyone can act on it: a PR opened moments after the label
+  # lands means the window between "issue becomes valuable" and "issue is claimed" was effectively zero for
+  # everyone else watching the repo.
+  #
+  # A PR arriving inside the window is NOT rejected. It is HELD, with a neutral comment naming the moment it
+  # becomes eligible, and proceeds normally once the window elapses — no penalty beyond waiting, and the
+  # contributor keeps their work. The clock is anchored to the EARLIEST time the label was applied, so
+  # re-applying it never resets the window for anyone.
+  #
+  # Whole number of minutes, 0 to 1440. `0` turns the rule off. Default: 30. Config-as-code only.
+  priorityEligibilityWindow: 30
+
   # Stale-base auto-rebase threshold. When the repository's current default branch is at least this many
   # commits ahead of a PR's own base commit, the pre-review readiness gate forces an update_branch before
   # review runs — independent of GitHub's own mergeable_state "behind" signal, which only fires when the

packages/loopover-engine/src/focus-manifest.ts

@@ -209,6 +209,12 @@ export type FocusManifestGateConfig = {
    *  (byte-identical to today) — a discrete positive-minutes count, not a score, so it is neither clamped
    *  nor rounded; an invalid value (fractional, non-positive, non-finite) is dropped with a warning. */
   requireFreshRebaseWindowMinutes: number | null;
+  /** `gate.priorityEligibilityWindow` (#9738): minutes a `gittensor:priority` label must have been publicly
+   *  present before a PR closing that issue is gate-eligible. Priority issues carry the highest payout, so
+   *  first-come pickup is only fair if everyone can see the issue before anyone can act on it. A PR inside
+   *  the window is HELD with a neutral comment, never rejected, and proceeds once the window elapses.
+   *  `0` disables the rule; null means the shipped default (30). */
+  priorityEligibilityWindowMinutes: number | null;
   /** `gate.staleBaseAheadByThreshold` (#review-grounding stale-base fact): a commit count. When the repo's
    *  current default branch is at least this many commits ahead of a PR's own base commit, the pre-review
    *  readiness gate forces an `update_branch` (same action class as the existing `mergeableState: "behind"`
@@ -1386,6 +1392,7 @@ const EMPTY_GATE_CONFIG: FocusManifestGateConfig = {
   dryRun: null,
   premergeContentRecheck: null,
   requireFreshRebaseWindowMinutes: null,
+  priorityEligibilityWindowMinutes: null,
   staleBaseAheadByThreshold: null,
   claMode: null,
   claConsentPhrase: null,
@@ -1837,6 +1844,7 @@ const GATE_TOP_LEVEL_KEYS = new Set<string>([
   "dryRun",
   "premergeContentRecheck",
   "requireFreshRebaseWindow",
+  "priorityEligibilityWindow",
   "staleBaseAheadByThreshold",
   "claMode",
   "cla",
@@ -1941,6 +1949,8 @@ function parseGateConfig(value: JsonValue | undefined, warnings: string[]): Focu
     dryRun: normalizeOptionalBoolean(record.dryRun, "gate.dryRun", warnings),
     premergeContentRecheck: normalizeOptionalBoolean(record.premergeContentRecheck, "gate.premergeContentRecheck", warnings),
     requireFreshRebaseWindowMinutes: normalizeOptionalPositiveInteger(record.requireFreshRebaseWindow, "gate.requireFreshRebaseWindow", warnings),
+    // Zero is MEANINGFUL here (it turns the rule off), so this cannot use normalizeOptionalPositiveInteger.
+    priorityEligibilityWindowMinutes: normalizeOptionalNonNegativeInteger(record.priorityEligibilityWindow, "gate.priorityEligibilityWindow", warnings, MAX_PRIORITY_ELIGIBILITY_WINDOW_MINUTES),
     staleBaseAheadByThreshold: normalizeOptionalPositiveInteger(record.staleBaseAheadByThreshold, "gate.staleBaseAheadByThreshold", warnings),
     claMode: normalizeOptionalGateMode(record.claMode, "gate.claMode", warnings),
     claConsentPhrase: parsePublicSafeText(claRecord?.consentPhrase, "gate.cla.consentPhrase", warnings),
@@ -2004,6 +2014,7 @@ function parseGateConfig(value: JsonValue | undefined, warnings: string[]): Focu
     gate.dryRun !== null ||
     gate.premergeContentRecheck !== null ||
     gate.requireFreshRebaseWindowMinutes !== null ||
+    gate.priorityEligibilityWindowMinutes !== null ||
     gate.staleBaseAheadByThreshold !== null ||
     gate.claMode !== null ||
     gate.claConsentPhrase !== null ||
@@ -2221,6 +2232,17 @@ export function experimentalConfigToJson(experimental: FocusManifestExperimental
   return out;
 }
 
+/** A NON-NEGATIVE integer, for a field where zero is a real setting rather than an absence -- e.g.
+ *  `gate.priorityEligibilityWindow: 0` deliberately turns the window off, which `normalizeOptionalPositiveInteger`
+ *  below would reject as invalid and silently replace with the shipped default (#9738). Bounded above so a typo
+ *  cannot set a window that never opens. */
+function normalizeOptionalNonNegativeInteger(value: JsonValue | undefined, field: string, warnings: string[], max: number): number | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= max) return value;
+  warnings.push(`Manifest field "${field}" must be a whole number between 0 and ${max}; ignoring it.`);
+  return null;
+}
+
 /** A positive INTEGER count (not a score/confidence) — e.g. `contentLane.maxAppendedEntries` counts discrete
  *  surfaces[] entries, so a fractional value (a likely typo) would render a nonsensical contributor-facing close
  *  message ("append between 1 and 2.5 entries"). Rejects fractional and non-positive values alike. */
@@ -2233,6 +2255,9 @@ function normalizeOptionalPositiveInteger(value: JsonValue | undefined, field: s
 
 const MAX_CONTRIBUTOR_OPEN_ITEM_CAP = 100;
 
+/** A day. Long enough for any deliberate cool-off, short enough that a typo cannot park work indefinitely. */
+const MAX_PRIORITY_ELIGIBILITY_WINDOW_MINUTES = 24 * 60;
+
 function normalizeOptionalContributorOpenItemCap(value: JsonValue | undefined, field: string, warnings: string[]): number | null {
   const parsed = normalizeOptionalPositiveInteger(value, field, warnings);
   if (parsed === null) return null;

scripts/check-docs-drift.ts

@@ -190,6 +190,7 @@ export const SETTINGS_ALIAS_MANIFEST: AliasManifestRow[] = [
   { field: "aiReviewOnMerge", aliases: ["onMerge"] },
   { field: "aiReviewReviewers", aliases: ["reviewers:"] },
   { field: "requireFreshRebaseWindowMinutes", aliases: ["requireFreshRebaseWindow"] },
+  { field: "priorityEligibilityWindowMinutes", aliases: ["priorityEligibilityWindow"] },
   { field: "sizeGateMaxFiles", aliases: ["maxFiles"] },
   { field: "sizeGateMaxLines", aliases: ["maxLines"] },
 ];

src/github/backfill.ts

@@ -3559,6 +3559,46 @@ export async function fetchLivePullRequestMergedAt(
   return result === undefined ? undefined : (result.data.merged_at ?? null);
 }
 
+/**
+ * When a label FIRST landed on an issue, ISO-8601, or null when it never did / cannot be read (#9738).
+ *
+ * `first: N` on purpose: the eligibility window is anchored to the EARLIEST labeling so re-applying the label
+ * cannot reset the clock for anyone. GitHub returns timeline items chronologically, so the first LABELED_EVENT
+ * naming this label is the moment the issue became publicly valuable.
+ *
+ * Reads at most one page. A maintainer who has labeled and unlabeled an issue more times than that has an
+ * issue whose history is not what this rule is for, and a null here FAILS OPEN (no hold) rather than guessing.
+ */
+export async function fetchIssueLabelFirstAppliedAt(
+  env: Env,
+  repoFullName: string,
+  issueNumber: number,
+  labelName: string,
+  token: string | undefined,
+  admissionKey?: GitHubRateLimitAdmissionKey,
+): Promise<string | null> {
+  if (!token || !labelName) return null;
+  const { owner, name } = repoParts(repoFullName);
+  if (!owner || !name) return null;
+  const query = `query LoopOverIssueLabeledAt { repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { issue(number: ${issueNumber}) { timelineItems(first: 100, itemTypes: [LABELED_EVENT]) { nodes { __typename ... on LabeledEvent { createdAt label { name } } } } } } }`;
+  const result = await githubGraphQl<{
+    data?: {
+      repository?: {
+        issue?: { timelineItems?: { nodes?: Array<{ createdAt?: string | null; label?: { name?: string | null } | null } | null> | null } | null } | null;
+      } | null;
+    };
+    errors?: unknown[];
+  }>(env, query, token, admissionKey).catch(() => undefined);
+  if (result === undefined) return null;
+  if (Array.isArray(result.errors) && result.errors.length > 0) return null;
+  const wanted = labelName.toLowerCase();
+  for (const node of result.data?.repository?.issue?.timelineItems?.nodes ?? []) {
+    const label = node?.label?.name;
+    if (typeof label === "string" && label.toLowerCase() === wanted && typeof node?.createdAt === "string") return node.createdAt;
+  }
+  return null;
+}
+
 export type LinkedIssueClosureByPullRequestResult = "closed_by_pull_request" | "not_closed_by_pull_request" | "fetch_error";
 
 /** Verifies whether GitHub attributes this issue's closure to the specific PR, via GraphQL's `ClosedEvent.closer`

src/openapi/schemas.ts

@@ -4,6 +4,7 @@ import { AGENT_ACTION_CLASSES, AUTONOMY_LEVELS, FEASIBILITY_VERDICTS, PUBLIC_SUR
 // #9773: the request bodies these routes really accept, from the one place they are defined.
 import { checkBeforeStartSchema, slopRiskSchema, validateFocusManifestSchema, validateLinkedIssueSchema } from "@loopover/contract/api-requests";
 import { MAX_REVIEW_NAG_COOLDOWN_DAYS } from "../settings/agent-actions";
+import { MAX_PRIORITY_ELIGIBILITY_WINDOW_MINUTES } from "../review/priority-eligibility-window";
 import { MAX_CONTRIBUTOR_OPEN_ITEM_CAP } from "../types";
 import {
   MAX_FIND_OPPORTUNITIES_TARGETS,
@@ -759,6 +760,8 @@ export const RepositorySettingsSchema = z
     gateDryRun: z.boolean().optional(),
     premergeContentRecheck: z.boolean().optional(),
     requireFreshRebaseWindowMinutes: z.number().int().positive().nullable().optional(),
+    // #9738: non-negative, not positive -- 0 is the documented way to turn the window off.
+    priorityEligibilityWindowMinutes: z.number().int().min(0).max(MAX_PRIORITY_ELIGIBILITY_WINDOW_MINUTES).nullable().optional(),
     staleBaseAheadByThreshold: z.number().int().positive().nullable().optional(),
     mergeReadinessGateMode: z.enum(["off", "advisory", "block"]),
     manifestPolicyGateMode: z.enum(["off", "advisory", "block"]),

src/queue/processors.ts

@@ -106,6 +106,7 @@ import {
   backfillRepositorySegment,
   fetchAndStorePullRequestFilesForReview,
   fetchBaseAheadBy,
+  fetchIssueLabelFirstAppliedAt,
   fetchLinkedIssueFacts,
   fetchLiveBaseBranchAdvancedAt,
   invalidateCiStateCache,
@@ -192,6 +193,7 @@ import {
   type PullRequestFreshness,
 } from "../github/pr-freshness";
 import { DEFAULT_TYPE_LABELS, resolvePrTypeLabel } from "../settings/pr-type-label";
+import { DEFAULT_PRIORITY_ELIGIBILITY_WINDOW_MINUTES, resolvePriorityEligibilityHold } from "../review/priority-eligibility-window";
 import { fetchLinkedIssueLabelsForPropagation } from "../review/linked-issue-label-propagation-fetch";
 import { shouldPublishReviewCheck } from "../review/check-names";
 import { fetchPublicContributorProfile } from "../github/public";
@@ -2795,6 +2797,7 @@ function buildAgentMaintenancePlanInput(args: {
   linkedIssueRulesConfig: Awaited<ReturnType<typeof loadLinkedIssueHardRules>>;
   migrationCollisionHold: AgentActionPlanInput["migrationCollisionHold"];
   unlinkedIssueMatchHold: AgentActionPlanInput["unlinkedIssueMatchHold"];
+  priorityEligibilityHold: AgentActionPlanInput["priorityEligibilityHold"];
   aiReviewLowConfidenceHold: AgentActionPlanInput["aiReviewLowConfidenceHold"];
   unlinkedIssueMatchClose: AgentActionPlanInput["unlinkedIssueMatchClose"];
   liveMergeState: string | undefined;
@@ -2834,6 +2837,7 @@ function buildAgentMaintenancePlanInput(args: {
     linkedIssueRulesConfig,
     migrationCollisionHold,
     unlinkedIssueMatchHold,
+    priorityEligibilityHold,
     aiReviewLowConfidenceHold,
     unlinkedIssueMatchClose,
     liveMergeState,
@@ -2912,6 +2916,7 @@ function buildAgentMaintenancePlanInput(args: {
     },
     ...(migrationCollisionHold !== undefined ? { migrationCollisionHold } : {}),
     ...(unlinkedIssueMatchHold !== undefined ? { unlinkedIssueMatchHold } : {}),
+    ...(priorityEligibilityHold !== undefined ? { priorityEligibilityHold } : {}),
     ...(aiReviewLowConfidenceHold !== undefined ? { aiReviewLowConfidenceHold } : {}),
     ...(unlinkedIssueMatchClose !== undefined ? { unlinkedIssueMatchClose } : {}),
     manualReviewLockContentionResolved,
@@ -3452,6 +3457,24 @@ async function runAgentMaintenancePlanAndExecute(
         })
       : undefined;
   const unlinkedIssueMatchHold = unlinkedIssueMatchDisposition?.kind === "hold" ? unlinkedIssueMatchDisposition : undefined;
+
+  // Priority-issue eligibility window (#9738). A PR closing a `gittensor:priority` issue is gate-eligible
+  // only once the label has been publicly present for the configured window, so first-come pickup is fair to
+  // everyone watching the repo rather than to whoever was already looking. Resolved here (not in the planner)
+  // because it needs a GitHub read; the DECISION is the pure evaluator, unit-tested on its own.
+  //
+  // FAIL-OPEN throughout: a fetch that throws, a label that was never applied, or a timestamp we cannot parse
+  // all yield no hold. Holding a contributor's PR on a fact we could not read is a penalty for our own gap.
+  const priorityEligibilityHold = await resolvePriorityEligibilityHold({
+    env,
+    repoFullName,
+    linkedIssues: pr.linkedIssues,
+    prCreatedAt: pr.createdAt ?? null,
+    windowMinutes: settings.priorityEligibilityWindowMinutes ?? DEFAULT_PRIORITY_ELIGIBILITY_WINDOW_MINUTES,
+    priorityLabel: settings.typeLabels?.priority ?? DEFAULT_TYPE_LABELS.priority,
+    token: ciToken,
+    fetchLabeledAt: (repo, issueNumber, label) => fetchIssueLabelFirstAppliedAt(env, repo, issueNumber, label, ciToken),
+  }).catch(() => undefined);
   const unlinkedIssueMatchClose = unlinkedIssueMatchDisposition?.kind === "close" ? unlinkedIssueMatchDisposition : undefined;
 
   // Contributor blacklist (#1425): resolve whether the PR author is on the repo's blacklist (the shared/global
@@ -3653,6 +3676,7 @@ async function runAgentMaintenancePlanAndExecute(
       linkedIssueRulesConfig,
       migrationCollisionHold,
       unlinkedIssueMatchHold,
+      priorityEligibilityHold,
       aiReviewLowConfidenceHold: aiReviewLowConfidenceHold ?? aiReviewSalvageableHold,
       unlinkedIssueMatchClose,
       liveMergeState,