agent-relay-server 0.120.4 → 0.120.6

package/src/workspace-auto-merge.ts

@@ -21,10 +21,13 @@
 import {
   createActivityEvent,
   getActiveMergePause,
+  getWorkspace,
   listOrchestrators,
   listWorkspaces,
   patchWorkspaceMetadata,
+  updateWorkspaceStatus,
 } from "./db";
+import { findLatestCommandByCorrelation } from "./commands-db";
 import { notifyBranchLandFailed, notifyStewardHandoff } from "./branch-landed";
 import { resolveStewardIdentity } from "./steward-identity";
 import { emitCommandEvent } from "./command-events";
@@ -36,17 +39,20 @@ import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
 import { emitWorkspaceTaskSemanticNotifications } from "./services/task-lifecycle";
 import { ensureRepoSteward } from "./steward";
 import { requestWorkspaceMerge, workspaceMergeOrchestrators } from "./workspace-merge";
+import { settleWorkspaceCommand } from "./workspace-command-settle";
+import { CLEAR_MERGE_NO_PROGRESS, MAX_NO_PROGRESS_MERGE_ATTEMPTS, mergeNoProgressCount, noteMergeNoProgress } from "./workspace-merge-progress";
 import { workspaceOwnerOrchestrator } from "./workspace-host";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES } from "./workspace-phase";
 import { fetchHostMergePreview } from "./workspace-probe";
-import type { WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMergePreview, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
+import type { Command, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMergePreview, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
 import { STEWARD_WAKE_COOLDOWN_MS, stewardFallbackTarget, workspaceAutoMergeEnabled } from "./config";
 import { isPathWithinBase } from "./utils";
 import type { Orchestrator } from "./types";
 
 const WORKSPACE_LAND_STRATEGIES = ["direct", "pr"] as const;
 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";
@@ -174,41 +180,13 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
   }
 }
 
-// #638 — auto-merge loop breaker. A `workspace.merge` the orchestrator settles `failed`
-// (no progress: origin moved ahead of local base, a replay conflict the clean-preview
-// didn't predict, a push race) returns the workspace to a landable status
-// (`review_requested`). The on-settle re-trigger (routes/commands.ts → scheduleRepoMerge)
-// then re-dispatches it within a few seconds — forever. That's a silent merge-command
-// storm that churns the per-repo lease and 409s every manual land (the live incident).
-// Cap consecutive no-progress attempts per workspace; past the cap, stop dispatching and
-// escalate. The count is incremented by the merge-result handler (server owns the
-// transition) and cleared on genuine progress or a fresh ready/request-review hand-off.
-export const MAX_NO_PROGRESS_MERGE_ATTEMPTS = 3;
-
 // 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;
 
-/** The recorded count of consecutive no-progress merge attempts for a workspace (#638). */
-export function mergeNoProgressCount(metadata: Record<string, unknown>): number {
-  const n = metadata.autoMergeNoProgressCount;
-  return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : 0;
-}
-
-/** Metadata patch recording one more no-progress merge attempt (#638). Applied by the
- * merge-result handler when a dispatched merge settles `failed` without landing. */
-export function noteMergeNoProgress(metadata: Record<string, unknown>): Record<string, unknown> {
-  return { autoMergeNoProgressCount: mergeNoProgressCount(metadata) + 1, autoMergeNoProgressAt: Date.now() };
-}
-
-/** Metadata patch that clears the no-progress back-off — genuine progress (a land/recycle)
- * or a fresh hand-off means the lane is worth attempting again (#638). */
-export const CLEAR_MERGE_NO_PROGRESS: Record<string, unknown> = {
-  autoMergeNoProgressCount: 0,
-  autoMergeNoProgressAt: undefined,
-  autoMergeBackedOffAt: undefined,
-};
+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
@@ -558,11 +536,93 @@ export function resetRepoMergeSchedulerForTests(): void {
   autoMergeWatchdogStartedAt = Date.now();
 }
 
