feat(gate): force a fresh rebase + CI recheck immediately before merge when base has advanced

The update_branch action (which merges the current base into head and
would naturally re-trigger CI on a truly-rebased branch) only fired
when liveMergeState === "behind" inside the review-gating pass, not
immediately before the merge action itself. The merge decision's own
gate treats GitHub's mergeable_state as the sole base-freshness
signal, and mergeable_state only detects git-level TEXTUAL conflicts
-- a base that has advanced with a new, non-conflicting sibling commit
(e.g. a second PR's distinct-but-colliding migration file) still reads
clean. So a PR sitting green + approved + clean gets merged without
ever being forced through a fresh rebase-and-CI-recheck cycle against
whatever landed on the base moments earlier from a concurrent merge.

Added a new config-driven gate.requireFreshRebaseWindow setting
(minutes, off by default) wired through the full config-as-code chain:
migration 0093, Drizzle schema, RepositorySettings type, the DB
round-trip in repositories.ts (default/row-mapping/insert/update),
focus-manifest.ts's gate config parse/serialize/resolve, the OpenAPI
schema, and .gittensory.yml.example docs.

The base-freshness check itself lives in runAgentMaintenancePlanAndExecute,
immediately before planAgentMaintenanceActions is called with
merge-eligible inputs: a new fetchLiveBaseBranchAdvancedAt (backfill.ts)
reads the base branch's live tip-commit timestamp via GET /commits/{ref}.
When it landed within the configured window, maybeForceFreshRebase
forces an update_branch through the SAME action class/write-permission/
dry-run/kill-switch stack prReadyForReview's own BEHIND-branch path
already uses -- not a new action class, just a new trigger condition.
A bounded retry cap (3 attempts, keyed per head SHA in the transient
cache, mirroring ciPendingDeferStuck's pattern) prevents a fast-moving
base from live-locking the PR; past the cap it falls through to a
normal merge with an audit trail. Every failure mode (unreadable base
commit, cap reached, forced action not authorized) fails open to
today's merge behavior.

Off by default -- zero behavior change for any repo that hasn't opted
in, and the new live GitHub read only fires when a repo has explicitly
configured the window AND the PR is otherwise merge-mechanically-ready.

Tests: DB round-trip in data-spine.test.ts, full gate.requireFreshRebaseWindow
parse/round-trip/resolve coverage in focus-manifest.test.ts, and 6 new
end-to-end queue.test.ts scenarios covering a normal merge, a forced
rebase, the off-by-default path, the bounded-retry fallback, an
unreadable base commit, and an unauthorized forced action -- each
driving the real processJob path and asserting on audit_events.
100% branch coverage on the new code.

Closes #2552

Author: JSONbored

.gittensory.yml.example

@@ -183,6 +183,15 @@ gate:
   # PR, so it is opt-in rather than a new default.
   premergeContentRecheck: false
 
+  # Force-rebase-before-merge window in minutes (#2552, anti-race). When the base branch has advanced within
+  # this many minutes of the actual merge-decision moment, an agent-driven merge forces an update_branch +
+  # fresh CI recheck cycle before merging, instead of trusting a mergeable_state: clean read that may already
+  # be stale relative to a sibling commit that just landed on the base. A bounded retry cap prevents a
+  # fast-moving base from live-locking the PR — after a few forced attempts it falls through to a normal
+  # merge with an audit note. Positive integer (minutes), or omit/null. Default: null (never force).
+  # DB-backed (dashboard-settable too); this overrides the stored value.
+  requireFreshRebaseWindow: 10
+
   # AI maintainer review. Opt-in; the AI capabilities are switched on at the
   # deployment level.
   aiReview:

apps/gittensory-ui/public/openapi.json

@@ -8682,6 +8682,12 @@
           },
           "badgeEnabled": {
             "type": "boolean"
+          },
+          "requireFreshRebaseWindowMinutes": {
+            "type": "integer",
+            "nullable": true,
+            "minimum": 0,
+            "exclusiveMinimum": true
           }
         },
         "required": [

migrations/0093_gate_require_fresh_rebase_window.sql

@@ -0,0 +1,5 @@
+-- Force-rebase-before-merge gate (#2552): optional per-repo window (minutes). NULL (the default) means the
+-- gate never forces a rebase -- byte-identical behavior for every existing row. When set, an agent-driven
+-- merge whose base branch advanced within this window forces an update_branch + fresh CI recheck before
+-- merging, instead of trusting a mergeable_state: clean read that may already be stale relative to the base.
+ALTER TABLE repository_settings ADD COLUMN require_fresh_rebase_window_minutes INTEGER;

src/db/repositories.ts

@@ -510,6 +510,7 @@ export async function getRepositorySettings(env: Env, fullName: string): Promise
       reviewNagCooldownDays: 5,
       reviewNagLabel: "review-nag-cooldown",
       autoCloseExemptLogins: [],
+      requireFreshRebaseWindowMinutes: null,
     };
   }
   return {
@@ -562,6 +563,7 @@ export async function getRepositorySettings(env: Env, fullName: string): Promise
     reviewNagCooldownDays: normalizePositiveIntWithDefault(row.reviewNagCooldownDays, 5),
     reviewNagLabel: row.reviewNagLabel,
     autoCloseExemptLogins: parseAutoCloseExemptLogins(row.autoCloseExemptLoginsJson),
+    requireFreshRebaseWindowMinutes: normalizeOpenItemCap(row.requireFreshRebaseWindowMinutes),
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };
@@ -646,6 +648,7 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
     reviewNagCooldownDays: normalizePositiveIntWithDefault(settings.reviewNagCooldownDays, 5),
     reviewNagLabel: settings.reviewNagLabel ?? "review-nag-cooldown",
     autoCloseExemptLogins: normalizeAutoCloseExemptLogins(settings.autoCloseExemptLogins).logins,
