agent-relay-server 0.11.8 → 0.11.9

package/runner/src/adapter.ts

@@ -12,6 +12,10 @@ export interface ProviderStatusEvent {
     status: string;
     id?: string;
     timestamp?: number;
+    title?: string;
+    body?: string;
+    icon?: string;
+    metadata?: Record<string, unknown>;
   };
   id?: string;
   label?: string;

package/src/bus.ts

@@ -159,6 +159,7 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         }
         const after = getAgent(conn.agentId);
         auditProviderStateTransition(conn.agentId, before, after);
+        auditRunnerTimelineEvent(conn.agentId, after?.meta?.timelineEvent);
         // A real PreCompact/SessionStart hook arrives as a timelineEvent in the
         // merged meta — clears any pending stall watch (stale events ignored).
         noteAgentTimelineEvent(conn.agentId, after?.meta?.timelineEvent);
@@ -558,6 +559,47 @@ function auditProviderStateTransition(agentId: string, before: AgentCard | null
   }
 }
 
+function auditRunnerTimelineEvent(agentId: string, timelineEvent: unknown): void {
+  if (!isRecord(timelineEvent)) return;
+  const metadata = isRecord(timelineEvent.metadata) ? timelineEvent.metadata : {};
+  if (metadata.source !== "runner") return;
+  const status = stringValue(timelineEvent.status);
+  if (!status) return;
+  const eventType = stringValue(metadata.eventType) ?? status;
+  const timestamp = numberValue(timelineEvent.timestamp) ?? Date.now();
+  const id = stringValue(timelineEvent.id) ?? `${eventType}-${timestamp}`;
+  const title = stringValue(timelineEvent.title) ?? status.replace(/[._-]+/g, " ");
+  const body = stringValue(timelineEvent.body);
+  const icon = stringValue(timelineEvent.icon) ?? "ti-activity";
+  try {
+    const event = createActivityEvent({
+      clientId: `runner-timeline-${agentId}-${id}`,
+      kind: "state",
+      title,
+      body,
+      meta: agentId,
+      icon,
+      view: "agents",
+      agentId,
+      metadata: {
+        ...metadata,
+        eventType,
+        timelineStatus: status,
+        timelineId: id,
+        timelineTimestamp: timestamp,
+      },
+    });
+    emitRelayEvent({
+      type: "activity.created",
+      source: "server",
+      subject: String(event.id),
+      data: event as unknown as Record<string, unknown>,
+    });
+  } catch {
+    // Timeline writes must never block bus status updates.
+  }
+}
+
 function providerStateFromAgent(agent: AgentCard | null | undefined): Record<string, unknown> | null {
   const value = agent?.meta?.providerState;
   if (!isRecord(value) || typeof value.state !== "string") return null;

package/src/config-store.ts

@@ -7,13 +7,17 @@ import type {
   ConfigHistoryEntry,
   ManagedAgentState,
   ManagedAgentStatus,
+  SpawnApprovalMode,
   SpawnPolicy,
   SpawnProvider,
+  StewardConfig,
 } from "./types";
 
 const CONFIG_HISTORY_LIMIT = 50;
 const SPAWN_POLICY_NAMESPACE = "spawn-policy";
 const AGENT_PROFILE_NAMESPACE = "agent-profile";
+const STEWARD_NAMESPACE = "steward";
+const STEWARD_KEY = "default";
 const VALID_PROVIDERS = ["claude", "codex"] as const;
 const VALID_PROFILE_PROVIDERS = ["any", "claude", "codex"] as const;
 const VALID_PROFILE_BASES = ["host", "minimal", "isolated"] as const;
@@ -390,10 +394,42 @@ function cleanBinding(value: unknown): NonNullable<SpawnPolicy["binding"]> {
   };
 }
 