+function commandIsTerminal(command: Command | null): boolean {
+  return Boolean(command && TERMINAL_COMMAND_STATUSES.has(command.status));
+}
+
+function latestWorkspaceCommand(ws: WorkspaceRecord): Command | null {
+  const type = ws.status === "merge_planned" ? "workspace.merge" : "workspace.cleanup";
+  return findLatestCommandByCorrelation(type, ws.id);
+}
+
+function recoverAgedInFlightWorkspaces(now: number): Record<string, string[]> {
+  const oldEnough = (ws: WorkspaceRecord) => now - ws.updatedAt >= IN_FLIGHT_WORKSPACE_WATCHDOG_AGE_MS;
+  const recoveredMergePlanned: string[] = [];
+  const recoveredCleanupRequested: string[] = [];
+  const settledTerminal: string[] = [];
+  const stillActive: string[] = [];
+
+  for (const ws of listWorkspaces().filter((row) =>
+    row.mode === "isolated"
+    && Boolean(row.worktreePath)
+    && (row.status === "merge_planned" || row.status === "cleanup_requested")
+    && oldEnough(row),
+  )) {
+    const command = latestWorkspaceCommand(ws);
+    if (command && !commandIsTerminal(command)) {
+      stillActive.push(ws.id);
+      continue;
+    }
+    if (command) {
+      settleWorkspaceCommand(command, { onMergeSettled: scheduleRepoMerge });
+      settledTerminal.push(ws.id);
+    }
+    const fresh = getWorkspace(ws.id);
+    if (!fresh) continue;
+    if (fresh.status === "merge_planned") {
+      const reason = command
+        ? `workspace.merge ${command.status} without settling workspace state`
+        : "workspace.merge command missing";
+      updateWorkspaceStatus(fresh.id, "review_requested", {
+        mergeCommandId: command?.id,
+        mergeError: reason,
+        inFlightWatchdogRecoveredAt: now,
+        ...noteMergeNoProgress(fresh.metadata),
+      });
+      recoveredMergePlanned.push(fresh.id);
+      scheduleRepoMerge(fresh.repoRoot);
+      createActivityEvent({
+        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} without cleaning workspace`
+        : "workspace.cleanup command missing";
+      updateWorkspaceStatus(fresh.id, "active", {
+        cleanupCommandId: command?.id,
+        cleanupError: reason,
+        inFlightWatchdogRecoveredAt: now,
+      });
+      recoveredCleanupRequested.push(fresh.id);
+      createActivityEvent({
+        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 };
+}
+
 export function runAutoMergeWatchdog(
   opts: { now?: number; staleMs?: number; log?: (message: string) => void } = {},
 ): Record<string, unknown> {
   const now = opts.now ?? Date.now();
   const staleMs = opts.staleMs ?? AUTO_MERGE_WATCHDOG_STALE_MS;
+  const inFlightRecovery = recoverAgedInFlightWorkspaces(now);
   const ready = landableWorkspaces();
   const repoRoots = [...new Set(ready.map((ws) => ws.repoRoot).filter(Boolean))];
   const repoStaleForMs = Object.fromEntries(repoRoots.map((repoRoot) => {
@@ -571,10 +631,10 @@ export function runAutoMergeWatchdog(
     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: [] };
+  if (!ready.length) return { readyCount: 0, staleForMs, repoStaleForMs, restartedRepoRoots: [], inFlightRecovery };
 
   const restartedRepoRoots = repoRoots.filter((repoRoot) => repoStaleForMs[repoRoot]! >= staleMs);
-  if (!restartedRepoRoots.length) return { readyCount: ready.length, staleForMs, repoStaleForMs, restartedRepoRoots: [] };
+  if (!restartedRepoRoots.length) return { readyCount: ready.length, staleForMs, repoStaleForMs, restartedRepoRoots: [], 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)`);
@@ -583,7 +643,7 @@ export function runAutoMergeWatchdog(
     if (existing) existing.rerun = true;
     else scheduleRepoMerge(repoRoot);
   }
-  return { readyCount: ready.length, staleForMs, repoStaleForMs, restartedRepoRoots };
+  return { readyCount: ready.length, staleForMs, repoStaleForMs, restartedRepoRoots, inFlightRecovery };
 }
 
 // Drain the landable rows for ONE repo (the event-driven fast path). Scoped to the

package/src/workspace-command-settle.ts

@@ -0,0 +1,227 @@
+import { isRecord, sanitizeFsName, type LandGateRunResult } from "agent-relay-sdk";
+import { storeTextArtifact } from "./artifact-text";
+import { notifyBaseWorktreeStrand, notifyBranchLandFailed, notifyBranchLanded, notifyLandGateFailed, notifyLandGateWarnings } from "./branch-landed";
+import { getWorkspace, releaseMergeLease, setWorkspaceBranch, updateWorkspaceStatus } from "./db";
+import { handleReviewerMergeResult } from "./reviewer-pipeline";
+import { emitWorkspaceTaskSemanticNotifications } from "./services/task-lifecycle";
+import { VALID_WORKSPACE_STATUSES, cleanString, optionalEnum } from "./validation";
+import { CLEAR_MERGE_NO_PROGRESS, noteMergeNoProgress } from "./workspace-merge-progress";
+import { claimMetadataPatch } from "./workspace-claim";
+import { commandTargetsWorkspaceOwner } from "./workspace-host";
+import type { Command, WorkspaceStatus } from "./types";
+
+export interface WorkspaceCommandSettleResult {
+  settled: boolean;
+  ignoredWrongOwner?: boolean;
+}
+
+export interface WorkspaceCommandSettleOptions {
+  onMergeSettled?: (repoRoot: string | undefined) => void;
+}
+
+const WORKSPACE_MERGE_SETTLED_STATUSES = new Set(["succeeded", "failed", "timed_out", "rejected", "canceled"]);
+const WORKSPACE_MERGE_FAILED_STATUSES = new Set(["failed", "timed_out", "rejected", "canceled"]);
+const WORKSPACE_CLEANUP_FAILED_STATUSES = new Set(["failed", "timed_out", "rejected", "canceled"]);
+
+function normalizeGateRunResult(value: unknown): LandGateRunResult | undefined {
+  if (!isRecord(value)) return undefined;
+  const name = typeof value.name === "string" ? value.name : undefined;
+  const command = typeof value.command === "string" ? value.command : "";
+  if (!name) return undefined;
+  return {
+    name,
+    command,
+    optional: value.optional === true,
+    passed: value.passed === true,
+    exitCode: typeof value.exitCode === "number" ? value.exitCode : null,
+    timedOut: value.timedOut === true,
+    durationMs: typeof value.durationMs === "number" ? value.durationMs : 0,
+    outputTail: typeof value.outputTail === "string" ? value.outputTail : "",
+    output: typeof value.output === "string" ? value.output : (typeof value.outputTail === "string" ? value.outputTail : ""),
+  };
+}
+
+function normalizeGateWarnings(value: unknown): LandGateRunResult[] {
+  if (!Array.isArray(value)) return [];
+  return value.map(normalizeGateRunResult).filter((g): g is LandGateRunResult => Boolean(g));
+}
+
+async function uploadGateOutputArtifact(workspaceId: string, gate: LandGateRunResult): Promise<string | undefined> {
+  try {
+    const safeName = sanitizeFsName(gate.name, { replacement: "-", maxLen: 60, trimEdge: true, fallback: "gate" });
+    const stored = await storeTextArtifact({
+      text: gate.output || gate.outputTail || "(no output)",
+      filename: `land-gate-${safeName}-${workspaceId}.log`,
+      createdBy: "server",
+      metadata: { kind: "land-gate-output", workspaceId, gateName: gate.name, gateCommand: gate.command, exitCode: gate.exitCode, timedOut: gate.timedOut },
+    });
+    return stored.id;
+  } catch (error) {
+    console.warn(`land-gate artifact upload failed for ${workspaceId} gate "${gate.name}": ${String(error)}`);
+    return undefined;
+  }
+}
+
+function commandFailureReason(command: Command, fallback: string): string {
+  if (command.error) return command.error;
+  if (command.status === "timed_out") return "command timed out";
+  if (command.status === "canceled") return "command canceled";
+  if (command.status === "rejected") return "command rejected";
+  return fallback;
+}
+
+export function settleWorkspaceCleanupCommand(command: Command): WorkspaceCommandSettleResult {
+  if (command.type !== "workspace.cleanup") return { settled: false };
+  if (command.status === "succeeded" && isRecord(command.result)) {
+    const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+    if (!workspaceId) return { settled: true };
+    const workspace = getWorkspace(workspaceId);
+    if (workspace && commandTargetsWorkspaceOwner(command, workspace)) {
+      updateWorkspaceStatus(workspaceId, "cleaned", {
+        cleanupResult: command.result,
+        cleanupCommandId: command.id,
+      });
+    }
+    return { settled: true };
+  }
+  if (!WORKSPACE_CLEANUP_FAILED_STATUSES.has(command.status)) return { settled: false };
+  const resultWorkspaceId = isRecord(command.result) ? cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 }) : undefined;
+  const workspaceId = resultWorkspaceId ?? command.correlationId;
+  if (!workspaceId) return { settled: true };
+  const workspace = getWorkspace(workspaceId);
+  if (!workspace || workspace.status !== "cleanup_requested") return { settled: true };
+  if (!commandTargetsWorkspaceOwner(command, workspace)) return { settled: true, ignoredWrongOwner: true };
+  updateWorkspaceStatus(workspaceId, "active", {
+    cleanupCommandId: command.id,
+    cleanupError: commandFailureReason(command, "cleanup failed"),
+    cleanupFailedAt: Date.now(),
+    cleanupResult: isRecord(command.result) ? command.result : undefined,
+  });
+  return { settled: true };
+}
+
+export function settleWorkspaceMergeCommand(command: Command, opts: WorkspaceCommandSettleOptions = {}): WorkspaceCommandSettleResult {
+  if (command.type !== "workspace.merge") return { settled: false };
+  if (WORKSPACE_MERGE_SETTLED_STATUSES.has(command.status)) {
+    releaseMergeLease({ commandId: command.id });
+    const settledRepoRoot = typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined;
+    opts.onMergeSettled?.(settledRepoRoot);
+  }
+  if (command.status === "succeeded" && isRecord(command.result)) {
+    if (handleReviewerMergeResult(command, command.result)) return { settled: true };
+    const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+    const resultStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+    if (!workspaceId || !resultStatus) return { settled: true };
+    const landedWorkspace = getWorkspace(workspaceId);
+    if (landedWorkspace && !commandTargetsWorkspaceOwner(command, landedWorkspace)) return { settled: true, ignoredWrongOwner: true };
+    const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
+    const normalizedStatus = command.result.merged === true
+      && !newBranch
+      && ["review_requested", "merge_planned", "conflict"].includes(resultStatus)
+      ? "merged"
+      : resultStatus;
+    updateWorkspaceStatus(workspaceId, normalizedStatus, {
+      mergeResult: command.result,
+      mergeCommandId: command.id,
+      mergedAt: Date.now(),
+      ...CLEAR_MERGE_NO_PROGRESS,
+      mergeError: undefined,
+      ...(normalizedStatus !== resultStatus ? { mergeStatusNormalizedFrom: resultStatus } : {}),
+      ...claimMetadataPatch(true),
+    });
+    const mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
+    const baseSha = cleanString(command.result.baseSha, "result.baseSha", { max: 64 });
+    if (newBranch) setWorkspaceBranch(workspaceId, newBranch, baseSha ?? mergedSha);
+    const prLanded = isRecord(command.params.prLanded) ? command.params.prLanded : undefined;
+    const baseWorktreeSync = isRecord(command.result.baseWorktreeSync) ? command.result.baseWorktreeSync : undefined;
+    if (baseWorktreeSync && baseWorktreeSync.reconciled === false && landedWorkspace) {
+      notifyBaseWorktreeStrand({
+        workspace: landedWorkspace,
+        sync: {
+          reconciled: false,
+          unsyncedPaths: Array.isArray(baseWorktreeSync.unsyncedPaths) ? baseWorktreeSync.unsyncedPaths.filter((p): p is string => typeof p === "string") : undefined,
+          preservedWipPaths: Array.isArray(baseWorktreeSync.preservedWipPaths) ? baseWorktreeSync.preservedWipPaths.filter((p): p is string => typeof p === "string") : undefined,
+          message: typeof baseWorktreeSync.message === "string" ? baseWorktreeSync.message : undefined,
+        },
+      });
+    }
+    if ((command.result.merged === true || prLanded) && landedWorkspace) {
+      notifyBranchLanded({
+        workspace: landedWorkspace,
+        mergedSha: prLanded ? cleanString(prLanded.sha, "params.prLanded.sha", { max: 64 }) ?? mergedSha : mergedSha,
+        subject: prLanded
+          ? cleanString(prLanded.subject, "params.prLanded.subject", { max: 200 })
+          : cleanString(command.result.subject, "result.subject", { max: 200 }),
+        prLand: Boolean(prLanded),
+        newBranch,
+        pushed: prLanded ? true : typeof command.result.pushed === "boolean" ? command.result.pushed : undefined,
+      });
+    }
+    const gateWarnings = command.result.merged === true ? normalizeGateWarnings(command.result.gateWarnings) : [];
+    if (gateWarnings.length && landedWorkspace) {
+      const warnWorkspace = landedWorkspace;
+      void (async () => {
+        const combined = gateWarnings.map((g) => `### ${g.name} (${g.command}) - ${g.timedOut ? "timed out" : g.exitCode === null ? "could not run" : `exited ${g.exitCode}`}\n${g.output || g.outputTail || "(no output)"}`).join("\n\n");
+        let artifactId: string | undefined;
+        try {
+          artifactId = (await storeTextArtifact({ text: combined, filename: `land-gate-warnings-${warnWorkspace.id}.log`, createdBy: "server", metadata: { kind: "land-gate-warnings", workspaceId: warnWorkspace.id, gateNames: gateWarnings.map((g) => g.name) } })).id;
+        } catch (error) {
+          console.warn(`land-gate-warnings artifact upload failed for ${warnWorkspace.id}: ${String(error)}`);
+        }
+        try {
+          notifyLandGateWarnings({ workspace: warnWorkspace, warnings: gateWarnings, artifactId });
+        } catch (error) {
+          console.warn(`land-gate-warnings notify threw for ${warnWorkspace.id}: ${String(error)}`);
+        }
+      })();
+    }
+    return { settled: true };
+  }
+  if (WORKSPACE_MERGE_FAILED_STATUSES.has(command.status) && command.correlationId) {
+    const current = getWorkspace(command.correlationId);
+    if (!current || current.status !== "merge_planned") return { settled: true };
+    if (!commandTargetsWorkspaceOwner(command, current)) return { settled: true, ignoredWrongOwner: true };
+    const failedResultStatus = isRecord(command.result)
+      ? optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined
+      : undefined;
+    const nextStatus: WorkspaceStatus = failedResultStatus && failedResultStatus !== "merge_planned"
+      ? failedResultStatus
+      : "review_requested";
+    const reason = commandFailureReason(command, "merge failed");
+    updateWorkspaceStatus(command.correlationId, nextStatus, {
+      mergeCommandId: command.id,
+      mergeError: reason,
+      ...noteMergeNoProgress(current.metadata),
+    });
+    if (nextStatus === "conflict") {
+      emitWorkspaceTaskSemanticNotifications({
+        workspace: current,
+        transition: "land-conflict",
+        actor: "workspace-merge",
+        occurrenceKey: `workspace-merge-conflict:${current.id}:${command.id}`,
+        outcome: { reason, commandId: command.id, status: nextStatus },
+      });
+    }
+    const gateFailure = isRecord(command.result) ? normalizeGateRunResult(command.result.gateFailure) : undefined;
+    if (gateFailure) {
+      void (async () => {
+        const artifactId = await uploadGateOutputArtifact(current.id, gateFailure);
+        try {
+          notifyLandGateFailed({ workspace: current, gate: gateFailure, artifactId });
+        } catch (error) {
+          console.warn(`land-gate-failed notify threw for ${current.id}: ${String(error)}`);
+        }
+      })();
+    } else {
+      notifyBranchLandFailed({ workspace: current, commandId: command.id, reason });
+    }
+    return { settled: true };
+  }
+  return { settled: false };
+}
+
+export function settleWorkspaceCommand(command: Command, opts: WorkspaceCommandSettleOptions = {}): WorkspaceCommandSettleResult {
+  if (command.type === "workspace.merge") return settleWorkspaceMergeCommand(command, opts);
+  if (command.type === "workspace.cleanup") return settleWorkspaceCleanupCommand(command);
+  return { settled: false };
+}

