@humwick/server 0.0.0-stage → 0.130.0

package/src/workspace-auto-merge.ts

@@ -0,0 +1,1055 @@
+// Event-driven workspace merge-back engine (#237).
+//
+// The branch merge-back used to be driven entirely by a 2-min maintenance poll, so an
+// agent that marked ready waited an invisible up-to-2-min interval with no signal —
+// the "feels like a hung process" UX that was #235's root cause. This module makes the
+// land path EVENT-DRIVEN and demotes the poll to a self-healing backstop (the standard
+// controller pattern: react to events, periodically resync):
+//
+//   - on `ready`/`request-review`  → `scheduleRepoMerge(repoRoot)` (workspace-actions.ts)
+//   - on a merge command settling   → `scheduleRepoMerge(repoRoot)` (routes/commands.ts)
+//   - periodic backstop + runOnStart → `autoMergeCleanFastForwards` (maintenance.ts def)
+//
+// `landCandidates` is THE single per-candidate land engine; all three entry points
+// funnel through it so the land rule has one home. Dispatch is serialized by the
+// per-repo merge lease inside `requestWorkspaceMerge`, so a single pass dispatches at
+// most one merge per repo — the rest report `heldByLease` and are drained by the
+// on-settle re-trigger. That chain (schedule → dispatch → on-settle re-schedule → next)
+// IS the "sequential drain under the lease" the design calls for; no new concurrency
+// model. Different repos run on independent leases, so they land in parallel.
+
+import { fireAndForget } from "@humwick/sdk";
+import {
+  createActivityEventAsync,
+  emitWorkspaceChange,
+  getActiveMergePause,
+  getHostAsync,
+  getWorkspace,
+  listOrchestrators,
+  listWorkspaces,
+  patchWorkspaceMetadataAsync,
+  updateWorkspaceStatus,
+  workspaceLandBarrier, updateWorkspaceStatusAsync} from "./db";
+import { findLatestCommandByCorrelation } from "./commands-db";
+import { refreshPendingLandQueueLease } from "./db/commands-claim-admission";
+import { notifyBranchLandFailed } from "./branch-landed";
+import { resolveStewardIdentity } from "./steward-identity";
+import { emitCommandEvent } from "./command-events";
+import { superviseLandConflict } from "./workspace-conflict-resolver";
+import { routeNotification } from "./notification-router";
+import { renderTemplate } from "./prompt-resolver";
+import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
+import { emitWorkspaceTaskSemanticNotifications, markWorkspaceTasksCarryPending } from "./services/task-lifecycle";
+import { requestWorkspaceMerge, workspaceMergeOrchestrators } from "./workspace-merge";
+import { settleWorkspaceCommand } from "./workspace-command-settle";
+import { CLEAR_MERGE_NO_PROGRESS, MAX_NO_PROGRESS_MERGE_ATTEMPTS, mergeBackoffInputFingerprint, mergeBackoffRecoveredFromDirtyWorktree, mergeNoProgressCount, noteMergeNoProgress, sameMergeBackoffInputFingerprint, type MergeBackoffInputFingerprint } from "./workspace-merge-progress";
+import { applyMergeRetryCandidatePolicy } from "./workspace-merge-retry-policy";
+import { recoverTerminalMergeRetry } from "./workspace-land-retry";
+import { recordLandStopped } from "./workspace-land-stopped";
+
+import { workspaceActiveClaim } from "./workspace-claim";
+import { notifyWorkspaceHumanEscalation } from "./workspace-human-escalation";
+import { AUTO_LAND_CANDIDATE_STATUSES, DIRTY_WORKTREE_LAND_SKIP_REASON, LAND_IN_FLIGHT_STATUSES } from "./workspace-phase";
+import { runLandGateFailureWatchdog } from "./workspace-land-gate-watchdog";
+import { workspaceAwaitingLandAuthorization } from "./land-authorization";
+import { fetchHostMergePreview } from "./workspace-probe";
+import { reconcileLegacyLandingExecution } from "./services/legacy-landing-recovery";
+import type { Command, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMergePreview, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
+import { stewardFallbackTarget, workspaceAutoMergeEnabled } from "./config";
+import { DeadlineExceededError, withAbortDeadline } from "./async-deadline";
+
+const WORKSPACE_AUTO_MERGE_POLICIES = ["on-green", "on-approval", "manual"] as const;
+export { CLEAR_MERGE_NO_PROGRESS, MAX_NO_PROGRESS_MERGE_ATTEMPTS, mergeNoProgressCount, noteMergeNoProgress } from "./workspace-merge-progress";
+
+type AutoMergeRequestOptions = {
+  requestedBy: "auto-merge";
+  strategy?: WorkspaceMergeStrategy;
+  profileStrategy?: WorkspaceLandingPolicy;
+  autoMerge?: WorkspaceAutoMergePolicy;
+  reviewer?: string;
+};
+
+function workspaceLandStrategy(metadata: Record<string, unknown>): WorkspaceLandingPolicy | undefined {
+  const value = metadata.landStrategy;
+  return value === "direct" || value === "pr" ? value : undefined;
+}
+
+function workspaceAutoMergePolicy(metadata: Record<string, unknown>): WorkspaceAutoMergePolicy | undefined {
+  const value = metadata.autoMerge;
+  return typeof value === "string" && (WORKSPACE_AUTO_MERGE_POLICIES as readonly string[]).includes(value)
+    ? value as WorkspaceAutoMergePolicy
+    : undefined;
+}
+
+function workspaceReviewer(metadata: Record<string, unknown>): string | undefined {
+  const value = metadata.reviewer;
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function autoMergeRequestOptions(ws: WorkspaceRecord): AutoMergeRequestOptions {
+  const landStrategy = workspaceLandStrategy(ws.metadata);
+  const autoMerge = workspaceAutoMergePolicy(ws.metadata);
+  const reviewer = workspaceReviewer(ws.metadata);
+  return {
+    requestedBy: "auto-merge",
+    ...(landStrategy ? { profileStrategy: landStrategy } : {}),
+    ...(autoMerge ? { autoMerge } : {}),
+    ...(reviewer ? { reviewer } : {}),
+  };
+}
+
+// Don't re-escalate a backed-off lane more than once per this window.
+const NO_PROGRESS_ESCALATION_COOLDOWN_MS = 30 * 60 * 1000;
+export const AUTO_MERGE_ERROR_BACKOFF_MS = 3_000;
+export const AUTO_MERGE_WATCHDOG_STALE_MS = 5 * 60 * 1000;
+export const IN_FLIGHT_WORKSPACE_WATCHDOG_AGE_MS = 20 * 60 * 1000;
+// #2232 — hard per-cycle deadline for one `autoMergeForRepo` dispatch cycle. Deliberately BELOW
+// AUTO_MERGE_WATCHDOG_STALE_MS so a wedged cycle self-terminates and releases its repo lane before the
+// watchdog even has to consider it; the watchdog force-restart below is the second layer, not the first.
+// Sized well above a healthy sweep (per-candidate host preview 8s, reservation 40s, all already bounded)
+// — and an over-tight deadline costs only re-probing, never lost work: the rows stay landable and the
+// next cycle (event trigger, watchdog, or the ~10-min backstop) re-sweeps them.
+export const AUTO_MERGE_CYCLE_DEADLINE_MS = 4 * 60 * 1000;
+// #2232 — how many multiples of the staleness threshold a repo lane must sit wedged (with a run state
+// still in the map) before the watchdog stops politely flagging a rerun and FORCE-replaces the run.
+export const AUTO_MERGE_WATCHDOG_FORCE_RESTART_FACTOR = 2;
+
+const TERMINAL_COMMAND_STATUSES = new Set(["succeeded", "failed", "timed_out", "rejected", "canceled"]);
+
+// Surface a lane auto-merge can't advance (#638): wake the repo steward (if enabled) and
+// route a stranded-escalation notice to the configured fallback / workspace owner, so a
+// no-progress lane raises attention instead of churning silently. Cooldown-guarded so a
+// persistently-stuck row isn't re-escalated every sweep.
+// #1953 RC1 — `_tip` is retained for call-site compatibility but no longer consumed: the branch tip
+// only mattered for the steward-handoff watchdog re-arm, and a no-progress backoff no longer hands
+// off to a steward (it escalates to the coordinator instead).
+async function escalateNoProgressMerge(ws: WorkspaceRecord, _tip?: string): Promise<void> {
+  const meta = ws.metadata as Record<string, unknown>;
+  await recordLandStopped(ws.id, typeof meta.mergeRetryHeadMismatchAt === "number" ? "head-moved" : typeof meta.mergeRetryExhaustedAt === "number" ? "retry-exhausted" : "no-progress", typeof meta.mergeError === "string" ? meta.mergeError : undefined);
+  if (typeof meta.mergeRetryHeadMismatchAt === "number" && typeof meta.autoMergeBackedOffAt === "number") return;
+  const lastEscalated = typeof meta.autoMergeBackedOffAt === "number" ? meta.autoMergeBackedOffAt : 0;
+  if (lastEscalated && Date.now() - lastEscalated < NO_PROGRESS_ESCALATION_COOLDOWN_MS) return;
+  const mergeError = typeof meta.mergeError === "string" && meta.mergeError ? meta.mergeError : "merge made no progress";
+  const { coordinatorAgentId } = resolveStewardIdentity(ws);
+  const fallback = stewardFallbackTarget();
+  const recipients = [...new Set([coordinatorAgentId, fallback, ws.ownerAgentId].filter((r): r is string => Boolean(r)))];
+  const subject = "Workspace can't auto-land — needs attention";
+  const body = renderTemplate("steward.merge-stall", {
+    wsId: ws.id, branch: `\`${ws.branch ?? ws.id}\``,
+    repoRoot: ws.repoRoot,
+    attempts: String(MAX_NO_PROGRESS_MERGE_ATTEMPTS),
+    mergeError,
+    baseRef: ws.baseRef ?? "base",
+  });
+  const payload = { kind: "workspace.auto-merge-stuck", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: ws.baseRef, attempts: MAX_NO_PROGRESS_MERGE_ATTEMPTS, reason: mergeError };
+  let escalated = false;
+  if (recipients.length) {
+    notifyBranchLandFailed({ workspace: ws,
+      commandId: typeof meta.mergeCommandId === "string" ? meta.mergeCommandId : undefined,
+      recipients,
+      reason: `auto-merge backed off after ${MAX_NO_PROGRESS_MERGE_ATTEMPTS} no-progress attempts (${mergeError})`,
+    });
+    escalated = true;
+  } else {
+    const human = notifyWorkspaceHumanEscalation({ subject, body, payload, source: "workspace-auto-merge" });
+    escalated = human.accepted;
+    if (!human.accepted) {
+      console.warn(`[workspace-auto-merge] no-progress escalation for ${ws.id} had zero agent recipients and no human channel: ${human.reason ?? "unknown reason"}`);
+    }
+  }
+  // A metadata patch is silent, so push the owner's amber land ring explicitly (#2983).
+  if (escalated) emitWorkspaceChange(await patchWorkspaceMetadataAsync(ws.id, { autoMergeBackedOffAt: Date.now() }));
+  await createActivityEventAsync({
+    clientId: `workspace-auto-merge-backoff-${ws.id}-${Date.now()}`,
+    kind: "state",
+    title: "Auto-merge backed off (no progress)",
+    body: `${ws.branch ?? ws.id} → ${ws.baseRef ?? "base"} failed to land ${MAX_NO_PROGRESS_MERGE_ATTEMPTS}× without progress — stopping the merge loop (${mergeError})`,
+    meta: ws.branch ?? ws.id,
+    icon: "ti-alert-octagon",
+    view: "orchestrators",
+    metadata: { source: "server", maintenanceJobId: "workspace-auto-merge", workspaceId: ws.id, attempts: MAX_NO_PROGRESS_MERGE_ATTEMPTS },
+  });
+}
+
+async function notifyProtectedTipRestore(ws: WorkspaceRecord, preview: WorkspaceMergePreview): Promise<{ ok: boolean; stale?: boolean }> {
+  const discardedRef = preview.protectedTipDiscardedRef;
+  const discardedHead = preview.protectedTipDiscardedHead;
+  if (!discardedRef || !discardedHead) return { ok: true };
+  // #1456 — durably mark the workspace + every bound Task `carry-pending` the moment the revert is
+  // reported. Authoritative state written here-and-now (multi-host-safe, no later git read), so a task
+  // whose delivered tip was discarded CANNOT reach landed-on-main by any land path until the carry is
+  // explicitly confirmed. Returns ok=false if it could NOT durably record the obligation — the caller
+  // fails closed on that (withholds the steward hand-off) rather than risk a silent divergent land.
+  const carry = markWorkspaceTasksCarryPending(ws, discardedHead);
+  const body = `Workspace \`${ws.branch ?? ws.id}\` restored protected tip \`${preview.protectedTip?.slice(0, 12) ?? "unknown"}\`; discarded HEAD \`${discardedHead.slice(0, 12)}\` was preserved at \`${discardedRef}\`.`;
+  await createActivityEventAsync({
+    clientId: `workspace-protected-tip-restore-${ws.id}-${Date.now()}`,
+    kind: "state",
+    title: "Protected workspace tip restored",
+    body,
+    meta: ws.branch ?? ws.id,
+    icon: "ti-shield",
+    view: "orchestrators",
+    metadata: { source: "server", maintenanceJobId: "workspace-auto-merge", workspaceId: ws.id, protectedTip: preview.protectedTip, discardedHead, discardedRef },
+  });
+  // #1912 C3 — the activity write yielded. Do not send a land-path notification using a row a
+  // concurrent reconcile/stop has retired, repointed, or reassigned while the write was pending.
+  const current = getWorkspace(ws.id); if (!current || current.status !== ws.status || current.ownerAgentId !== ws.ownerAgentId) return { ok: carry.ok, stale: true };
+  const { coordinatorAgentId } = resolveStewardIdentity(current);
+  const recipients = [...new Set([coordinatorAgentId, current.ownerAgentId].filter((r): r is string => Boolean(r)))];
+  if (recipients.length) {
+    routeNotification({
+      type: "workspace.land_gate_warning",
+      scope: { workspaceId: current.id, repoRoot: current.repoRoot, author: current.ownerAgentId, parent: coordinatorAgentId ?? undefined },
+      recipients,
+      message: {
+        subject: "Workspace protected tip restored",
+        body,
+        payload: { kind: "workspace.protected-tip-restore", workspaceId: current.id, repoRoot: current.repoRoot, branch: current.branch, protectedTip: preview.protectedTip, discardedHead, discardedRef },
+      },
+    });
+  }
+  return { ok: carry.ok };
+}
+
+interface LandSweepResult {
+  scanned: number;
+  merged: string[];
+  heldByLease: string[];
+  heldByClaim: string[];
+  heldByPause: string[];
+  heldAwaitingApproval: string[];
+  previewUnavailable: string[];
+  dirtyWorktree: string[];
+  backedOff: string[];
+  leftForSteward: string[];
+  wokeStewards: string[];
+  // #1473 round-3 F3 — candidates whose land-authorization is stale: the live branch head has moved
+  // past the delivered tip it was authorized for (walked-back + re-pushed unreviewed work), so the
+  // dispatch is withheld rather than re-landing the branch on that stale authorization.
+  staleAuthorization: string[];
+}
+
+function emptyLandSweep(): LandSweepResult {
+  return { scanned: 0, merged: [], heldByLease: [], heldByClaim: [], heldByPause: [], heldAwaitingApproval: [], previewUnavailable: [], dirtyWorktree: [], backedOff: [], leftForSteward: [], wokeStewards: [], staleAuthorization: [] };
+}
+
+function mergeInputFingerprint(ws: WorkspaceRecord, preview: WorkspaceMergePreview): MergeBackoffInputFingerprint {
+  const meta = ws.metadata as Record<string, unknown>;
+  const conflictScanBaseSha = typeof meta.conflictScanBaseSha === "string" ? meta.conflictScanBaseSha : undefined;
+  const previewUsesRemoteBase = typeof preview.baseRef === "string"
+    && (preview.baseRef.startsWith("origin/") || preview.baseRef.startsWith("refs/remotes/origin/"));
+  return {
+    headSha: preview.headSha ?? null,
+    protectedTipSha: preview.protectedTip ?? null,
+    // #2608 gap 1: this must be a live observation, never the workspace row's creation-time baseSha.
+    baseSha: preview.baseSha ?? conflictScanBaseSha ?? null,
+    // The conflict scanner records a freshly-fetched remote base. A stale-base recovery preview
+    // also names origin/<base> directly, so it can supply the same signal without another fetch.
+    originBaseSha: conflictScanBaseSha ?? (previewUsesRemoteBase ? preview.baseSha ?? null : null),
+  };
+}
+
+async function fetchFirstUsableMergePreview(
+  ws: WorkspaceRecord,
+  orchestrators: ReturnType<typeof listOrchestrators>,
+): Promise<WorkspaceMergePreview | { available: false } | null> {
+  for (const orch of workspaceMergeOrchestrators(ws, orchestrators)) {
+    if (!orch.apiUrl) continue;
+    const preview = await fetchHostMergePreview(orch.apiUrl, ws, { protectTip: true });
+    if (!preview || (preview as { available?: false }).available === false) continue;
+    const p = preview as WorkspaceMergePreview;
+    if (p.error || p.missing) continue;
+    return p;
+  }
+  return null;
+}
+
+// Deterministic auto-land (Layer 0, #167/#207/#242): land fast-forwardable ready work
+// under the shared per-repo lease; moved-base/non-ff direct lands fail visibly and
+// re-enter the steward/coordinator loop. THE single per-candidate land engine — see module header.
+async function landCandidates(
+  candidates: WorkspaceRecord[],
+  orchestrators: ReturnType<typeof listOrchestrators>,
+  signal?: AbortSignal,
+  /** #1819 — out-param counting the leading candidates this sweep actually PROCESSED, so an aborted
+   *  caller can tell which repos it genuinely drained from which it merely started. */
+  progress?: { processed: number },
+): Promise<LandSweepResult> {
+  const merged: string[] = [], previewUnavailable: string[] = [];
+  const heldByLease: string[] = [], heldByClaim: string[] = [], heldByPause: string[] = [], heldAwaitingApproval: string[] = [], dirtyWorktree: string[] = [], backedOff: string[] = [], leftForSteward: string[] = [], wokeStewards: string[] = [], staleAuthorization: string[] = [];
+
+  for (const candidate of candidates) {
+    let ws = candidate;
+    // #1819 — genuinely cancellable: each candidate awaits a host merge preview, so an abort lands
+    // in that await and the sweep stops at the next workspace. The checkpoint is deliberately at the
+    // TOP of a candidate and nowhere else — below it a lane's no-progress counter, mergeError and
+    // dispatch are one bookkeeping unit, and bailing between them would strand a lane mid-decision.
+    if (signal?.aborted) break;
+    if (progress) progress.processed++;
+    if (isAwaitingReviewerApproval(ws)) { heldAwaitingApproval.push(ws.id); continue; }
+    // A claimed workspace is being validated by a steward — don't race it (#208).
+    if (workspaceActiveClaim(ws)) { heldByClaim.push(ws.id); continue; }
+    if (getActiveMergePause(ws.repoRoot, ws.baseRef ?? "main")) { heldByPause.push(ws.id); continue; }
+    // A capped lane gets one cheap SHA-only input comparison per sweep. The host preview is also
+    // the probe we reuse below when an input changed, so re-arming never causes a second fetch.
+    // Static inputs remain capped; HEAD, protected-tip pin, preview/conflict-scan base, or fresh
+    // origin/base movement clears the strike budget exactly once and lets this preview decide.
+    let wasBackedOff = mergeNoProgressCount(ws.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS;
+    const preview = await fetchFirstUsableMergePreview(ws, orchestrators);
+    if (!preview) {
+      if (wasBackedOff) {
+        backedOff.push(ws.id);
+        await escalateNoProgressMerge(ws);
+        continue;
+      }
+      previewUnavailable.push(ws.id);
+      // #1025 A5 — a lane whose preview is persistently unusable (owner host offline, the
+      // worktree path is gone, or every probe returns error/missing) used to exit here with
+      // ZERO side effects: no no-progress, no wake, no notify — a ready branch would strand
+      // silently forever. Give it the SAME no-progress/strand path as the unknown-merge-state
+      // lane so no status is escalation-blind: advance the loop-breaker, and once it crosses
+      // the cap, escalateNoProgressMerge fires the owner `landed-failure` wake + steward/
+      // coordinator escalation. A transient blip self-clears when a usable preview returns.
+      const held = await patchWorkspaceMetadataAsync(ws.id, {
+        ...noteMergeNoProgress(ws.metadata),
+        mergeError: "no online host returned a usable merge preview (owner offline, worktree missing, or probe error)",
+        lastPreviewUnavailableAt: Date.now(),
+      }) ?? ws;
+      if (mergeNoProgressCount(held.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+        backedOff.push(ws.id);
+        await escalateNoProgressMerge(held);
+      }
+      continue;
+    }
+    // A host preview is an awaited read of mutable workspace state. Re-load the row before any
+    // retry-policy decision or metadata write: an owner can hand the same HEAD off again while the
+    // preview is in flight, which clears the old retry incident and advances landRequestAttemptAt.
+    // The retry-policy writer CASes this exact snapshot, closing the smaller read→write window too.
+    const current = getWorkspace(ws.id);
+    if (!current
+      || current.repoRoot !== ws.repoRoot
+      || current.worktreePath !== ws.worktreePath
+      || (current.baseRef ?? "main") !== (ws.baseRef ?? "main")
+      || current.mode !== "isolated"
+      || !current.worktreePath
+      || !AUTO_LAND_CANDIDATE_STATUSES.has(current.status)
+      || workspaceLandBarrier(current).blocked
+      || workspaceAwaitingLandAuthorization(current)) continue;
+    ws = current;
+    if (isAwaitingReviewerApproval(ws)) { heldAwaitingApproval.push(ws.id); continue; }
+    if (workspaceActiveClaim(ws)) { heldByClaim.push(ws.id); continue; }
+    if (getActiveMergePause(ws.repoRoot, ws.baseRef ?? "main")) { heldByPause.push(ws.id); continue; }
+    wasBackedOff = mergeNoProgressCount(ws.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS;
+    const p = preview as WorkspaceMergePreview;
+    const inputFingerprint = mergeInputFingerprint(ws, p);
+    // Queue/no-verdict refusals are a retry incident scoped to cause + handed-off HEAD + land
+    // attempt. Keep every such row visible to this preview seam: it is the only place that can
+    // observe a new HEAD and re-arm immediately. A boolean candidate filter would permanently hide
+    // exhausted rows and could neither surface their exhaustion nor recover them after new work.
+    const retryPolicy = await applyMergeRetryCandidatePolicy(ws, p.headSha, inputFingerprint, escalateNoProgressMerge);
+    ws = retryPolicy.workspace;
+    if (retryPolicy.rearmed) wasBackedOff = false;
+    if (retryPolicy.exhausted) backedOff.push(ws.id);
+    if (retryPolicy.retryAt !== undefined) scheduleRepoMergeAt(ws.repoRoot, retryPolicy.retryAt);
+    if (retryPolicy.stop) continue;
+    const dirtyCount = p.dirtyCount ?? 0;
+    // #1695 — worktree cleanliness is not a SHA input: cleaning uncommitted files can leave
+    // HEAD and every base observation unchanged. Preserve that narrow self-heal alongside the
+    // fingerprint comparison; a still-dirty preview remains capped and cannot dispatch.
+    if (wasBackedOff) {
+      const stamped = mergeBackoffInputFingerprint(ws.metadata);
+      if (!mergeBackoffRecoveredFromDirtyWorktree(ws.metadata, p) && sameMergeBackoffInputFingerprint(stamped, inputFingerprint)) {
+        backedOff.push(ws.id);
+        await escalateNoProgressMerge(ws, p.headSha);
+        continue;
+      }
+      ws = await patchWorkspaceMetadataAsync(ws.id, {
+        ...CLEAR_MERGE_NO_PROGRESS,
+        autoMergeObservedInputFingerprint: inputFingerprint,
+      }) ?? ws;
+    } else {
+      ws = await patchWorkspaceMetadataAsync(ws.id, { autoMergeObservedInputFingerprint: inputFingerprint }) ?? ws;
+    }
+    // #1473 round-3 F3 — head-pin the authorization now that the live head is known. The candidacy
+    // filter (landableWorkspaces) only proved a land-authorizing delivery EXISTS for this workspace;
+    // here we additionally require the live branch head to still match the delivered tip it was
+    // authorized for. A branch that walked its land back (merge_planned → review_requested) and then
+    // re-pushed UNREVIEWED commits has a moved head, so withhold the dispatch AND the steward hand-off
+    // rather than re-landing the new head on the stale authorization.
+    if (workspaceAwaitingLandAuthorization(ws, { currentHead: p.headSha })) {
+      staleAuthorization.push(ws.id);
+      await recordLandStopped(ws.id, "stale-authorization", `branch head ${p.headSha ?? "?"} is not the delivered head; re-deliver it`);
+      continue;
+    }
+    // #1456 (BLOCKER 4) FAIL CLOSED — if the carry-pending obligation could NOT be durably recorded, do
+    // NOT hand this workspace to a steward (it could land a divergent lineage with no gate). Note
+    // no-progress + (on repeat) escalate; the next sweep re-attempts the mark, then the hand-off proceeds.
+    const protectedTipRestore = p.protectedTipRestored ? await notifyProtectedTipRestore(ws, p) : undefined; if (protectedTipRestore?.stale) continue;
+    if (protectedTipRestore && !protectedTipRestore.ok) {
+      const heldCarry = await patchWorkspaceMetadataAsync(ws.id, { ...noteMergeNoProgress(ws.metadata, inputFingerprint), mergeError: "#1456 fail-closed: could not durably record the carry-pending obligation for a moved-base protected-tip revert; withholding steward hand-off", lastCarryPendingMarkFailedAt: Date.now() }) ?? ws;
+      if (mergeNoProgressCount(heldCarry.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) { backedOff.push(ws.id); await escalateNoProgressMerge(heldCarry, p.headSha); }
+      continue;
+    }
+    if (p.reason === DIRTY_WORKTREE_LAND_SKIP_REASON || dirtyCount > 0) {
+      const mergeError = p.reason ?? DIRTY_WORKTREE_LAND_SKIP_REASON;
+      const heldDirty = await patchWorkspaceMetadataAsync(ws.id, {
+        ...noteMergeNoProgress(ws.metadata, inputFingerprint),
+        mergeError,
+        lastLandSkipReason: DIRTY_WORKTREE_LAND_SKIP_REASON,
+        lastLandSkipAt: Date.now(),
+      }) ?? ws;
+      dirtyWorktree.push(ws.id);
+      if (mergeNoProgressCount(heldDirty.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+        backedOff.push(ws.id);
+        await escalateNoProgressMerge(heldDirty, p.headSha);
+      }
+      continue;
+    } else if (wasBackedOff) {
+      // The changed fingerprint already cleared the strike budget before this single re-probe.
+      // Clear the stale verdict too; the current preview supplies the replacement verdict below.
+      await patchWorkspaceMetadataAsync(ws.id, {
+        mergeError: undefined,
+        lastLandSkipReason: undefined,
+        lastLandSkipAt: undefined,
+        lastMergeStateUnknownAt: undefined,
+      });
+    }
+
+    const ahead = p.unmergedAhead ?? p.ahead ?? 0;
+    const behind = p.behind ?? 0;
+    // Dispatch anything that won't conflict. If the effective strategy is direct and the
+    // branch is behind the current base, the host fails fast with a caller-facing
+    // direct-land error (#1184); PR strategy can still use the same preview.
+    // Only a predicted conflict (true) or unknown state (undefined) goes to the steward.
+    // A no-op (#230) — nothing to land (ahead=0, clean) — is also landable: the host
+    // resolves it to a terminal `merged` status, draining the queue instead of waking
+    // the steward every sweep for a workspace with no work.
+    // #1249/#1242 — a protected-tip restore means the base moved under this branch and the
+    // worker tip was reverted to avoid clobbering it. The re-preview (protectTip:false) then
+    // reports the RESTORED tip as cleanly landable (`conflict:false, ahead>0`), so `canLand`
+    // would be true and we'd RE-DISPATCH the exact land that just reverted — a silent loop that
+    // never escalates. Force a restore to be non-landable so it routes to the steward hand-off
+    // below (stop the loop + wake the steward) instead of re-dispatching.
+    const protectedTipRestored = p.protectedTipRestored === true;
+    const canLand = !protectedTipRestored && (p.noop === true || (p.conflict === false && ahead > 0));
+    if (!canLand) {
+      let handoffWorkspace = ws;
+      if (p.conflict !== true) {
+        // #2607 (d) — fail loud: when the host flags a stale local base, name the base and
+        // its staleness instead of the generic "merge state unknown". The stale-base detail
+        // carries the used base ref + SHAs, so the wedge is diagnosable from metadata alone.
+        const staleDetail = typeof p.baseStaleDetail === "string" && p.baseStaleDetail ? p.baseStaleDetail : undefined;
+        const staleRecoveredNote = p.baseStaleRecovered === true && p.baseRef
+          ? ` (re-evaluated against fresh remote base '${p.baseRef}'${p.baseSha ? ` @ ${String(p.baseSha).slice(0, 12)}` : ""})`
+          : "";
+        const mergeError = protectedTipRestored
+          ? "base moved under the branch; protected worker tip was restored (moved-base revert #1242) — re-dispatch would loop, handing off to a steward"
+          : p.protectedTipReachable === false
+          ? p.protectedTipError ?? "protected worker tip is no longer reachable"
+          : staleDetail
+          ? `stale local base: ${staleDetail}${staleRecoveredNote} (#2607)`
+          : p.reason ?? p.error ?? "merge state unknown";
+        handoffWorkspace = await patchWorkspaceMetadataAsync(ws.id, {
+          ...noteMergeNoProgress(ws.metadata, inputFingerprint),
+          mergeError,
+          lastMergeStateUnknownAt: Date.now(),
+          ...(p.headSha ? { lastUnknownHeadSha: p.headSha } : {}),
+          ...(p.baseSha ? { lastUnknownBaseSha: p.baseSha } : {}),
+        }) ?? ws;
+        if (mergeNoProgressCount(handoffWorkspace.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+          backedOff.push(ws.id);
+          await escalateNoProgressMerge(handoffWorkspace, p.headSha);
+          continue;
+        }
+      }
+      leftForSteward.push(ws.id);
+      // #1953 RC1 — wake a steward ONLY for a genuine git conflict. A protected-tip revert or a
+      // "merge state unknown"/unreachable-tip lane is not something a steward can rebase away; those
+      // now route through the no-progress escalation above (→ coordinator/owner/fallback), never a
+      // steward that would spawn, find nothing to resolve, and re-strand the row. #2704 — with no
+      // steward enabled, the conflict goes straight back to its owner.
+      if (p.conflict === true) {
+        const wake = await superviseLandConflict(handoffWorkspace, "conflict", { tip: p.headSha });
+        if (wake.ok) {
+          wokeStewards.push(wake.policy);
+        } else if ("cooldown" in wake && !wake.cooldown) {
+          // #1021 A1+A2 — a GENUINE wake failure (nothing spawned: host offline / provider
+          // error) now correctly yields !ok, so the conflict lane's loop-breaker advances and
+          // escalateNoProgressMerge becomes reachable. A cooldown means a steward WAS woken
+          // recently and is presumably working — that is not a failure, so don't count it (and
+          // don't mislabel the cooldown as a spawn failure in mergeError). Carry the real error.
+          const failedHandoff = await patchWorkspaceMetadataAsync(ws.id, {
+            ...noteMergeNoProgress(ws.metadata, inputFingerprint),
+            mergeError: wake.error ?? "cannot spawn steward on the workspace owning host",
+            lastStewardWakeFailedAt: Date.now(),
+          }) ?? ws;
+          if (mergeNoProgressCount(failedHandoff.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+            backedOff.push(ws.id);
+            await escalateNoProgressMerge(failedHandoff, p.headSha);
+            continue;
+          }
+        }
+      }
+      if (p.conflict === true || protectedTipRestored) {
+        emitWorkspaceTaskSemanticNotifications({
+          workspace: ws,
+          transition: "land-conflict",
+          actor: "workspace-auto-merge",
+          occurrenceKey: protectedTipRestored
+            ? `workspace-protected-tip-revert:${ws.id}:${p.baseRef ?? ws.baseRef ?? "base"}:${p.protectedTip ?? "?"}`
+            : `workspace-conflict:${ws.id}:${p.baseRef ?? ws.baseRef ?? "base"}:${p.ahead ?? "?"}:${p.behind ?? "?"}`,
+          outcome: { reason: protectedTipRestored ? "protected-tip revert" : "conflict", ahead: p.ahead, behind: p.behind, baseRef: p.baseRef },
+        });
+      }
+      continue;
+    }
+
+    // Honor per-spawn land metadata first (#421), then the operator's instance
+    // landing.strategy (#419-followup), through the shared resolver in requestWorkspaceMerge
+    // so auto-land and manual land cannot drift (#1184).
+    // #2608 gap 2 is deliberately not folded into this recovery: the row's baseRef is the durable
+    // target branch and baseSha is its fork anchor, while `origin/main` is a host-local evaluation
+    // ref. Persisting the latter over either field would change their meaning; the land executor
+    // resolves the current target tip again under the landing lease.
+    const result = await requestWorkspaceMerge(ws, { ...autoMergeRequestOptions(ws), ...(p.headSha ? { expectedHeadSha: p.headSha } : {}) });
+    if (!result.ok) {
+      // 409 = another merge holds this repo's lease this tick; the on-settle re-trigger
+      // (routes/commands.ts → scheduleRepoMerge) drains it once the lease frees.
+      heldByLease.push(ws.id);
+      continue;
+    }
+    emitCommandEvent(result.command, "command.requested");
+    merged.push(ws.id);
+    await createActivityEventAsync({
+      clientId: `workspace-auto-merge-${ws.id}-${Date.now()}`,
+      kind: "state",
+      title: p.noop ? "Workspace auto-resolving (no work to merge)" : behind > 0 ? "Workspace auto-merging (rebase)" : "Workspace auto-merging (clean fast-forward)",
+      body: p.noop
+        ? `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (nothing to land — resolving to merged)`
+        : `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead${behind > 0 ? `, ${behind} behind — rebasing` : ", clean"})`,
+      meta: ws.branch ?? ws.id,
+      icon: "ti-git-merge",
+      view: "orchestrators",
+      metadata: { source: "server", maintenanceJobId: "workspace-auto-merge", workspaceId: ws.id, commandId: result.command.id, ahead },
+    });
+  }
+
+  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldByPause, heldAwaitingApproval, previewUnavailable, dirtyWorktree, backedOff, leftForSteward, wokeStewards, staleAuthorization };
+}
+
+// Coalesced, fire-and-forget per-repo land trigger (see module header). A run already
+// in flight for the repo just flags a rerun, so concurrent readies don't fan out
+// redundant host probes. Errors are swallowed: the runOnStart backstop is the
+// self-healer for anything a dropped run strands.
+// #1473 — the scope a queued rerun must cover. `undefined` was previously overloaded to mean
+// BOTH "nothing pending" and "unfiltered full-repo sweep", so clearing the pending baseRef before
+// the active sweep made a coalesced same-base settle (and every error retry) silently widen to
+// unfiltered. The three states are now explicit: `none` = no rerun queued; `scoped` = rerun only
+// workspaces landing into this base; `unfiltered` = re-sweep every ready-to-land row in the repo.
+type PendingRerun =
+  | { kind: "none" }
+  | { kind: "scoped"; baseRef: string }
+  | { kind: "unfiltered" };
+
+const NO_PENDING_RERUN: PendingRerun = { kind: "none" };
+
+function pendingRerunFor(baseRef?: string): PendingRerun {
+  return baseRef ? { kind: "scoped", baseRef } : { kind: "unfiltered" };
+}
+
+// Widen two pending scopes into the narrowest scope that still covers BOTH — a coalescing race may
+// only over-sweep, never under-sweep (dropping a row that needs landing is the dangerous side).
+// Same-base coalescing stays scoped; a disagreement, or any unfiltered party, widens to unfiltered.
+function widenPendingRerun(a: PendingRerun, b: PendingRerun): PendingRerun {
+  if (a.kind === "none") return b;
+  if (b.kind === "none") return a;
+  if (a.kind === "unfiltered" || b.kind === "unfiltered") return { kind: "unfiltered" };
+  return a.baseRef === b.baseRef ? { kind: "scoped", baseRef: a.baseRef } : { kind: "unfiltered" };
+}
+
+type RepoMergeRunState = {
+  lastProgressAt: number;
+  pending: PendingRerun;
+  // #2232 — this run must never resume: its cycle blew the deadline, or the watchdog force-replaced it
+  // with a fresh loop. Checked at the loop's continue condition AND in its catch, so a wedged cycle that
+  // finally unblocks unwinds instead of running a second, concurrent sweep behind its replacement.
+  abandoned?: boolean;
+  // #2232 — the in-flight cycle's controller, so the deadline and the watchdog can both cancel it
+  // (a cooperative sweep stops at its next per-candidate checkpoint; a wedged await is abandoned).
+  abort?: AbortController;
+};
+
+const repoMergeRunning = new Map<string, RepoMergeRunState>();
+const repoMergeLastCompletedAt = new Map<string, number>();
+let autoMergeWatchdogStartedAt = Date.now();
+let autoMergeCycleDeadlineMs = AUTO_MERGE_CYCLE_DEADLINE_MS;
+
+/** Test-only (#2232): shrink the per-cycle deadline so a hung-cycle test needn't wait minutes. */
+export function __setAutoMergeCycleDeadlineForTests(ms?: number): void {
+  autoMergeCycleDeadlineMs = ms ?? AUTO_MERGE_CYCLE_DEADLINE_MS;
+}
+
+function errMessage(error: unknown): string {
+  if (error instanceof Error) return `${error.name}: ${error.message}`;
+  return String(error);
+}
+
+// #1473 — when `baseRef` is given, only workspaces landing INTO that same base are "affected"
+// by the just-settled merge (main moved under them); a workspace targeting a different base is
+// untouched and must not be re-probed/re-woken on every unrelated settle in the repo. Omitting
+// `baseRef` preserves the original unfiltered sweep (used by the ready/request-review trigger,
+// the watchdog restart, and the periodic `autoMergeCleanFastForwards` backstop).
+function landableWorkspaces(repoRoot?: string, baseRef?: string): WorkspaceRecord[] {
+  return listWorkspaces(repoRoot ? { repoRoot } : undefined).filter(
+    // #1482 — an explicitly landBlocked workspace is NEVER an auto-merge candidate, so it is
+    // never dispatched and never wakes a steward. Covers all three sweep triggers (event, backstop,
+    // watchdog) at this single selection filter.
+    // #1473 — nor is a workspace bound to a deliverable Task that has NOT authorized a land: a pushed
+    // `agent/*` branch in a ready-to-land status is not, by itself, a land authorization (a "HOLD" is
+    // coordinator convention only). Excluding it here keeps it out of BOTH the auto-land dispatch and
+    // the conflict→steward hand-off that landCandidates performs, at the SAME single selection filter.
+    (ws) => ws.mode === "isolated" && Boolean(ws.worktreePath) && AUTO_LAND_CANDIDATE_STATUSES.has(ws.status)
+      // #1482 + #2518 (MED 5 single resolver) — the ONE combined land barrier: a landBlocked
+      // (review/research) workspace or one bound to a review-held Task is NEVER an auto-merge
+      // candidate, so it is never dispatched and never wakes a steward (the held park leaves it
+      // `review_requested` with NO authorization; after the coordinator's clear the flag is off
+      // and the promoted delivery lands normally). Covers all three sweep triggers (event,
+      // backstop, watchdog) and the conflict→steward hand-off at this single selection filter.
+      && !workspaceLandBarrier(ws).blocked
+      // #1473 — nor is a workspace bound to a deliverable Task that has NOT authorized a land: a pushed
+      // `agent/*` branch in a ready-to-land status is not, by itself, a land authorization (a "HOLD" is
+      // coordinator convention only). Excluding it here keeps it out of BOTH the auto-land dispatch and
+      // the conflict→steward hand-off that landCandidates performs, at the SAME single selection filter.
+      && !workspaceAwaitingLandAuthorization(ws)
+      && (!baseRef || (ws.baseRef ?? "main") === baseRef),
+  );
+}
+
+// #2232 (review F2) — `owningState` is the run whose cycle produced this completion, and the stamp is
+// withheld unless that run still OWNS the repo lane. Without the identity guard a ZOMBIE cycle (deadline-
+// abandoned or watchdog force-replaced) that finishes its last candidate still satisfies the caller's
+// stamp gate, and writes its progress onto whatever `repoMergeRunning` holds — by then the REPLACEMENT's
+// state — resetting the live run's watchdog clock and delaying the next force-restart by up to the wedge
+// duration. Same identity check the lane release in `scheduleRepoMerge`'s `finally` already uses. Callers
+// with no owning run (the periodic backstop) pass nothing and stamp unconditionally, as before.
+function noteAutoMergeCycleCompleted(repoRoot: string, owningState?: RepoMergeRunState): void {
+  if (owningState && repoMergeRunning.get(repoRoot) !== owningState) return;
+  const completedAt = Date.now();
+  repoMergeLastCompletedAt.set(repoRoot, completedAt);
+  const state = repoMergeRunning.get(repoRoot);
+  if (state) state.lastProgressAt = completedAt;
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+const repoMergeWakes = new Map<string, { at: number; timer: ReturnType<typeof setTimeout> }>();
+
+function wakeRepoMerge(repoRoot: string): void {
+  repoMergeWakes.delete(repoRoot);
+  scheduleRepoMerge(repoRoot);
+}
+
+/** Wake the repo lane when a deferred retry's backoff ends, not on the next backstop sweep (#2965). */
+function scheduleRepoMergeAt(repoRoot: string, at: number): void {
+  const existing = repoMergeWakes.get(repoRoot);
+  if (existing && existing.at <= at) return;
+  if (existing) clearTimeout(existing.timer);
+  const timer = setTimeout(() => wakeRepoMerge(repoRoot), Math.max(0, at - Date.now()));
+  timer.unref?.();
+  repoMergeWakes.set(repoRoot, { at, timer });
+}
+
+/** Test-only (#2965): fire every armed backoff wake now, without waiting on the wall clock. */
+export function __fireRepoMergeWakesForTests(): Array<{ repoRoot: string; at: number }> {
+  const fired = [...repoMergeWakes].map(([repoRoot, wake]) => ({ repoRoot, at: wake.at }));
+  for (const { repoRoot } of fired) {
+    clearTimeout(repoMergeWakes.get(repoRoot)!.timer);
+    wakeRepoMerge(repoRoot);
+  }
+  return fired;
+}
+
+// #1473 — `baseRef`, when given, targets this trigger at only the workspaces landing into that
+// base (the one that actually moved), instead of re-sweeping every ready-to-land workspace in
+// the repo. Omit it for an unfiltered sweep (the ready/request-review trigger and watchdog
+// restart both do — those aren't reacting to a specific base moving).
+export function scheduleRepoMerge(repoRoot: string | undefined, baseRef?: string): void {
+  if (!repoRoot) return;
+  if (!workspaceAutoMergeEnabled()) return;
+  const incoming = pendingRerunFor(baseRef);
+  const existing = repoMergeRunning.get(repoRoot);
+  if (existing) {
+    existing.pending = widenPendingRerun(existing.pending, incoming);
+    return;
+  }
+  const state: RepoMergeRunState = { lastProgressAt: Date.now(), pending: incoming };
+  repoMergeRunning.set(repoRoot, state);
+  void fireAndForget(`[auto-merge] repo lane ${repoRoot}`, async () => {
+    let retriedAfterError = false;
+    try {
+      do {
+        // Capture the scope for THIS iteration and reset pending to `none` (not `undefined`), so a
+        // concurrent same-base settle arriving during the await queues a fresh scoped rerun instead
+        // of being read as an unfiltered one.
+        const active = state.pending;
+        state.pending = NO_PENDING_RERUN;
+        state.lastProgressAt = Date.now();
+        const runBaseRef = active.kind === "scoped" ? active.baseRef : undefined;
+        // #2232 — BOUND THE CYCLE. `autoMergeForRepo` can hang on an await that never settles or throws
+        // (see the module note below), and a hung cycle used to hold this repo's `repoMergeRunning` entry
+        // forever: every later trigger coalesced onto a loop that would never reach its next iteration, so
+        // the repo silently stopped dispatching ALL merges until a daemon restart. The race rejects within
+        // a tick of the deadline even though the awaited work never settles, which is what makes the
+        // `finally` below (the lane release) actually reachable.
+        const controller = new AbortController();
+        state.abort = controller;
+        try {
+          await withAbortDeadline(autoMergeForRepo(repoRoot, runBaseRef, controller.signal, state), autoMergeCycleDeadlineMs, controller,
+            { label: `auto-merge cycle for ${repoRoot}` });
+        } catch (err) {
+          // Force-replaced by the watchdog while we were wedged — the fresh loop owns this repo now.
+          if (state.abandoned) break;
+          if (err instanceof DeadlineExceededError) {
+            // #2232 — THE missing hang log. Pre-#2232 a hung cycle produced NO log line at all (it never
+            // threw, so the "cycle failed" warn below never fired) — the wedge was invisible in the daemon
+            // log and only showed up as merges silently not happening.
+            console.error(`[workspace-auto-merge] Repo auto-merge cycle for ${repoRoot} (${runBaseRef ?? "all bases"}) hung past its ${autoMergeCycleDeadlineMs}ms deadline — abandoning the cycle and releasing the repo lane so the next cycle can run`);
+            state.abandoned = true;
+            break;
+          }
+          console.warn(`[workspace-auto-merge] Repo auto-merge cycle failed for ${repoRoot}: ${errMessage(err)}`);
+          if (!retriedAfterError) {
+            retriedAfterError = true;
+            await sleep(AUTO_MERGE_ERROR_BACKOFF_MS);
+            // Retry the SAME scope that just failed, widened by anything that coalesced in during
+            // the failed attempt — never silently promote a scoped retry to a full-repo sweep.
+            state.pending = widenPendingRerun(state.pending, active);
+          }
+        }
+      } while (!state.abandoned && state.pending.kind !== "none");
+    } catch {
+      // Swallow — the periodic backstop (runOnStart + interval) is the self-healer.
+    } finally {
+      if (repoMergeRunning.get(repoRoot) === state) repoMergeRunning.delete(repoRoot);
+      // #2232 — an abandoned run must not swallow work that coalesced in while it was wedged: now that
+      // the lane is released, re-arm a FRESH loop for exactly that queued scope. Only those external
+      // arrivals are requeued — the abandoned cycle's OWN scope is re-covered by the watchdog and the
+      // periodic backstop, so a persistently wedged repo re-arms on their cadence instead of hot-looping.
+      if (state.abandoned && state.pending.kind !== "none") {
+        scheduleRepoMerge(repoRoot, state.pending.kind === "scoped" ? state.pending.baseRef : undefined);
+      }
+    }
+  });
+}
+
+export function resetRepoMergeSchedulerForTests(): void {
+  for (const wake of repoMergeWakes.values()) clearTimeout(wake.timer);
+  repoMergeWakes.clear();
+  repoMergeRunning.clear();
+  repoMergeLastCompletedAt.clear();
+  autoMergeWatchdogStartedAt = Date.now();
+  autoMergeCycleDeadlineMs = AUTO_MERGE_CYCLE_DEADLINE_MS;
+}
+
+function commandIsTerminal(command: Command | null): boolean {
+  return Boolean(command && TERMINAL_COMMAND_STATUSES.has(command.status));
+}
+
+function latestWorkspaceCommand(ws: WorkspaceRecord): Command | null {
+  const type = LAND_IN_FLIGHT_STATUSES.has(ws.status) ? "workspace.merge" : "workspace.cleanup";
+  return findLatestCommandByCorrelation(type, ws.id);
+}
+
+async function recoverAgedInFlightWorkspaces(now: number, signal?: AbortSignal): Promise<Record<string, unknown>> {
+  const oldEnough = (ws: WorkspaceRecord) => now - ws.updatedAt >= IN_FLIGHT_WORKSPACE_WATCHDOG_AGE_MS;
+  const orchestrators = listOrchestrators();
+  const recoveredMergePlanned: string[] = [], recoveredCleanupRequested: string[] = [], settledTerminal: string[] = [], stillActive: string[] = [];
+  // #2094 Fix A — merge_planned rows reclaimed FAST because their claiming executor is confirmed gone
+  // (a restart-orphaned merge), distinct from `recoveredMergePlanned` (aged terminal/missing recovery)
+  // and `stillActive` (a genuinely-running gate). Surfaced for operator visibility into the land-wedge.
+  const reclaimedOrphaned: string[] = [];
+  // #1993 — command ids the sweep force-terminalized because they were stuck non-terminal PAST their
+  // own execution lease (a `pending` workspace.merge to a still-online host that `expireCommands`
+  // never sweeps). Surfaced for operator visibility into the land-wedge recovery.
+  const expiredStaleCommands: string[] = [];
+  // #1830 re-review — a dedicated flag set ONLY at the break site, so the returned `aborted` field
+  // reports "the checkpoint actually fired" rather than "the signal happened to be aborted by the
+  // time the function returned" (true either way once a caller aborts, telling a caller nothing
+  // about whether any row was actually skipped).
+  let stoppedEarly = false;
+
+  for (const ws of listWorkspaces().filter((row) =>
+    row.mode === "isolated"
+    && Boolean(row.worktreePath)
+    && (LAND_IN_FLIGHT_STATUSES.has(row.status) || row.status === "cleanup_requested"),
+  )) {
+    // #1830 review F2 — PER-ROW CHECKPOINT (maintenance/jobs.ts:194-197's precedented shape): each
+    // iteration below is one atomic settle/status-write unit, so this is the only safe place to stop.
+    // Pre-#1830 this loop had no real await in it, so the job's `withTimeout` race (scheduler.ts) always
+    // saw an already-resolved promise and its deadline could never actually fire. Now `settleWorkspaceCommand`
+    // awaits the bounded async ancestry check (up to the 5s fetch + 2s rev-parse + 2x2s merge-base +
+    // escalation bound in git-process.ts, PER aged workspace), so a handful of stuck rows can genuinely
+    // overrun the job's deadline. Without this checkpoint the scheduler would time the run out and clear
+    // its DB lease while this loop kept running unseen underneath it, able to start a second overlapping
+    // pass over the same rows on the next tick (double-settling, double-incrementing no-progress counters).
+    if (signal?.aborted) { stoppedEarly = true; break; }
+    // #2094 Fix A — resolve the command up front: the executor-orphan fast-path (case C) needs it for a
+    // young merge_planned row the 20-min age gate would otherwise skip. Only a merge_planned row can be
+    // executor-orphaned, so a young cleanup_requested/non-merge row still pays NO command lookup (the
+    // pre-#2094 cost) — fetch only when the row is old enough for the existing recovery OR could be an orphan.
+    let command = (LAND_IN_FLIGHT_STATUSES.has(ws.status) || oldEnough(ws)) ? latestWorkspaceCommand(ws) : null;
+    if (command?.status === "pending" && command.type === "workspace.merge") {
+      if (refreshPendingLandQueueLease(command.id, now)) {
+        stillActive.push(ws.id);
+        continue;
+      }
+      const hostId = orchestrators.find((o) => o.agentId === command?.target)?.hostId;
+      if (hostId && (await getHostAsync(hostId))?.policy.gatesEnabled === false) {
+        stillActive.push(ws.id);
+        continue;
+      }
+    }
+    // #2141 — re-enter terminal legacy misses through review_requested so the normal lane re-previews origin.
+    if (await recoverTerminalMergeRetry(ws, command, now, { update: updateWorkspaceStatus, schedule: scheduleRepoMerge, escalate: escalateNoProgressMerge })) continue;
+    // #2094 Fix A — case C: a claimed merge whose executor PROCESS a restart replaced, or whose execution
+    // journaled a verdict Relay never received (#2935), is reconciled in seconds, not after its lease.
+    // Its terminal then takes the ordinary settle below; a no-verdict restart kill retries (#2965).
+    if (LAND_IN_FLIGHT_STATUSES.has(ws.status) && (command?.status === "accepted" || command?.status === "running")) {
+      const reconciled = await reconcileLegacyLandingExecution(command, orchestrators, now);
+      if (reconciled && commandIsTerminal(reconciled)) {
+        command = reconciled;
+        reclaimedOrphaned.push(ws.id);
+      }
+    }
+    // Shield young dispatch/withdraw windows; aged rows still need crash recovery (#2859).
+    if (!oldEnough(ws) && command?.type === "workspace.merge"
+      && ((typeof ws.metadata.lastWorkspaceActionAt === "number" && command.createdAt < ws.metadata.lastWorkspaceActionAt)
+        || (command.status === "canceled" && command.error?.startsWith("land withdrawn:")))) { stillActive.push(ws.id); continue; }
+    // Failed merges settle immediately: conflict scans can keep updatedAt fresh forever (#2859).
+    if (!oldEnough(ws) && !(command?.type === "workspace.merge" && command.status !== "succeeded" && commandIsTerminal(command))) continue;
+    if (command && !commandIsTerminal(command)) {
+      // #1993 (managed-land wedge) — a non-terminal command STILL within its execution lease is
+      // genuinely in flight; leave it alone (a real ci-land-full runs well inside the merge command
+      // TTL). But one PAST its `expiresAt` is a STUCK merge command that `expireCommands` cannot
+      // reach: a `pending` workspace.merge to a still-ONLINE host is never target-gone-swept
+      // (#930/#953 keep pending commands for a busy host to poll), and its accepted/running sibling
+      // would already have been swept — so a pending-forever command left this row pinned at
+      // merge_planned with NO bounded recovery. auto-merge's landable filter excludes merge_planned,
+      // and this watchdog used to re-file such a row under `stillActive` on EVERY sweep, so it stayed
+      // wedged (status merge_planned, stale mergeCommandId/mergeError, autoMergeNoProgressCount stuck
+      // at 0) until it was couriered through a fresh workspace. Terminalize the stuck command exactly
+      // as the command-expiration sweep would (executor-authorized pending→timed_out), then fall
+      // through to settle + recovery below so the lane returns to review_requested, takes a
+      // no-progress strike, and re-dispatches a FRESH gate.
+      const pastLease = typeof command.expiresAt === "number" && command.expiresAt <= now;
+      if (!pastLease) {
+        stillActive.push(ws.id);
+        continue;
+      }
+      const reconciled = await reconcileLegacyLandingExecution(command, orchestrators, now);
+      if (!reconciled) {
+        stillActive.push(ws.id);
+        continue;
+      }
+      command = reconciled;
+      expiredStaleCommands.push(command.id);
+    }
+    let settlementFailure: unknown;
+    if (command) {
+      // A malformed/forward-incompatible terminal payload must be isolated to this row. Falling
+      // through lets the aged in-flight fallback below recover it and keeps sibling rows moving.
+      try {
+        const settlement = await settleWorkspaceCommand(command, { onMergeSettled: scheduleRepoMerge });
+        if (!settlement.settled) { stillActive.push(ws.id); continue; }
+        settledTerminal.push(ws.id);
+      } catch (error) { settlementFailure = error; }
+    }
+    const fresh = getWorkspace(ws.id);
+    if (!fresh || !oldEnough(ws)) continue; // Only aged rows take the missing/malformed-result fallback.
+    if (LAND_IN_FLIGHT_STATUSES.has(fresh.status)) {
+      const reason = command
+        ? `workspace.merge ${command.status}${settlementFailure ? ` settlement failed: ${errMessage(settlementFailure)}` : " without settling workspace state"}`
+        : "workspace.merge command missing";
+      await updateWorkspaceStatusAsync(fresh.id, "review_requested", {
+        mergeCommandId: command?.id,
+        landGateQueue: undefined,
+        mergeError: reason,
+        inFlightWatchdogRecoveredAt: now,
+        ...noteMergeNoProgress(fresh.metadata),
+      });
+      recoveredMergePlanned.push(fresh.id);
+      scheduleRepoMerge(fresh.repoRoot);
+      await createActivityEventAsync({
+        clientId: `workspace-inflight-watchdog-merge-${fresh.id}-${now}`,
+        kind: "state",
+        title: "Recovered stuck workspace merge",
+        body: `${fresh.branch ?? fresh.id} was stuck in merge_planned; returned to review_requested (${reason})`,
+        meta: fresh.branch ?? fresh.id,
+        icon: "ti-refresh-alert",
+        view: "orchestrators",
+        metadata: { source: "server", maintenanceJobId: "workspace-auto-merge-watchdog", workspaceId: fresh.id, commandId: command?.id, commandStatus: command?.status },
+      });
+    } else if (fresh.status === "cleanup_requested") {
+      const reason = command
+        ? `workspace.cleanup ${command.status}${settlementFailure ? ` settlement failed: ${errMessage(settlementFailure)}` : " without cleaning workspace"}`
+        : "workspace.cleanup command missing";
+      await updateWorkspaceStatusAsync(fresh.id, "active", {
+        cleanupCommandId: command?.id,
+        cleanupError: reason,
+        inFlightWatchdogRecoveredAt: now,
+      });
+      recoveredCleanupRequested.push(fresh.id);
+      await createActivityEventAsync({
+        clientId: `workspace-inflight-watchdog-cleanup-${fresh.id}-${now}`,
+        kind: "state",
+        title: "Recovered stuck workspace cleanup",
+        body: `${fresh.branch ?? fresh.id} was stuck in cleanup_requested; returned to active (${reason})`,
+        meta: fresh.branch ?? fresh.id,
+        icon: "ti-refresh-alert",
+        view: "orchestrators",
+        metadata: { source: "server", maintenanceJobId: "workspace-auto-merge-watchdog", workspaceId: fresh.id, commandId: command?.id, commandStatus: command?.status },
+      });
+    }
+  }
+
+  return { recoveredMergePlanned, recoveredCleanupRequested, settledTerminal, stillActive, reclaimedOrphaned, expiredStaleCommands, ...(stoppedEarly ? { aborted: true } : {}) };
+}
+
+export async function runAutoMergeWatchdog(
+  opts: { now?: number; staleMs?: number; log?: (message: string) => void; signal?: AbortSignal } = {},
+): Promise<Record<string, unknown>> {
+  // #1819 — the watchdog restart decision itself (re-arming repo merge loops; each `scheduleRepoMerge`
+  // only ENQUEUES, the landing itself runs in `autoMergeCleanFastForwards`/`autoMergeForRepo`, which
+  // are cancellable) reads in-memory loop state and is effectively single-unit, small work that a 10s
+  // deadline cannot be overrun by in practice. #1830 — that no longer covers the WHOLE function: the
+  // in-flight recovery below now AWAITS the bounded (5s fetch / 2s rev-parse/merge-base) async
+  // ancestry check per aged workspace, so it gets its own PER-ROW checkpoint
+  // (`recoverAgedInFlightWorkspaces`'s own comment) instead of relying on this pre-flight refusal alone.
+  if (opts.signal?.aborted) return { readyCount: 0, aborted: true, restartedRepoRoots: [], forceRestartedRepoRoots: [] };
+  const now = opts.now ?? Date.now();
+  await runLandGateFailureWatchdog({ now, signal: opts.signal });
+  const staleMs = opts.staleMs ?? AUTO_MERGE_WATCHDOG_STALE_MS;
+  const inFlightRecovery = await recoverAgedInFlightWorkspaces(now, opts.signal);
+  const ready = landableWorkspaces();
+  const repoRoots = [...new Set(ready.map((ws) => ws.repoRoot).filter(Boolean))];
+  const repoStaleForMs = Object.fromEntries(repoRoots.map((repoRoot) => {
+    const state = repoMergeRunning.get(repoRoot);
+    const lastProgressAt = state?.lastProgressAt ?? repoMergeLastCompletedAt.get(repoRoot) ?? autoMergeWatchdogStartedAt;
+    return [repoRoot, now - lastProgressAt];
+  }));
+  const staleForMs = Object.values(repoStaleForMs).reduce((max, value) => Math.max(max, value), 0);
+  if (!ready.length) return { readyCount: 0, staleForMs, repoStaleForMs, restartedRepoRoots: [], forceRestartedRepoRoots: [], inFlightRecovery };
+
+  const restartedRepoRoots = repoRoots.filter((repoRoot) => repoStaleForMs[repoRoot]! >= staleMs);
+  if (!restartedRepoRoots.length) return { readyCount: ready.length, staleForMs, repoStaleForMs, restartedRepoRoots: [], forceRestartedRepoRoots: [], inFlightRecovery };
+
+  const log = opts.log ?? console.warn;
+  log(`[workspace-auto-merge] Watchdog: no auto-merge cycle completed for ${staleForMs}ms while ${ready.length} ready workspace(s) exist; restarting ${restartedRepoRoots.length} repo merge loop(s)`);
+  const forceStaleMs = staleMs * AUTO_MERGE_WATCHDOG_FORCE_RESTART_FACTOR;
+  const forceRestartedRepoRoots: string[] = [];
+  for (const repoRoot of restartedRepoRoots) {
+    const existing = repoMergeRunning.get(repoRoot);
+    // #2232 — REAL recovery for a WEDGED loop. Flagging `pending` (below) is consumed at the TOP of the
+    // next iteration of the SAME loop — a complete no-op when that loop is the thing that is stuck, which
+    // is precisely when this watchdog fires. Observed: one repo stopped dispatching every merge for 20+
+    // min until a daemon restart, with this watchdog "restarting" it on every tick. So past N× the
+    // threshold, force-REPLACE the run instead of flagging it: mark it abandoned (it can never resume
+    // behind its replacement), abort its cycle (a cooperative sweep stops at its next candidate; a wedged
+    // await is abandoned), drop the entry, and start a genuinely fresh cycle.
+    if (existing && repoStaleForMs[repoRoot]! >= forceStaleMs) {
+      existing.abandoned = true;
+      existing.abort?.abort(new Error(`watchdog force-restarted a wedged auto-merge cycle for ${repoRoot}`));
+      repoMergeRunning.delete(repoRoot);
+      forceRestartedRepoRoots.push(repoRoot);
+      log(`[workspace-auto-merge] Watchdog: repo ${repoRoot} merge loop wedged for ${repoStaleForMs[repoRoot]}ms (>= ${forceStaleMs}ms) — force-replacing the stale in-flight cycle with a fresh one`);
+      scheduleRepoMerge(repoRoot);
+      continue;
+    }
+    // A watchdog restart isn't reacting to a specific base moving — force an unfiltered rerun.
+    if (existing) existing.pending = widenPendingRerun(existing.pending, { kind: "unfiltered" });
+    else scheduleRepoMerge(repoRoot);
+  }
+  return { readyCount: ready.length, staleForMs, repoStaleForMs, restartedRepoRoots, forceRestartedRepoRoots, inFlightRecovery };
+}
+
+// Drain the landable rows for ONE repo (the event-driven fast path). Scoped to the
+// repo whose ready/settle event fired so it doesn't re-probe every other repo's worktrees, and
+// (#1473) further scoped to `baseRef` when the trigger was a specific base settling — this is
+// what stops a single land from flooding the steward with re-probes of every ready branch in
+// the repo regardless of which base they target.
+// #2232 — `signal` is the cycle deadline's (and the watchdog force-restart's) cancellation channel; it
+// reaches landCandidates' existing per-candidate checkpoint, so a bounded-out cycle stops cleanly at a
+// candidate boundary instead of racing on underneath its replacement.
+//
+// WHICH AWAIT CAN HANG (#2232 item 3, best-effort): every host RPC on this path is already deadline-
+// bounded (merge preview 8s, landing-identity discovery 5s, execution-tree reservation 40s). The one
+// genuinely UNBOUNDED await found is the DB write gateway: a CRITICAL write (`requestWorkspaceMerge` →
+// `ensureLegacyOpenLandingOwnershipAsync`, `landingControllers.ensureLegacyOpen`) is admitted and HELD in
+// the writer FIFO while the writer is wedged (writer-gateway.ts: `drainLoop` pauses on `wedged`, and the
+// per-op `writerTimeoutMs` only arms at DISPATCH). Non-critical writes shed fast and surface as a thrown
+// error; a critical one waits for however long the wedged op takes — unbounded by construction. Bounding
+// it AT that await is deliberately NOT done here: abandoning an in-flight critical write makes its
+// outcome indeterminate, and a re-dispatched land is exactly what the at-most-once landing contract
+// forbids. The per-cycle deadline above is therefore the safety net for this (and any future) hang: the
+// write keeps its own semantics while the repo's dispatch lane is released regardless.
+/** Test-only (#2607): drive one repo's land sweep directly — the same `landCandidates`
+ * engine the event trigger and the maintenance backstop both drain through. */
+export { autoMergeForRepo as __autoMergeForRepoForTests };
+async function autoMergeForRepo(repoRoot: string, baseRef?: string, signal?: AbortSignal, owningState?: RepoMergeRunState): Promise<LandSweepResult> {
+  if (!workspaceAutoMergeEnabled()) return emptyLandSweep();
+  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
+  if (!orchestrators.length) return emptyLandSweep();
+  const candidates = landableWorkspaces(repoRoot, baseRef);
+  const progress = { processed: 0 };
+  try {
+    return await landCandidates(candidates, orchestrators, signal, progress);
+  } finally {
+    // #2232 — the same rule autoMergeCleanFastForwards documents for #1819: an ABORTED sweep that left
+    // candidates unprocessed did NOT drain this lane, and stamping it anyway would tell the watchdog the
+    // merge loop is alive — blinding the one backstop that restarts it, under exactly the deadline
+    // pressure that produced the abort. Every non-abort path stamps exactly as before.
+    if (!signal?.aborted || progress.processed >= candidates.length) noteAutoMergeCycleCompleted(repoRoot, owningState);
+  }
+}
+
+// Self-healing backstop (#237): the periodic resync (workspace-auto-merge maintenance
+// job, runOnStart + ~10-min interval) that lands anything events missed — a relay
+// restart that lost the in-flight chain, a dropped stop-hook, a direct human commit
+// with no agent turn. Scans EVERY repo's landable rows; the per-repo lease still caps
+// it at one dispatch per repo per sweep, and the on-settle re-trigger drains the rest fast.
+export async function autoMergeCleanFastForwards(context: { signal?: AbortSignal } = {}): Promise<Record<string, unknown>> {
+  if (!workspaceAutoMergeEnabled()) return { skipped: "disabled" };
+  if (context.signal?.aborted) return { scanned: 0, aborted: true };
+  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
+  if (!orchestrators.length) return { scanned: 0, skipped: "no online orchestrators" };
+
+  const candidates = landableWorkspaces();
+  const repoRoots = [...new Set(candidates.map((ws) => ws.repoRoot).filter(Boolean))];
+  const progress = { processed: 0 };
+  // Spread to a plain Record for the maintenance-job result contract (the named
+  // LandSweepResult interface has no index signature).
+  try {
+    return { ...(await landCandidates(candidates, orchestrators, context.signal, progress)), ...(context.signal?.aborted ? { aborted: true } : {}) };
+  } finally {
+    // #1819 — a completed-cycle stamp is what `runAutoMergeWatchdog` reads to decide a repo's merge
+    // loop is alive (repoMergeLastCompletedAt / lastProgressAt). On the ABORT path this sweep did NOT
+    // complete a cycle for the repos whose candidates it never reached, and stamping them anyway
+    // would tell the watchdog every lane just drained — blinding the one backstop that restarts a
+    // stalled loop, under exactly the deadline pressure that produced the abort. So on abort, stamp
+    // only repos with no candidate left unprocessed. The normal path and the pre-existing THROW path
+    // are deliberately unchanged: `stalled` is empty unless the signal aborted, so both still stamp
+    // every repo exactly as before.
+    const stalled = context.signal?.aborted
+      ? new Set(candidates.slice(progress.processed).map((ws) => ws.repoRoot))
+      : new Set<string>();
+    for (const repoRoot of repoRoots) if (!stalled.has(repoRoot)) noteAutoMergeCycleCompleted(repoRoot);
+  }
+}
+
+export { wakeRepoSteward } from "./workspace-steward-wake";