+const STEWARD_CONFIG_DEFAULTS: StewardConfig = {
+  enabled: false,
+  provider: "claude",
+  permissionMode: "open",
+  keepaliveSeconds: 300,
+};
+
+function validateStewardConfig(value: unknown): StewardConfig {
+  if (!isRecord(value)) throw new ValidationError("steward config value must be an object");
+  const config: StewardConfig = {
+    enabled: value.enabled === undefined ? false : cleanBoolean(value.enabled, "enabled"),
+    provider: cleanEnum(value.provider, "provider", VALID_PROVIDERS) as SpawnProvider,
+    model: cleanString(value.model, "model", { max: 120 }),
+    effort: value.effort === undefined || value.effort === null ? undefined : cleanEnum(value.effort, "effort", VALID_EFFORTS) as ProviderEffort,
+    permissionMode: (value.permissionMode === undefined || value.permissionMode === null
+      ? "open"
+      : cleanEnum(value.permissionMode, "permissionMode", VALID_PERMISSION_MODES)) as SpawnApprovalMode,
+    keepaliveSeconds: value.keepaliveSeconds === undefined || value.keepaliveSeconds === null
+      ? 300
+      : cleanNumber(value.keepaliveSeconds, "keepaliveSeconds", { min: 0, max: 2_592_000 }),
+  };
+  // Reject a provider/model/effort combo the catalog can't resolve before it ever
+  // reaches a spawn (same guard as spawn policies).
+  try {
+    resolveProviderSelection({ provider: config.provider, model: config.model, effort: config.effort });
+  } catch (error) {
+    throw new ValidationError(error instanceof Error ? error.message : String(error));
+  }
+  return config;
+}
+
 function normalizeValue(namespace: string, key: string, value: unknown): unknown {
   if (value === undefined) throw new ValidationError("value required");
   if (namespace === SPAWN_POLICY_NAMESPACE) return validateSpawnPolicy(key, value);
   if (namespace === AGENT_PROFILE_NAMESPACE) return validateAgentProfile(key, value);
+  if (namespace === STEWARD_NAMESPACE) return validateStewardConfig(value);
   if (JSON.stringify(value) === undefined) throw new ValidationError("value must be valid JSON");
   return value;
 }
@@ -485,6 +521,28 @@ function setSpawnPolicy(policy: SpawnPolicy, updatedBy?: string): ConfigEntry<Sp
   return setConfig(SPAWN_POLICY_NAMESPACE, policy.name, policy, updatedBy);
 }
 
