agent-relay-server 0.11.6 → 0.11.8

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.11.3",
+    "version": "0.11.4",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",
@@ -3682,6 +3682,35 @@
         ]
       }
     },
+    "/api/workspaces/stewards": {
+      "get": {
+        "operationId": "getWorkspaceStewards",
+        "summary": "List repo stewards and merge leases",
+        "tags": [
+          "Other"
+        ],
+        "description": "Per-repo coordination state for isolated workspaces. Returns `{ stewards, mergeLeases }`. Each steward record (`repoRoot`, `stewardAgentId`, `lastStewardAgentId`, `electedAt`) is persistent — it survives a full all-agents-offline gap (steward goes null/dormant, last-known preserved) and is re-elected when an agent rejoins the repo. Each merge lease (`repoRoot`, `workspaceId`, `commandId`, `holder`, `expiresAt`) marks an in-flight base merge; only one may be held per repo so concurrent merges into base are serialized.",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/workspaces/{id}": {
       "get": {
         "operationId": "getWorkspaceById",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.11.6",
+  "version": "0.11.8",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -39,14 +39,16 @@
     "postinstall": "node scripts/install-bin-shim.cjs",
     "start": "bun run src/index.ts",
     "dev": "bun --watch run src/index.ts",
-    "dev:dashboard": "cd dashboard && npx vite",
+    "dev:dashboard": "cd dashboard && bun run dev",
     "build:sdk": "cd sdk && bun run build",
-    "build:dashboard": "bun run build:sdk && cd dashboard && npx vite build",
+    "build:dashboard": "bun run build:sdk && cd dashboard && bun run build",
     "test": "bun test",
     "smoke:spawn": "bun run scripts/orchestrator-spawn-smoke.ts",
     "typecheck": "tsc --noEmit",
     "docs:api": "bun run scripts/extract-api-spec.ts",
-    "docs:api:check": "bun run scripts/extract-api-spec.ts --check"
+    "docs:api:check": "bun run scripts/extract-api-spec.ts --check",
+    "release": "bun run scripts/release.ts",
+    "publish:ci": "bun run scripts/publish-ci.ts"
   },
   "keywords": [
     "agent-relay",

package/src/config.ts

@@ -24,6 +24,10 @@ export const OFFLINE_PRUNE_MS = envPositiveInt("OFFLINE_PRUNE_MS", DAY_MS); // 2
 export const REAP_INTERVAL_MS = envPositiveInt("REAP_INTERVAL_MS", 60_000); // reaper cadence
 export const CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_CLAIM_LEASE_MS", 1_800_000); // 30min claim lease
 export const POOL_CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_POOL_CLAIM_LEASE_MS", STALE_TTL_MS * 3); // pool binding lease
+// Per-repo merge serialization lease — only one base merge may run at a time per
+// repo. Held from when a workspace.merge command is dispatched until it settles
+// (or this TTL expires, in case the orchestrator never reports back).
+export const WORKSPACE_MERGE_LEASE_MS = envPositiveInt("AGENT_RELAY_WORKSPACE_MERGE_LEASE_MS", 900_000); // 15min
 
 // Max body size for any POST/PATCH request (64 KiB).
 export const MAX_BODY_BYTES = 64 * 1024;

package/src/db.ts

@@ -71,7 +71,7 @@ import type {
   WorkspaceRecord,
   WorkspaceStatus,
 } from "./types";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS } from "./config";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "./config";
 
 let db: Database;
 const CONTEXT_SNAPSHOT_DEBOUNCE_MS = 60_000;
@@ -379,6 +379,31 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_workspaces_owner_agent ON workspaces(owner_agent_id);
     CREATE INDEX IF NOT EXISTS idx_workspaces_policy ON workspaces(owner_policy_name);
 
+    -- Persistent per-repo steward record. Keyed to the repo, not a live agent, so
+    -- it survives a full all-agents-offline gap: steward_agent_id goes NULL
+    -- (dormant) while last_steward_agent_id preserves continuity, and the row is
+    -- re-filled when an agent rejoins the repo. This is the durable backing store
+    -- the steward column on workspace rows mirrors for display/maintenance.
+    CREATE TABLE IF NOT EXISTS repo_stewards (
+      repo_root TEXT PRIMARY KEY,
+      steward_agent_id TEXT,
+      last_steward_agent_id TEXT,
+      elected_at INTEGER,
+      updated_at INTEGER NOT NULL
+    );
+
+    -- Per-repo merge serialization lease. Exactly one base merge may be in flight
+    -- per repo; a second merge request is rejected until the holder settles or the
+    -- lease expires. Atomicity comes from the repo_root PRIMARY KEY + expiry guard.
+    CREATE TABLE IF NOT EXISTS workspace_merge_leases (
+      repo_root TEXT PRIMARY KEY,
+      workspace_id TEXT NOT NULL,
+      command_id TEXT,
+      holder TEXT,
+      acquired_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS tasks (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       source TEXT NOT NULL,
@@ -1692,6 +1717,9 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
   const agent = getAgent(input.id)!;
   if (agent.kind === "channel") upsertChannelForAgent(agent);
   evaluatePoolBindings();
+  // A (re)joining agent may revive a dormant repo steward — re-elect for the
+  // repos it owns live workspaces in (issue #157, steward survives offline gap).
+  if (agent.status !== "offline") electWorkspaceStewardsForAgent(agent.id);
   return agent;
 }
 
@@ -4140,13 +4168,16 @@ function relayConversationId(message: Message): string | undefined {
 }
 
 function isCoveredByLaterAgentResponse(message: Message, agentId: string): boolean {
+  // Order by id, not created_at: ids are monotonic insertion order, so this is
+  // robust when a reply lands in the same millisecond as the message it covers
+  // (created_at > … strictly would miss it, leaving the message wrongly pending).
   const replies = (db.prepare(`
     ${MSG_SELECT}
     WHERE m.from_agent = ?
-      AND m.created_at > ?
-    ORDER BY m.created_at ASC
+      AND m.id > ?
+    ORDER BY m.id ASC
     LIMIT 200
-  `).all(agentId, message.createdAt) as any[]).map(rowToMessage);
+  `).all(agentId, message.id) as any[]).map(rowToMessage);
 
   const conversationId = relayConversationId(message);
   return replies.some((reply) => {
@@ -5108,31 +5139,203 @@ export function updateWorkspaceStatus(id: string, status: WorkspaceStatus, metad
   return getWorkspace(id);
 }
 
+// Workspace statuses that count as "live" for stewardship — an agent owning one
+// of these is a candidate steward; the repo is worth coordinating.
+const STEWARD_LIVE_STATUSES = "'active', 'ready', 'conflict', 'review_requested', 'merge_planned'";
+
+export interface RepoStewardRecord {
+  repoRoot: string;
+  stewardAgentId?: string;
+  lastStewardAgentId?: string;
+  electedAt?: number;
+  updatedAt: number;
+}
+
+function rowToRepoSteward(row: any): RepoStewardRecord {
+  return {
+    repoRoot: row.repo_root,
+    stewardAgentId: row.steward_agent_id ?? undefined,
+    lastStewardAgentId: row.last_steward_agent_id ?? undefined,
+    electedAt: row.elected_at ?? undefined,
+    updatedAt: row.updated_at,
+  };
+}
+
+export function getRepoSteward(repoRoot: string): RepoStewardRecord | null {
+  const row = db.prepare("SELECT * FROM repo_stewards WHERE repo_root = ?").get(repoRoot) as any;
+  return row ? rowToRepoSteward(row) : null;
+}
+
+export function listRepoStewards(): RepoStewardRecord[] {
+  return (db.prepare("SELECT * FROM repo_stewards ORDER BY updated_at DESC").all() as any[]).map(rowToRepoSteward);
+}
+
+// Persist the elected steward for a repo. The row is never deleted, so a repo's
+// stewardship survives a full all-agents-offline gap (steward goes NULL/dormant,
+// last_steward_agent_id keeps continuity) and resumes on the next agent join.
+function upsertRepoSteward(repoRoot: string, steward: string | null, now: number): void {
+  db.prepare(`
+    INSERT INTO repo_stewards (repo_root, steward_agent_id, last_steward_agent_id, elected_at, updated_at)
+    VALUES ($repoRoot, $steward, $steward, $electedAt, $now)
+    ON CONFLICT(repo_root) DO UPDATE SET
+      steward_agent_id = $steward,
+      last_steward_agent_id = coalesce($steward, repo_stewards.last_steward_agent_id),
+      elected_at = CASE
+        WHEN $steward IS NOT NULL AND $steward IS NOT repo_stewards.steward_agent_id THEN $now
+        ELSE repo_stewards.elected_at
+      END,
+      updated_at = $now
+  `).run({ $repoRoot: repoRoot, $steward: steward, $electedAt: steward ? now : null, $now: now });
+}
+
 function electWorkspaceStewards(repoRoot?: string): void {
   const params: string[] = repoRoot ? [repoRoot] : [];
   const repoRows = db.prepare(`
     SELECT DISTINCT repo_root FROM workspaces
-    WHERE status IN ('active', 'ready', 'conflict', 'review_requested', 'merge_planned')
+    WHERE status IN (${STEWARD_LIVE_STATUSES})
     ${repoRoot ? "AND repo_root = ?" : ""}
   `).all(...params) as Array<{ repo_root: string }>;
+  const now = Date.now();
   for (const row of repoRows) {
-    const current = db.prepare(`
-      SELECT steward_agent_id FROM workspaces
-      WHERE repo_root = ? AND steward_agent_id IS NOT NULL AND status IN ('active', 'ready', 'conflict', 'review_requested', 'merge_planned')
-      LIMIT 1
-    `).get(row.repo_root) as { steward_agent_id?: string } | undefined;
-    const currentAgent = current?.steward_agent_id ? getAgent(current.steward_agent_id) : null;
-    const steward = currentAgent && currentAgent.status !== "offline" && current?.steward_agent_id
-      ? current.steward_agent_id
-      : ((db.prepare(`
-          SELECT owner_agent_id FROM workspaces
-          WHERE repo_root = ? AND owner_agent_id IS NOT NULL AND status IN ('active', 'ready', 'conflict', 'review_requested', 'merge_planned')
-          ORDER BY created_at ASC
-          LIMIT 1
-        `).get(row.repo_root) as { owner_agent_id?: string } | undefined)?.owner_agent_id);
-    db.prepare("UPDATE workspaces SET steward_agent_id = ?, updated_at = ? WHERE repo_root = ? AND status IN ('active', 'ready', 'conflict', 'review_requested', 'merge_planned')")
-      .run(steward ?? null, Date.now(), row.repo_root);
+    // Candidate pool: owners of live workspaces in this repo who are online,
+    // oldest first. A steward must be an online agent actively in the repo — an
+    // offline agent can't coordinate, so it is never elected (the old bug).
+    const pool = (db.prepare(`
+      SELECT w.owner_agent_id AS id, MIN(w.created_at) AS created_at
+      FROM workspaces w JOIN agents a ON a.id = w.owner_agent_id
+      WHERE w.repo_root = ? AND w.owner_agent_id IS NOT NULL
+        AND a.status != 'offline' AND w.status IN (${STEWARD_LIVE_STATUSES})
+      GROUP BY w.owner_agent_id
+      ORDER BY created_at ASC
+    `).all(row.repo_root) as Array<{ id: string }>).map((r) => r.id);
+
+    // Keep the current steward if it is still in the pool (stable election);
+    // otherwise promote the oldest online owner, else go dormant (null).
+    const current = getRepoSteward(row.repo_root)?.stewardAgentId ?? null;
+    const steward = (current && pool.includes(current) ? current : pool[0]) ?? null;
+
+    upsertRepoSteward(row.repo_root, steward, now);
+    // Mirror onto live workspace rows only when the steward actually changed, so
+    // re-elections don't churn updated_at and reset the auto-abandon clock for a
+    // dormant repo (a stranded review_requested must still age out).
+    if (steward !== current) {
+      db.prepare(`UPDATE workspaces SET steward_agent_id = ?, updated_at = ? WHERE repo_root = ? AND status IN (${STEWARD_LIVE_STATUSES})`)
+        .run(steward, now, row.repo_root);
+    }
+  }
+}
+
+// Public re-election trigger that does not change any workspace status — used by
+// maintenance to revive a dormant steward (e.g. on the next agent join) before
+// deciding whether a stranded worktree needs escalation.
+export function reelectRepoSteward(repoRoot: string): void {
+  electWorkspaceStewards(repoRoot);
+}
+
+// Merge a metadata patch into a workspace WITHOUT bumping updated_at or running a
+// steward election. For maintenance bookkeeping (stranded/escalation markers)
+// that must not disturb age-based GC timers. undefined values delete keys.
+export function patchWorkspaceMetadata(id: string, patch: Record<string, unknown>): WorkspaceRecord | null {
+  const existing = getWorkspace(id);
+  if (!existing) return null;
+  const next = { ...existing.metadata };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === undefined) delete next[k];
+    else next[k] = v;
   }
+  db.prepare("UPDATE workspaces SET metadata = ? WHERE id = ?").run(JSON.stringify(next), id);
+  return getWorkspace(id);
+}
+
+// Re-elect stewards for every repo where an agent owns a live workspace. Called
+// when an agent (re)registers so a dormant repo regains a steward on rejoin
+// without a full unscoped sweep.
+function electWorkspaceStewardsForAgent(agentId: string): void {
+  const repos = db.prepare(`
+    SELECT DISTINCT repo_root FROM workspaces
+    WHERE owner_agent_id = ? AND status IN (${STEWARD_LIVE_STATUSES})
+  `).all(agentId) as Array<{ repo_root: string }>;
+  for (const r of repos) electWorkspaceStewards(r.repo_root);
+}
+
+// --- Per-repo merge serialization lease (issue #157) -----------------------
+
+export interface MergeLeaseRecord {
+  repoRoot: string;
+  workspaceId: string;
+  commandId?: string;
+  holder?: string;
+  acquiredAt: number;
+  expiresAt: number;
+}
+
+function rowToMergeLease(row: any): MergeLeaseRecord {
+  return {
+    repoRoot: row.repo_root,
+    workspaceId: row.workspace_id,
+    commandId: row.command_id ?? undefined,
+    holder: row.holder ?? undefined,
+    acquiredAt: row.acquired_at,
+    expiresAt: row.expires_at,
+  };
+}
+
+export function getMergeLease(repoRoot: string): MergeLeaseRecord | null {
+  const row = db.prepare("SELECT * FROM workspace_merge_leases WHERE repo_root = ?").get(repoRoot) as any;
+  return row ? rowToMergeLease(row) : null;
+}
+
+export function listMergeLeases(): MergeLeaseRecord[] {
+  return (db.prepare("SELECT * FROM workspace_merge_leases ORDER BY acquired_at DESC").all() as any[]).map(rowToMergeLease);
+}
+
+export function releaseExpiredMergeLeases(now: number = Date.now()): string[] {
+  const expired = db.prepare("SELECT repo_root FROM workspace_merge_leases WHERE expires_at <= ?").all(now) as Array<{ repo_root: string }>;
+  if (!expired.length) return [];
+  db.prepare("DELETE FROM workspace_merge_leases WHERE expires_at <= ?").run(now);
+  return expired.map((r) => r.repo_root);
+}
+
+// Atomically acquire the per-repo merge lease. Succeeds if no live lease is held
+// for the repo (or the existing one has expired). Serialized via db.transaction
+// so two concurrent merge requests for the same repo can't both win.
+export function acquireMergeLease(
+  repoRoot: string,
+  workspaceId: string,
+  holder?: string,
+): { ok: true; lease: MergeLeaseRecord } | { ok: false; lease: MergeLeaseRecord } {
+  return db.transaction(() => {
+    const now = Date.now();
+    const existing = getMergeLease(repoRoot);
+    if (existing && existing.expiresAt > now) return { ok: false as const, lease: existing };
+    const expiresAt = now + WORKSPACE_MERGE_LEASE_MS;
+    db.prepare(`
+      INSERT INTO workspace_merge_leases (repo_root, workspace_id, command_id, holder, acquired_at, expires_at)
+      VALUES (?, ?, NULL, ?, ?, ?)
+      ON CONFLICT(repo_root) DO UPDATE SET
+        workspace_id = excluded.workspace_id, command_id = NULL, holder = excluded.holder,
+        acquired_at = excluded.acquired_at, expires_at = excluded.expires_at
+    `).run(repoRoot, workspaceId, holder ?? null, now, expiresAt);
+    return { ok: true as const, lease: getMergeLease(repoRoot)! };
+  })();
+}
+
+// Attach the dispatched command id to a held lease so it can be released by
+// command id when the merge settles.
+export function setMergeLeaseCommand(repoRoot: string, commandId: string): void {
+  db.prepare("UPDATE workspace_merge_leases SET command_id = ? WHERE repo_root = ?").run(commandId, repoRoot);
+}
+
+// Release a merge lease. Guard by commandId/workspaceId when known so a stale
+// release can't drop a newer lease for the same repo.
+export function releaseMergeLease(opts: { repoRoot?: string; commandId?: string; workspaceId?: string }): boolean {
+  const where: string[] = [];
+  const params: string[] = [];
+  if (opts.repoRoot) { where.push("repo_root = ?"); params.push(opts.repoRoot); }
+  if (opts.commandId) { where.push("command_id = ?"); params.push(opts.commandId); }
+  if (opts.workspaceId) { where.push("workspace_id = ?"); params.push(opts.workspaceId); }
+  if (!where.length) return false;
+  return db.prepare(`DELETE FROM workspace_merge_leases WHERE ${where.join(" AND ")}`).run(...params).changes > 0;
 }
 
 export function deleteOrchestrator(id: string): boolean {

package/src/maintenance.ts

@@ -9,16 +9,22 @@ import {
   createActivityEvent,
   evaluatePoolBindings,
   expireQueuedMessages,
+  getAgent,
   getDb,
+  getRepoSteward,
+  getWorkspace,
   listOrchestrators,
   listWorkspaces,
+  patchWorkspaceMetadata,
   pruneOfflineAgents,
   pruneOldMessages,
   deleteWorkspace,
   pruneOrphanedSharedWorkspaces,
   reapStaleAgents,
   reapStaleOrchestrators,
+  reelectRepoSteward,
   releaseExpiredClaims,
+  releaseExpiredMergeLeases,
   releaseOrphanedTasks,
   sendMessage,
   sweepArtifacts,
@@ -49,6 +55,15 @@ 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;
+// 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
+// agent id, or `broadcast`). Read at call-time so config changes take effect
+// without a restart (issue #157).
+const stewardEscalationMs = () => Number(process.env.AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS) || 60 * 60 * 1000;
+const stewardFallbackTarget = () => (process.env.AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK || "").trim();
+// Statuses that need an owner — a stranded one of these is what escalation rescues.
+const STRANDABLE_STATUSES = new Set<WorkspaceStatus>(["review_requested", "conflict"]);
 // Live statuses worth scanning. Terminal (cleaned/merged/abandoned) and
 // in-flight (cleanup_requested) states are skipped.
 const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
@@ -413,11 +428,27 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   return { scanned: candidates.length, flagged, cleared, notifiedStewards };
 }
 
+// Send a system DM, swallowing failures (a stale/missing/misconfigured target
+// must never break the GC sweep). Returns the target on success, null otherwise.
+function notifyTarget(target: string, subject: string, body: string, payload: Record<string, unknown>): string | null {
+  if (!target) return null;
+  try {
+    emitNewMessage(sendMessage({ from: "system", to: target, kind: "system", subject, body, payload }));
+    return target;
+  } catch {
+    return null;
+  }
+}
+
 async function workspaceGC(): Promise<Record<string, unknown>> {
   const now = Date.now();
   const cutoff = now - WORKSPACE_RETENTION_MS;
   const reviewCutoff = now - WORKSPACE_REVIEW_TTL_MS;
 
+  // 0. Free any merge leases whose holder never reported back (orchestrator died
+  // mid-merge). The lease TTL is the safety net; this just reclaims them eagerly.
+  const releasedLeaseRepos = releaseExpiredMergeLeases(now);
+
   // 1. Prune terminal rows past retention
   const all = listWorkspaces();
   const terminalIds: string[] = [];
@@ -428,29 +459,84 @@ async function workspaceGC(): Promise<Record<string, unknown>> {
     }
   }
 
-  // 2. Auto-abandon stale review_requested worktrees
+  // 2. Rescue stranded review_requested/conflict worktrees (issue #157). A
+  // worktree is "stranded" when its steward is gone (all repo agents offline).
+  // Re-elect first — an agent may have rejoined — and hand off to the new
+  // steward; if none can be elected past the TTL, escalate to the fallback
+  // target so it never rots in silence. Bookkeeping uses patchWorkspaceMetadata
+  // (no updated_at bump) so the auto-abandon clock below keeps ticking.
+  const escalatedIds: string[] = [];
+  const reassignedIds: string[] = [];
+  const escalationTargets: string[] = [];
+  const escalationMs = stewardEscalationMs();
+  const fallbackTarget = stewardFallbackTarget();
+  for (const ws of all) {
+    if (!STRANDABLE_STATUSES.has(ws.status) || ws.mode !== "isolated" || !ws.worktreePath) continue;
+    reelectRepoSteward(ws.repoRoot);
+    const fresh = getWorkspace(ws.id);
+    if (!fresh || !STRANDABLE_STATUSES.has(fresh.status)) continue;
+    const meta = fresh.metadata as Record<string, unknown>;
+    const steward = fresh.stewardAgentId;
+    const stewardOnline = Boolean(steward && getAgent(steward) && getAgent(steward)!.status !== "offline");
+    const strandedAt = typeof meta.strandedAt === "number" ? meta.strandedAt : undefined;
+
+    if (stewardOnline) {
+      // An online steward owns it. If it was previously stranded and this
+      // steward hasn't been told, hand it off explicitly, then clear markers.
+      if (strandedAt !== undefined && meta.strandedNotifiedSteward !== steward) {
+        const sent = notifyTarget(
+          steward!,
+          "Workspace stewardship reassigned",
+          `You are now steward for ${fresh.repoRoot}. Workspace \`${fresh.branch ?? fresh.id}\` is ${fresh.status} and was stranded without an online steward — please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"}.`,
+          { kind: "workspace.steward-reassigned", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status },
+        );
+        if (sent) reassignedIds.push(fresh.id);
+      }
+      patchWorkspaceMetadata(fresh.id, { strandedAt: undefined, escalatedAt: undefined, strandedNotifiedSteward: steward });
+      continue;
+    }
+
+    // Stranded: no online steward could be elected.
+    if (strandedAt === undefined) { patchWorkspaceMetadata(fresh.id, { strandedAt: now }); continue; }
+    if (now - strandedAt < escalationMs || meta.escalatedAt) continue;
+    const sent = notifyTarget(
+      fallbackTarget,
+      "Stranded workspace needs an owner",
+      `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} with no online steward (all repo agents offline) for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h. Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
+      { kind: "workspace.stranded-escalation", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status, strandedAt },
+    );
+    if (sent) escalationTargets.push(sent);
+    patchWorkspaceMetadata(fresh.id, { escalatedAt: now });
+    escalatedIds.push(fresh.id);
+    createActivityEvent({
+      clientId: `workspace-gc-escalate-${fresh.id}-${now}`,
+      kind: "state",
+      title: "Workspace escalated",
+      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} — stranded ${fresh.status} escalated${fallbackTarget ? ` to ${fallbackTarget}` : " (no fallback configured)"}`,
+      meta: fresh.branch ?? fresh.id,
+      icon: "ti-alert-octagon",
+      view: "orchestrators",
+      metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id, fallback: fallbackTarget || null },
+    });
+  }
+
+  // 3. Auto-abandon stale review_requested worktrees
   const abandonedIds: string[] = [];
   const notifiedStewards: string[] = [];
   for (const ws of all) {
     if (ws.status === "review_requested" && ws.updatedAt < reviewCutoff) {
       updateWorkspaceStatus(ws.id, "abandoned", { autoAbandoned: true, abandonedReason: "review_requested TTL exceeded", abandonedAt: now });
       abandonedIds.push(ws.id);
-      if (ws.stewardAgentId) {
-        try {
-          const msg = sendMessage({
-            from: "system",
-            to: ws.stewardAgentId,
-            kind: "system",
-            subject: "Workspace auto-abandoned",
-            body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d without steward action. Run workspace cleanup to reclaim the worktree.`,
-            payload: { kind: "workspace.auto-abandoned", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch },
-          });
-          emitNewMessage(msg);
-          notifiedStewards.push(ws.stewardAgentId);
-        } catch {
-          // Steward gone — activity event is enough.
-        }
-      }
+      // Notify the steward if one exists, else the configured fallback so a
+      // stranded abandon isn't silent (issue #157).
+      const target = ws.stewardAgentId ?? fallbackTarget;
+      const sent = notifyTarget(
+        target,
+        "Workspace auto-abandoned",
+        `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d without steward action. Run workspace cleanup to reclaim the worktree.`,
+        { kind: "workspace.auto-abandoned", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch },
+      );
+      if (sent) notifiedStewards.push(sent);
       createActivityEvent({
         clientId: `workspace-gc-abandon-${ws.id}-${now}`,
         kind: "state",
@@ -483,7 +569,16 @@ async function workspaceGC(): Promise<Record<string, unknown>> {
     pruneCommands.push(command.id);
   }
 
-  return { prunedTerminal: terminalIds, autoAbandoned: abandonedIds, notifiedStewards, pruneCommands };
+  return {
+    prunedTerminal: terminalIds,
+    autoAbandoned: abandonedIds,
+    notifiedStewards,
+    pruneCommands,
+    releasedLeaseRepos,
+    escalated: escalatedIds,
+    reassigned: reassignedIds,
+    escalationTargets,
+  };
 }
 
 let timer: Timer | null = null;

package/src/routes.ts

@@ -85,6 +85,11 @@ import {
   getWorkspace,
   listWorkspaces,
   updateWorkspaceStatus,
+  acquireMergeLease,
+  setMergeLeaseCommand,
+  releaseMergeLease,
+  listRepoStewards,
+  listMergeLeases,
   deleteWorkspace,
   deleteOrchestrator,
   evaluatePoolBindings,
@@ -3799,6 +3804,10 @@ const getWorkspaceById: Handler = (_req, params) => {
   return json(workspace);
 };
 
+// Per-repo coordination state: persistent steward records (survive offline gaps)
+// and in-flight merge serialization leases (issue #157).
+const getWorkspaceStewards: Handler = () => json({ stewards: listRepoStewards(), mergeLeases: listMergeLeases() });
+
 // Proxy a read-only workspace interrogation to the owning orchestrator's host
 // API. Degrades to { available: false } rather than erroring so the dashboard
 // can render a placeholder when the host is offline or there's no worktree.
@@ -3931,6 +3940,7 @@ const postWorkspaceOrphanReclaim: Handler = async (req) => {
 const postWorkspaceAction: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
+  let mergeLeaseRepo: string | undefined;
   try {
     if (!isRecord(parsed.body)) return error("body required");
     const workspace = getWorkspace(params.id!);
@@ -3949,6 +3959,18 @@ const postWorkspaceAction: Handler = async (req, params) => {
     const denied = authorizeRoute(req, { scope: requiresCommand ? "command:write" : "agent:write", resource: { agentId, cwd: workspace.worktreePath } });
     if (denied) return denied;
     if (action === "status") return json(workspace);
+    // Serialize base merges per repo: acquire the merge lease BEFORE mutating
+    // status so a losing request leaves the workspace untouched (issue #157).
+    if (action === "merge") {
+      const lease = acquireMergeLease(workspace.repoRoot, workspace.id, agentId ?? "dashboard");
+      if (!lease.ok) {
+        return error(
+          `a merge is already in progress for ${workspace.repoRoot} (workspace ${lease.lease.workspaceId}); retry after it settles`,
+          409,
+        );
+      }
+      mergeLeaseRepo = workspace.repoRoot;
+    }
     const statusByAction: Record<string, WorkspaceStatus | undefined> = {
       status: undefined,
       ready: "ready",
@@ -3982,7 +4004,11 @@ const postWorkspaceAction: Handler = async (req, params) => {
       };
       if (action === "merge") {
         // Merge needs a live host: rebasing against a stale base later is unsafe.
-        if (!onlineOwner) return error("no online orchestrator available for workspace merge", 409);
+        if (!onlineOwner) {
+          releaseMergeLease({ repoRoot: workspace.repoRoot, workspaceId: workspace.id });
+          mergeLeaseRepo = undefined;
+          return error("no online orchestrator available for workspace merge", 409);
+        }
         const strategy = cleanEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto");
         command = createCommand({
           type: "workspace.merge",
@@ -4014,6 +4040,9 @@ const postWorkspaceAction: Handler = async (req, params) => {
           params: { action: "cleanup", ...baseParams, deleteBranch: true, queued: owner.status !== "online" },
         });
       }
+      // Bind the lease to the dispatched merge command so it's released by id
+      // when the command settles (postCommandResult).
+      if (action === "merge" && mergeLeaseRepo) setMergeLeaseCommand(mergeLeaseRepo, command.id);
       emitCommand(command);
     }
     auditEvent({
@@ -4029,6 +4058,9 @@ const postWorkspaceAction: Handler = async (req, params) => {
     });
     return json({ workspace: updated, command }, requiresCommand ? 202 : 200);
   } catch (e) {
+    // A merge that acquired the lease but failed before dispatch must release it,
+    // or the repo stays blocked until the TTL expires.
+    if (mergeLeaseRepo) releaseMergeLease({ repoRoot: mergeLeaseRepo });
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
   }
@@ -4336,6 +4368,11 @@ const patchCommand: Handler = async (req, params) => {
       }
     }
     if (command.type === "workspace.merge") {
+      // Merge settled (either way) — free the per-repo merge lease so the next
+      // base merge can proceed (issue #157).
+      if (command.status === "succeeded" || command.status === "failed") {
+        releaseMergeLease({ commandId: command.id });
+      }
       if (command.status === "succeeded" && isRecord(command.result)) {
         const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
         const resultStatus = cleanEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
@@ -6259,6 +6296,7 @@ const routes: Route[] = [
   // Static segments before :id so "/workspaces/orphans" isn't captured as an id.
   route("GET", "/api/workspaces/orphans", getWorkspaceOrphans),
   route("POST", "/api/workspaces/orphans/reclaim", postWorkspaceOrphanReclaim),
+  route("GET", "/api/workspaces/stewards", getWorkspaceStewards),
   route("GET", "/api/workspaces/:id", getWorkspaceById),
   route("GET", "/api/workspaces/:id/git-state", getWorkspaceGitState),
   route("GET", "/api/workspaces/:id/merge-preview", getWorkspaceMergePreview),