+    requireFreshRebaseWindowMinutes: normalizeOpenItemCap(settings.requireFreshRebaseWindowMinutes),
   };
   const db = getDb(env.DB);
   await db
@@ -700,6 +703,7 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
       reviewNagCooldownDays: resolved.reviewNagCooldownDays,
       reviewNagLabel: resolved.reviewNagLabel,
       autoCloseExemptLoginsJson: jsonString(resolved.autoCloseExemptLogins),
+      requireFreshRebaseWindowMinutes: resolved.requireFreshRebaseWindowMinutes,
       updatedAt: nowIso(),
     })
     .onConflictDoUpdate({
@@ -755,6 +759,7 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
         reviewNagCooldownDays: resolved.reviewNagCooldownDays,
         reviewNagLabel: resolved.reviewNagLabel,
         autoCloseExemptLoginsJson: jsonString(resolved.autoCloseExemptLogins),
+        requireFreshRebaseWindowMinutes: resolved.requireFreshRebaseWindowMinutes,
         updatedAt: nowIso(),
       },
     });

src/db/schema.ts

@@ -99,6 +99,9 @@ export const repositorySettings = sqliteTable("repository_settings", {
   reviewNagLabel: text("review_nag_label").notNull().default("review-nag-cooldown"),
   // Shared repo-scoped exemption list (#2463): a JSON array of GitHub logins.
   autoCloseExemptLoginsJson: text("auto_close_exempt_logins_json").notNull().default("[]"),
+  // Force-rebase-before-merge window in minutes (#2552): null = never force (default). Enforcement lands in
+  // runAgentMaintenancePlanAndExecute, not here.
+  requireFreshRebaseWindowMinutes: integer("require_fresh_rebase_window_minutes"),
   createdAt: text("created_at").notNull().$defaultFn(() => nowIso()),
   updatedAt: text("updated_at").notNull().$defaultFn(() => nowIso()),
 });

src/github/backfill.ts

@@ -2637,6 +2637,32 @@ export async function fetchLivePullRequestMergeState(
   return result?.data.mergeable_state ?? undefined;
 }
 