+/** Global steward config, merged over defaults (always returns a usable value). */
+export function getStewardConfig(): StewardConfig {
+  const entry = getConfig<StewardConfig>(STEWARD_NAMESPACE, STEWARD_KEY);
+  return entry ? { ...STEWARD_CONFIG_DEFAULTS, ...entry.value } : { ...STEWARD_CONFIG_DEFAULTS };
+}
+
+export function getStewardConfigEntry(): ConfigEntry<StewardConfig> {
+  const entry = getConfig<StewardConfig>(STEWARD_NAMESPACE, STEWARD_KEY);
+  return entry ?? {
+    namespace: STEWARD_NAMESPACE,
+    key: STEWARD_KEY,
+    value: { ...STEWARD_CONFIG_DEFAULTS },
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function setStewardConfig(value: unknown, updatedBy?: string): ConfigEntry<StewardConfig> {
+  return setConfig(STEWARD_NAMESPACE, STEWARD_KEY, value as StewardConfig, updatedBy);
+}
+
 function builtInProfileEntry(profile: AgentProfile): ConfigEntry<AgentProfile> {
   return {
     namespace: AGENT_PROFILE_NAMESPACE,

package/src/maintenance.ts

@@ -31,6 +31,9 @@ import {
   updateWorkspaceStatus,
 } from "./db";
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
+import { requestWorkspaceMerge } from "./workspace-merge";
+import { getStewardConfig } from "./config-store";
+import { ensureRepoSteward } from "./steward";
 import { emitRelayEvent } from "./events";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { applyCommandToRecipe } from "./recipe-runner";
@@ -55,6 +58,14 @@ const CONFLICT_SCAN_INTERVAL_MS = Number(process.env.AGENT_RELAY_CONFLICT_SCAN_I
 const WORKSPACE_RETENTION_MS = Number(process.env.AGENT_RELAY_WORKSPACE_RETENTION_MS) || DAY_MS;
 const WORKSPACE_REVIEW_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS) || 3 * DAY_MS;
 const WORKSPACE_GC_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS) || 60 * 60 * 1000;
+// Deterministic auto-land (Layer 0): merge clean fast-forwards with no human in
+// the loop. Default on for the seamless workflow; set AGENT_RELAY_WORKSPACE_AUTO_MERGE=0
+// to require a manual or steward merge per repo. Read at call-time so operators can
+// toggle it without a restart.
+const WORKSPACE_AUTO_MERGE_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE_INTERVAL_MS) || CONFLICT_SCAN_INTERVAL_MS;
+// Don't re-wake the managed steward for the same workspace more than once per
+// this window — a persistent conflict/behind row would otherwise re-ping every sweep.
+const STEWARD_WAKE_COOLDOWN_MS = Number(process.env.AGENT_RELAY_STEWARD_WAKE_COOLDOWN_MS) || 10 * 60 * 1000;
 // How long a stranded review_requested/conflict worktree (no online steward) may
 // sit before escalating to the configured fallback target, and the durable
 // escalation target itself (`policy:<name>`, `label:<name>`, `cap:<name>`, an
@@ -68,6 +79,37 @@ const STRANDABLE_STATUSES = new Set<WorkspaceStatus>(["review_requested", "confl
 // in-flight (cleanup_requested) states are skipped.
 const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
 const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["cleaned", "merged", "abandoned"]);
+// In-flight merge statuses that should reconcile to `merged` once the host
+// reports the branch's work has landed in base (squash/cherry-pick, or a merged
+// PR). Excludes active/ready: an agent still working may have landed an early
+// commit while more work is in flight — don't yank its workspace out from under it.
+const LANDED_RECONCILE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "review_requested", "conflict"]);
+
+// Orphaned-session reaper. A spawned agent's process can outlive its relay
+// presence: the relay agent goes offline/pruned but the orchestrator still
+// reports the session's process running, so it lingers forever (visible under the
+// orchestrator, gone from the Agents panel). Runtime-token self-heal recovers the
+// recoverable ones; this is the backstop that stops the genuinely stuck ones.
+// Conservative by design — a session must be observed continuously orphaned by
+// THIS relay for the grace window before it is reaped, and the tracker is in-memory
+// so a relay restart restarts the clock (giving self-heal first crack every time).
+const ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_ORPHAN_REAPER_INTERVAL_MS) || 5 * 60 * 1000;
+// Read at call-time so changes take effect without a restart (and so tests can tune
+// them). Parsed to allow an explicit 0 (immediate) — `|| default` would reject it.
+const envMsOrDefault = (name: string, fallback: number): number => {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v >= 0 ? v : fallback;
+};
+const orphanGraceMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_GRACE_MS", 30 * 60 * 1000);
+const orphanReapCooldownMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_REAP_COOLDOWN_MS", 5 * 60 * 1000);
+// Set AGENT_RELAY_ORPHAN_REAP=0 to detect + log orphans but never stop them.
+const orphanReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_REAP !== "0";
+// orchestratorId + session identity -> when we first saw it orphaned (and last reaped).
+const orphanTracker = new Map<string, { firstOrphanedAt: number; lastReapAt?: number }>();
+
+export function resetOrphanTrackerForTests(): void {
+  orphanTracker.clear();
+}
 
 interface MaintenanceJobDefinition {
   id: string;
@@ -220,6 +262,14 @@ const definitions: MaintenanceJobDefinition[] = [
       return { prunedAgentIds };
     },
   },