package/src/workspace-escalation.ts

@@ -0,0 +1,45 @@
+import { stewardFallbackTarget } from "./config";
+import { routeNotification } from "./notification-router";
+import { resolveStewardIdentity } from "./steward-identity";
+import type { NotificationType } from "./notification-types";
+import type { WorkspaceRecord, WorkspaceStatus } from "./types";
+
+export const READY_TO_LAND_ESCALATION_STATUSES = new Set<WorkspaceStatus>(["ready", "review_requested"]);
+
+export function routeWorkspaceCustodyEscalation(input: {
+  workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "status" | "ownerAgentId">;
+  type?: NotificationType;
+  subject: string;
+  body: string;
+  payload: Record<string, unknown>;
+  idempotencyKey?: string;
+}): string[] {
+  const { ownerAgentId, coordinatorAgentId } = resolveStewardIdentity(input.workspace);
+  const fallback = stewardFallbackTarget();
+  const recipients = [...new Set([ownerAgentId, coordinatorAgentId, fallback].filter((value): value is string => Boolean(value)))];
+  if (!recipients.length) return [];
+
+  routeNotification({
+    type: input.type ?? "workspace.stranded_escalation",
+    scope: {
+      workspaceId: input.workspace.id,
+      repoRoot: input.workspace.repoRoot,
+      author: ownerAgentId,
+      parent: coordinatorAgentId ?? undefined,
+    },
+    recipients,
+    message: {
+      subject: input.subject,
+      body: input.body,
+      payload: {
+        ...input.payload,
+        coordinatorAgentId,
+        ownerAgentId,
+        fallbackTarget: fallback || undefined,
+      },
+      idempotencyKey: input.idempotencyKey,
+    },
+    ttlMs: null,
+  });
+  return recipients;
+}

package/src/workspace-merge-progress.ts

@@ -0,0 +1,16 @@
+export const MAX_NO_PROGRESS_MERGE_ATTEMPTS = 3;
+
+export function mergeNoProgressCount(metadata: Record<string, unknown>): number {
+  const n = metadata.autoMergeNoProgressCount;
+  return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+export function noteMergeNoProgress(metadata: Record<string, unknown>): Record<string, unknown> {
+  return { autoMergeNoProgressCount: mergeNoProgressCount(metadata) + 1, autoMergeNoProgressAt: Date.now() };
+}
+
+export const CLEAR_MERGE_NO_PROGRESS: Record<string, unknown> = {
+  autoMergeNoProgressCount: 0,
+  autoMergeNoProgressAt: undefined,
+  autoMergeBackedOffAt: undefined,
+};