+/**
+ * The base branch's LIVE tip-commit timestamp via REST `GET /commits/{ref}`, for the force-fresh-rebase gate
+ * (#2552): `mergeable_state` only detects git-level TEXTUAL conflicts, so a base that advanced with a new,
+ * non-conflicting sibling commit (e.g. a second PR's distinct-but-colliding migration file) still reads
+ * `clean`, letting a merge proceed on a decision that is stale relative to what just landed on the base.
+ * Comparing this timestamp against "now" lets the caller force a fresh rebase + CI recheck instead of
+ * trusting a `clean` read that predates the base's latest commit. Best-effort: a fetch error returns
+ * undefined (caller fails open — no forced rebase, same as today).
+ */
+export async function fetchLiveBaseBranchAdvancedAt(
+  env: Env,
+  repoFullName: string,
+  baseRef: string,
+  token: string | undefined,
+  admissionKey?: GitHubRateLimitAdmissionKey,
+): Promise<string | undefined> {
+  const result = await githubJsonWithHeaders<{ commit?: { committer?: { date?: string | null } | null } | null }>(
+    env,
+    repoFullName,
+    `/commits/${encodeURIComponent(baseRef)}`,
+    token,
+    githubRateLimitOptions(admissionKey),
+  ).catch(() => undefined);
+  return result?.data.commit?.committer?.date ?? undefined;
+}
+
 /** The PR's LIVE state ("open" / "closed") via REST `GET /pulls/{n}`. The stored open-PR cache lags GitHub, so a
  *  sibling closed/merged on GitHub can still read `open` locally; the duplicate-winner election (#dup-winner /
  *  audit #15) confirms a lower sibling's live state before treating this PR as a cluster loser. Best-effort:

src/openapi/schemas.ts

@@ -598,6 +598,7 @@ export const RepositorySettingsSchema = z
     sizeGateMode: z.enum(["off", "advisory", "block"]).optional(),
     gateDryRun: z.boolean().optional(),
     premergeContentRecheck: z.boolean().optional(),
+    requireFreshRebaseWindowMinutes: z.number().int().positive().nullable().optional(),
     mergeReadinessGateMode: z.enum(["off", "advisory", "block"]),
     manifestPolicyGateMode: z.enum(["off", "advisory", "block"]),
     selfAuthoredLinkedIssueGateMode: z.enum(["off", "advisory", "block"]),

src/queue/processors.ts

@@ -78,6 +78,7 @@ import {
   enqueueRepositoryOpenDataBackfill,
   fetchAndStorePullRequestFilesForReview,
   fetchLinkedIssueFacts,
+  fetchLiveBaseBranchAdvancedAt,
   fetchLiveCiAggregatePreferGraphQl,
   type LiveCiAggregate,
   fetchLiveIssueState,
@@ -1998,6 +1999,34 @@ async function runAgentMaintenancePlanAndExecute(
     }
   }
 
+  // #2552: force a fresh rebase + CI recheck when the base has advanced within the configured window,
+  // immediately before what would otherwise be an agent-driven merge — mergeable_state only detects
+  // git-level TEXTUAL conflicts, so a base that advanced with a new, non-conflicting sibling commit (e.g. a
+  // second PR's distinct-but-colliding migration file) still reads `clean`, on a decision that predates
+  // the base's latest commit. Only pays the extra live GitHub read when the repo opted in AND the PR is
+  // otherwise merge-mechanically-ready (mergeableClean) — nothing is gained checking a PR that isn't clean
+  // yet. A forced rebase's resulting `synchronize` webhook re-triggers a fresh evaluation on the new head,
+  // so this pass stops here rather than falling through to planAgentMaintenanceActions with stale inputs.
+  const requireFreshRebaseWindowMinutes = settings.requireFreshRebaseWindowMinutes;
+  if (
+    typeof requireFreshRebaseWindowMinutes === "number" &&
+    baseRef &&
+    (liveMergeState ?? pr.mergeableState) === "clean" &&
+    (await maybeForceFreshRebase(env, {
+      installationId,
+      repoFullName,
+      pr,
+      settings,
+      windowMinutes: requireFreshRebaseWindowMinutes,
+      baseRef,
+      token,
+      admissionKey,
+      deliveryId,
+    }))
+  ) {
+    return;
+  }
+
   const planned = planAgentMaintenanceActions({
     conclusion: gate.conclusion,
     blockerTitles: gate.blockers.map((blocker) => blocker.title),
@@ -2545,6 +2574,112 @@ async function ciPendingDeferStuck(
   }
 }
 
+// #2552: bounded-retry cap for the force-fresh-rebase gate, keyed per head SHA (a genuine new push resets the
+// count, same as ciPendingDeferStuck above) — without this, a fast-moving base could keep the freshness window
+// perpetually "hot" and never let the PR clear to a real merge. Past the cap, the gate falls through to a
+// normal merge decision (with an audit trail) rather than holding the PR hostage to base velocity.
+const MAX_FRESH_REBASE_FORCES = 3;
+function freshRebaseForceCountKey(repoFullName: string, prNumber: number, headSha: string): string {
+  return `fresh-rebase-forced:${repoFullName.toLowerCase()}#${prNumber}:${headSha}`;
+}
+
+/**
+ * #2552: when the repo has opted into `gate.requireFreshRebaseWindow` and the base branch's live tip commit
+ * landed within that window of NOW, force an `update_branch` (merges base into head, re-triggering CI on the
+ * rebased result — the SAME action class/write-permission/dry-run/kill-switch stack `prReadyForReview`'s
+ * BEHIND-branch path already uses, not a new one) immediately before what would otherwise be a merge, instead
+ * of trusting a `mergeable_state: clean` read that predates the base's latest commit. Returns true when it
+ * forced the rebase (the caller stops this pass — the resulting `synchronize` webhook re-triggers a fresh
+ * evaluation on the new head); false when the freshness check doesn't apply, the cap was already reached, or
+ * the forced action itself couldn't complete (not authorized / dry-run / transient failure) — in every false
+ * case the caller falls through to the normal merge decision, so this gate fails open to today's behavior.
+ */
+async function maybeForceFreshRebase(
+  env: Env,
+  args: {
+    installationId: number;
+    repoFullName: string;
+    pr: PullRequestRecord;
+    settings: RepositorySettings;
+    // Narrowed by the caller (typeof settings.requireFreshRebaseWindowMinutes === "number") -- re-deriving and
+    // re-checking the same nullable field here would just be an unreachable duplicate of that guard.
+    windowMinutes: number;
+    baseRef: string;
+    token: string | undefined;
+    admissionKey: GitHubRateLimitAdmissionKey | undefined;
+    deliveryId: string;
+  },
+): Promise<boolean> {
+  const { installationId, repoFullName, pr, settings, windowMinutes, baseRef, token, admissionKey, deliveryId } = args;
+  /* v8 ignore next -- structurally unreachable: the caller only invokes this after confirming
+   * (liveMergeState ?? pr.mergeableState) === "clean", which GitHub can never compute for a PR with no
+   * head commit; the null check is belt-and-suspenders against the field's optional TS type. */
+  if (!pr.headSha) return false;
+  const advancedAt = await fetchLiveBaseBranchAdvancedAt(env, repoFullName, baseRef, token, admissionKey);
+  if (!advancedAt) return false; // fail-open: unreadable base commit -> no forced rebase
+  const advancedAtMs = Date.parse(advancedAt);
+  if (!Number.isFinite(advancedAtMs) || Date.now() - advancedAtMs >= windowMinutes * 60_000) return false;
+
+  const countKey = freshRebaseForceCountKey(repoFullName, pr.number, pr.headSha);
+  const storedCount = Number(await getTransientKey(env, countKey));
+  const attempt = Number.isFinite(storedCount) && storedCount > 0 ? storedCount : 0;
+  if (attempt >= MAX_FRESH_REBASE_FORCES) {
+    await recordAuditEvent(env, {
+      eventType: "agent.action.fresh_rebase_window_cap_exceeded",
+      actor: "gittensory",
+      targetKey: `${repoFullName}#${pr.number}`,
+      outcome: "completed",
+      detail: `base advanced within the ${windowMinutes}m freshness window, but the ${MAX_FRESH_REBASE_FORCES}-attempt forced-rebase cap was already reached for this head SHA — falling through to a normal merge decision`,
+      metadata: { deliveryId, repoFullName, headSha: pr.headSha, windowMinutes },
+    }).catch(
+      /* v8 ignore next -- fail-safe: an audit write failure never blocks the caller's fallthrough */
+      () => undefined,
+    );
+    return false;
+  }
+
+  const autonomyLevel = resolveAutonomy(settings.autonomy, "update_branch");
+  const installation = await getInstallation(env, installationId);
+  const [outcome] = await executeAgentMaintenanceActions(
+    env,
+    {
+      installationId,
+      repoFullName,
+      pullNumber: pr.number,
+      headSha: pr.headSha,
+      autonomy: settings.autonomy,
+      agentPaused: settings.agentPaused,
+      agentDryRun: settings.agentDryRun,
+      /* v8 ignore next -- an installed-App PR webhook always carries an installation record; the null is defensive (mirrors runAgentMaintenancePlanAndExecute's own identical merge-time read). */
+      installationPermissions: installation?.permissions ?? null,
+      authorLogin: pr.authorLogin,
+    },
+    [
+      {
+        actionClass: "update_branch",
+        requiresApproval: autonomyRequiresApproval(autonomyLevel),
+        reason: `base branch advanced within the ${windowMinutes}m freshness window; forcing a fresh rebase + CI recheck before merge`,
+        expectedHeadSha: pr.headSha,
+      },
+    ],
+  );
+  if (outcome?.outcome !== "completed") return false;
+  const nextAttempt = attempt + 1;
+  await putTransientKey(env, countKey, String(nextAttempt), 24 * 3600);
+  await recordAuditEvent(env, {
+    eventType: "agent.action.forced_rebase_freshness",
+    actor: "gittensory",
+    targetKey: `${repoFullName}#${pr.number}`,
+    outcome: "completed",
+    detail: `forced update_branch (attempt ${nextAttempt}/${MAX_FRESH_REBASE_FORCES}) — base advanced within the ${windowMinutes}m freshness window`,
+    metadata: { deliveryId, repoFullName, headSha: pr.headSha, windowMinutes, attempt: nextAttempt },
+  }).catch(
+    /* v8 ignore next -- fail-safe: an audit write failure never blocks the caller */
+    () => undefined,
+  );
+  return true;
+}
+
 // One CI run fires MANY check_run (one per job) + check_suite completions. Re-reviewing on every one storms the
 // PR with duplicate reviews (and races the request_changes/approve dedup). reviewbot's CI_COALESCE_WINDOW parity:
 // re-review a given PR at most once per this window. The re-review always re-fetches the LIVE CI, so the window