+  {
+    id: "orphaned-session-reaper",
+    title: "Orphaned session reaper",
+    description: "Stop spawned sessions whose relay agent is offline/gone but whose process the orchestrator still reports running, after a grace period for self-heal.",
+    intervalMs: ORPHAN_REAPER_INTERVAL_MS,
+    runOnStart: false,
+    handler: reapOrphanedSessions,
+  },
   {
     id: "orchestrator-reaper",
     title: "Orchestrator reaper",
@@ -320,6 +370,15 @@ const definitions: MaintenanceJobDefinition[] = [
     timeoutMs: 60 * 1000,
     handler: scanWorkspaceConflicts,
   },
+  {
+    id: "workspace-auto-merge",
+    title: "Workspace auto-merge",
+    description: "Auto-merge clean fast-forward review_requested worktrees into base under the per-repo lease; conflicts and diverged bases are left for the steward.",
+    intervalMs: WORKSPACE_AUTO_MERGE_INTERVAL_MS,
+    runOnStart: false,
+    timeoutMs: 60 * 1000,
+    handler: autoMergeCleanFastForwards,
+  },
   {
     id: "workspace-gc",
     title: "Workspace GC",
@@ -338,7 +397,7 @@ function workspacePathWithinBase(path: string | undefined, baseDir: string | und
 }
 
 async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord): Promise<WorkspaceMergePreview | { available: false } | null> {
-  const query = new URLSearchParams({ path: workspace.worktreePath });
+  const query = new URLSearchParams({ path: workspace.worktreePath, checkPr: "1" });
   if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
   const headers: Record<string, string> = {};
@@ -357,6 +416,118 @@ async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord)
 // cleanly. Auto-flag `conflict` when a clean merge is no longer possible, and
 // auto-clear conflicts we set ourselves once they resolve (restoring the prior
 // status). Human-set conflicts are never cleared.
+// Stop orphaned spawned sessions: process reported alive by the orchestrator, but
+// the relay agent is offline/pruned and self-heal has had its chance. See the
+// ORPHAN_* notes above. Covers both policy-managed and dashboard/ad-hoc spawns by
+// iterating the orchestrators' reported managedAgents directly.
+function reapOrphanedSessions(): Record<string, unknown> {
+  const now = Date.now();
+  const grace = orphanGraceMs();
+  const cooldown = orphanReapCooldownMs();
+  const reapEnabled = orphanReapEnabled();
+  const seen = new Set<string>();
+  const reaped: string[] = [];
+  let orphaned = 0;
+
+  for (const orch of listOrchestrators()) {
+    if (orch.status !== "online") continue; // can't trust the report or deliver the stop
+    for (const agent of orch.managedAgents) {
+      const sessionId = agent.spawnRequestId || agent.tmuxSession || agent.sessionName || agent.agentId;
+      if (!sessionId) continue;
+      const key = `${orch.id}:${sessionId}`;
+      const relayAgent = agent.agentId ? getAgent(agent.agentId) : null;
+      // Orphan = orchestrator reports the process running, but no live relay agent.
+      // "stale" is a recent/borderline disconnect — treat as alive and give it time;
+      // it will either recover or progress to "offline" and be caught next pass.
+      const isOrphan = !relayAgent || relayAgent.status === "offline";
+      if (!isOrphan) { orphanTracker.delete(key); continue; }
+      seen.add(key);
+      orphaned++;
+      const entry = orphanTracker.get(key) ?? { firstOrphanedAt: now };
+      orphanTracker.set(key, entry);
+      if (now - entry.firstOrphanedAt < grace) continue; // let self-heal recover it first
+      if (!reapEnabled) continue; // detect-only mode
+      if (entry.lastReapAt && now - entry.lastReapAt < cooldown) continue; // don't spam shutdowns
+      entry.lastReapAt = now;
+      const command = createCommand({
+        type: "agent.shutdown",
+        source: "system",
+        target: orch.agentId,
+        correlationId: agent.spawnRequestId,
+        params: {
+          action: "shutdown",
+          agentId: agent.agentId,
+          spawnRequestId: agent.spawnRequestId,
+          sessionName: agent.sessionName,
+          tmuxSession: agent.tmuxSession,
+          policyName: agent.policyName,
+          graceful: false,
+          timeoutMs: 10_000,
+          reason: "orphaned-session-reaper",
+          requestedBy: "orphaned-session-reaper",
+          requestedAt: now,
+          orchestratorId: orch.id,
+        },
+      });
+      emitRelayEvent({ type: "command.requested", source: "system", subject: command.id, data: { command } });
+      createActivityEvent({
+        clientId: `orphaned-session-reaper-${key}-${now}`,
+        kind: "state",
+        title: "Orphaned session reaped",
+        body: `${agent.label ?? agent.agentId ?? sessionId}: process still running on ${orch.id}, but its relay agent has been offline > ${Math.round(grace / 60000)}m and did not self-heal — stopping it`,
+        meta: agent.label ?? agent.agentId ?? sessionId,
+        icon: "ti-ghost",
+        view: "orchestrators",
+        agentId: agent.agentId || undefined,
+        metadata: {
+          source: "server",
+          maintenanceJobId: "orphaned-session-reaper",
+          orchestratorId: orch.id,
+          agentId: agent.agentId,
+          spawnRequestId: agent.spawnRequestId,
+          tmuxSession: agent.tmuxSession,
+          commandId: command.id,
+          orphanAgeMs: now - entry.firstOrphanedAt,
+        },
+      });
+      reaped.push(key);
+    }
+  }
+  // Forget sessions that recovered or are no longer reported, so a future orphaning
+  // of the same session starts a fresh grace window.
+  for (const key of orphanTracker.keys()) if (!seen.has(key)) orphanTracker.delete(key);
+  return { orphaned, reaped, tracked: orphanTracker.size, reapEnabled };
+}
+
+// Wake the managed per-repo steward (issue #167) for a workspace it should handle:
+// auto-provision the policy from global steward config, then queue a `policy:` wake
+// message (which also spawns the on-demand agent now via onMessageForPolicy). Honors a
+// per-workspace cooldown so a persistent conflict/behind row isn't re-pinged every sweep.
+// Returns the steward policy name on a fresh wake, or null (disabled / no owner / cooled down).
+function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
+  const meta = ws.metadata as Record<string, unknown>;
+  const lastWoke = typeof meta.stewardWokenAt === "number" ? meta.stewardWokenAt : 0;
+  if (lastWoke && Date.now() - lastWoke < STEWARD_WAKE_COOLDOWN_MS) return null;
+  const policyName = ensureRepoSteward(ws.repoRoot);
+  if (!policyName) return null;
+  try {
+    const msg = sendMessage({
+      from: "system",
+      to: `policy:${policyName}`,
+      kind: "system",
+      subject: `Steward: ${ws.status} workspace needs attention`,
+      body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, then land it via POST /api/workspaces/${ws.id}/actions {"action":"merge","strategy":"rebase-ff"} — or escalate if you can't.`,
+      payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
+    });
+    emitNewMessage(msg);
+    getLifecycleManager().onMessageForPolicy(policyName);
+    patchWorkspaceMetadata(ws.id, { stewardWokenAt: Date.now(), stewardPolicy: policyName });
+    return policyName;
+  } catch {
+    return null;
+  }
+}
+
 async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
   if (!orchestrators.length) return { scanned: 0, skipped: "no online orchestrators" };