src/signals/focus-manifest.ts

@@ -53,6 +53,13 @@ export type FocusManifestGateConfig = {
    *  costs one extra, uncached GitHub Trees-API call for any PR that touches migrations/**, so it is opt-in
    *  rather than a new default. */
   premergeContentRecheck: boolean | null;
+  /** `gate.requireFreshRebaseWindow` (#2552, anti-race): minutes. When the base branch has advanced within
+   *  this window of the actual merge-decision moment, an agent-driven merge forces an `update_branch` +
+   *  fresh CI recheck cycle before merging, instead of trusting a `mergeableState: clean` read that may
+   *  already be stale relative to a sibling commit that just landed on the base. null (unset) ⇒ never force
+   *  (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;
 };
 
 // The converged per-PR review features a self-host operator toggles PER-REPO under `features:` in the private
@@ -302,6 +309,7 @@ const EMPTY_GATE_CONFIG: FocusManifestGateConfig = {
   dryRun: null,
   firstTimeContributorGrace: null,
   premergeContentRecheck: null,
+  requireFreshRebaseWindowMinutes: null,
 };
 
 const EMPTY_FEATURES_CONFIG: FocusManifestFeaturesConfig = {
@@ -521,6 +529,7 @@ function parseGateConfig(value: JsonValue | undefined, warnings: string[]): Focu
     dryRun: normalizeOptionalBoolean(record.dryRun, "gate.dryRun", warnings),
     firstTimeContributorGrace: normalizeOptionalBoolean(record.firstTimeContributorGrace, "gate.firstTimeContributorGrace", warnings),
     premergeContentRecheck: normalizeOptionalBoolean(record.premergeContentRecheck, "gate.premergeContentRecheck", warnings),
+    requireFreshRebaseWindowMinutes: normalizeOptionalPositiveInteger(record.requireFreshRebaseWindow, "gate.requireFreshRebaseWindow", warnings),
   };
   // #2266: the flag is parsed, clamped, and threaded end-to-end, but the gate evaluator never reads it — a
   // maintainer who sets it to true believing it softens a blocker for newcomers gets no such effect. Surface
@@ -551,7 +560,8 @@ function parseGateConfig(value: JsonValue | undefined, warnings: string[]): Focu
     gate.selfAuthoredLinkedIssue !== null ||
     gate.dryRun !== null ||
     gate.firstTimeContributorGrace !== null ||
-    gate.premergeContentRecheck !== null;
+    gate.premergeContentRecheck !== null ||
+    gate.requireFreshRebaseWindowMinutes !== null;
   return gate;
 }
 
@@ -596,6 +606,7 @@ export function gateConfigToJson(gate: FocusManifestGateConfig): JsonValue {
   if (gate.dryRun !== null) out.dryRun = gate.dryRun;
   if (gate.firstTimeContributorGrace !== null) out.firstTimeContributorGrace = gate.firstTimeContributorGrace;
   if (gate.premergeContentRecheck !== null) out.premergeContentRecheck = gate.premergeContentRecheck;
+  if (gate.requireFreshRebaseWindowMinutes !== null) out.requireFreshRebaseWindow = gate.requireFreshRebaseWindowMinutes;
   return out;
 }
 
@@ -1208,6 +1219,7 @@ export function resolveEffectiveSettings(
   if (gate.dryRun !== null) effective.gateDryRun = gate.dryRun;
   if (gate.firstTimeContributorGrace !== null) effective.firstTimeContributorGrace = gate.firstTimeContributorGrace;
   if (gate.premergeContentRecheck !== null) effective.premergeContentRecheck = gate.premergeContentRecheck;
+  if (gate.requireFreshRebaseWindowMinutes !== null) effective.requireFreshRebaseWindowMinutes = gate.requireFreshRebaseWindowMinutes;
   // The dashboard "Require linked issue" toggle must not silently diverge from gate blocking: when the
   // boolean is on but linkedIssueGateMode is still off, treat it as a block requirement (#797).
   if (effective.requireLinkedIssue && effective.linkedIssueGateMode === "off") {

src/types.ts

@@ -659,6 +659,13 @@ export type RepositorySettings = {
    *  on top of the standing owner/admin/automation-bot exemption. Always populated by the DB layer (default
    *  `[]`); optional so existing settings fixtures/callers need not be touched. */
   autoCloseExemptLogins?: string[] | undefined;
+  /** Force-rebase-before-merge window in minutes (#2552, anti-race). When a base branch has advanced within
+   *  this many minutes of the actual merge-decision moment, an agent-driven merge forces an `update_branch` +
+   *  fresh CI recheck cycle first, rather than trusting a `mergeableState: clean` read that may already be
+   *  stale relative to a sibling commit that just landed on the base. `null`/undefined (default) = never
+   *  force -- a `mergeable_state: clean` read is trusted exactly as it is today. Layered like every other
+   *  settings field (`.gittensory.yml` `gate.requireFreshRebaseWindow` > DB > `null`). */
+  requireFreshRebaseWindowMinutes?: number | null | undefined;
   /** Agent-layer autonomy dial (#773): per-action-class level. Always populated by the DB layer (default
    *  `{}` = deny-by-default = "observe" for every class); optional so existing settings fixtures/callers
    *  need not be touched. The single source the action layer (#778) reads via `resolveAutonomy`. */