@@ -366,6 +537,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   );
   const flagged: string[] = [];
   const cleared: string[] = [];
+  const merged: string[] = [];
   const notifiedStewards: string[] = [];
 
   for (const ws of candidates) {
@@ -377,6 +549,37 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     if (p.error || p.missing || p.conflict === undefined) continue;
 
     const meta = ws.metadata as Record<string, unknown>;
+
+    // Landing wins over everything else. Once the work is in base — whether the
+    // PR was squash/cherry-pick merged on GitHub or fast-forwarded locally — the
+    // workspace is done, even if `git merge-tree` still predicts a textual
+    // conflict against the now-moved base (a PR-strategy row sits at
+    // merge_planned forever otherwise, and the conflict scan can even pin a
+    // landed branch to `conflict`). Reconcile to the terminal `merged` status so
+    // the dashboard stops showing it as unmerged and GC prunes it on schedule.
+    const landed = p.landed === true || p.prMerged === true;
+    if (landed && LANDED_RECONCILE_STATUSES.has(ws.status)) {
+      updateWorkspaceStatus(ws.id, "merged", {
+        autoMerged: true,
+        mergedFromStatus: ws.status,
+        landedDetectedAt: Date.now(),
+        landedVia: p.prMerged === true ? "pr" : "git",
+        autoConflict: false,
+      });
+      merged.push(ws.id);
+      createActivityEvent({
+        clientId: "server-workspace-" + ws.id + "-merged-" + Date.now(),
+        kind: "state",
+        title: "Workspace work landed in base",
+        body: `${ws.branch ?? ws.id} is ${p.prMerged === true ? "merged on the remote (PR)" : "already merged into base"} ${p.baseRef ? `(${p.baseRef})` : ""} — marking merged`,
+        meta: ws.branch ?? ws.id,
+        icon: "ti-git-merge",
+        view: "orchestrators",
+        metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, fromStatus: ws.status },
+      });
+      continue;
+    }
+
     if (p.conflict === true && ws.status !== "conflict") {
       updateWorkspaceStatus(ws.id, "conflict", {
         autoConflict: true,
@@ -397,10 +600,15 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
         view: "orchestrators",
         metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, ahead: p.ahead, behind: p.behind },
       });
-      // The steward is the repo's coordination point — ping it so a conflict
-      // gets resolved instead of silently rotting until merge time. Once-per-
-      // onset (we only enter this branch on the active→conflict transition).
-      if (ws.stewardAgentId) {
+      // Hand the conflict to a steward so it gets resolved instead of rotting
+      // until merge time. Once-per-onset (we only enter this branch on the
+      // active→conflict transition). When managed stewards are enabled, wake the
+      // auto-provisioned per-repo steward agent (#167); otherwise fall back to the
+      // legacy direct ping of the elected steward agent.
+      if (getStewardConfig().enabled) {
+        const woke = wakeRepoSteward(getWorkspace(ws.id) ?? ws, "conflict");
+        if (woke) notifiedStewards.push(woke);
+      } else if (ws.stewardAgentId) {
         try {
           const msg = sendMessage({
             from: "system",
@@ -425,7 +633,74 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     }
   }
 
-  return { scanned: candidates.length, flagged, cleared, notifiedStewards };
+  return { scanned: candidates.length, flagged, cleared, merged, notifiedStewards };
+}
+
+// Deterministic auto-land (Layer 0, issue #167). Walk the "ready to land" queue
+// (`review_requested` isolated worktrees) and, for any whose work is a strict
+// clean fast-forward (no conflict, base hasn't moved, real commits ahead), land
+// it via the shared merge helper — the same lease-serialized path the merge route
+// uses. Conflicts and diverged bases (`behind>0`, even if cleanly rebasable) are
+// deliberately left for the steward (a human or, later, the managed steward
+// agent): per the chosen "Clean FF immediate" gate, anything needing a rebase or
+// conflict reasoning is not auto-landed. No agent in the loop for the easy case.
+async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
+  if (process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE === "0") return { skipped: "disabled" };
+  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
+  if (!orchestrators.length) return { scanned: 0, skipped: "no online orchestrators" };
+
+  const candidates = listWorkspaces().filter(
+    (ws) => ws.mode === "isolated" && Boolean(ws.worktreePath) && ws.status === "review_requested",
+  );
+  const stewardEnabled = getStewardConfig().enabled;
+  const merged: string[] = [];
+  const heldByLease: string[] = [];
+  const leftForSteward: string[] = [];
+  const wokeStewards: string[] = [];
+
+  for (const ws of candidates) {
+    const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
+    if (!orch?.apiUrl) continue;
+    const preview = await fetchHostMergePreview(orch.apiUrl, ws);
+    if (!preview || (preview as { available?: false }).available === false) continue;
+    const p = preview as WorkspaceMergePreview;
+    if (p.error || p.missing) continue;
+
+    const ahead = p.unmergedAhead ?? p.ahead ?? 0;
+    const cleanFF = p.cleanFastForward === true && p.conflict !== true && (p.behind ?? 0) === 0 && ahead > 0;
+    if (!cleanFF) {
+      // Base moved on (behind>0) or conflict — needs reasoning/rebase, which is the
+      // steward's job. Wake the managed steward when enabled (cooldown-guarded);
+      // otherwise leave it for conflict-scan's legacy ping / human review.
+      leftForSteward.push(ws.id);
+      if (stewardEnabled) {
+        const woke = wakeRepoSteward(ws, (p.behind ?? 0) > 0 ? "base moved on (behind>0)" : "conflict");
+        if (woke) wokeStewards.push(woke);
+      }
+      continue;
+    }
+
+    const result = requestWorkspaceMerge(ws, { strategy: "rebase-ff", requestedBy: "auto-merge" });
+    if (!result.ok) {
+      // 409 = another merge holds this repo's lease this tick; retry next sweep.
+      heldByLease.push(ws.id);
+      continue;
+    }
+    emitCommand(result.command);
+    merged.push(ws.id);
+    createActivityEvent({
+      clientId: `workspace-auto-merge-${ws.id}-${Date.now()}`,
+      kind: "state",
+      title: "Workspace auto-merging (clean fast-forward)",
+      body: `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead, 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, leftForSteward, wokeStewards };
 }
 
 // Send a system DM, swallowing failures (a stale/missing/misconfigured target