agent-relay-server 0.120.0 → 0.120.2

package/src/sse.ts

@@ -11,20 +11,27 @@ interface Connection {
   agentId: string | null;
   controller: ReadableStreamDefaultController<Uint8Array>;
   keepalive: Timer;
-  // Pending cross-tick backpressure re-check (#971 refinement). Set when a stream
-  // dips below the queue floor during a synchronous fanout; cleared on the deferred
-  // tick once we know whether it drained (healthy) or stayed stuck (stale → drop).
+  queuedBytes: number;
+  // Pending backpressure re-check. Set when a stream crosses the byte floor; cleared
+  // once it drains or is closed after making no progress during the grace interval.
   drainCheck?: Timer;
+  drainCheckDesiredSize?: number | null;
 }
 
 const connections = new Map<string, Connection>();
 const encoder = new TextEncoder();
 const SSE_KEEPALIVE_MS = 15_000;
 const SSE_RETRY_MS = 5_000;
-const SSE_MAX_QUEUED_CHUNKS = 128;
+const SSE_MAX_QUEUED_BYTES = 1024 * 1024;
+const SSE_DRAIN_GRACE_MS = 2_000;
 
 subscribeRelayEvents((event) => fanout(event));
 
+function fanoutAgent(agentId: string, cache: Map<string, AgentCard | null>): AgentCard | null {
+  if (!cache.has(agentId)) cache.set(agentId, getAgent(agentId));
+  return cache.get(agentId) ?? null;
+}
+
 // #797 — let the db layer derive outbound-channel liveness from live SSE subscriptions.
 // A channel agent is "subscribed" iff the channels-host daemon holds an open
 // GET /api/events?for=<channelAgentId> stream (createSSEStream stores `for` as agentId).
@@ -48,7 +55,7 @@ export function createSSEStream(agentId: string | null): Response {
         sendEncoded(conn, encoder.encode(": keepalive\n\n"));
       }, SSE_KEEPALIVE_MS);
 
-      connections.set(connId, { id: connId, agentId, controller, keepalive });
+      connections.set(connId, { id: connId, agentId, controller, keepalive, queuedBytes: 0 });
 
       controller.enqueue(encoder.encode(
         `retry: ${SSE_RETRY_MS}\nevent: connected\ndata: ${JSON.stringify({ connectionId: connId })}\n\n`
@@ -90,7 +97,7 @@ function sseFrame(event: string, data: unknown): Uint8Array {
 }
 
 function isBackpressured(conn: Connection): boolean {
-  return conn.controller.desiredSize !== null && conn.controller.desiredSize < -SSE_MAX_QUEUED_CHUNKS;
+  return conn.queuedBytes >= SSE_MAX_QUEUED_BYTES && conn.controller.desiredSize !== null && conn.controller.desiredSize < 0;
 }
 
 function sendEncoded(conn: Connection, chunk: Uint8Array) {
@@ -101,26 +108,36 @@ function sendEncoded(conn: Connection, chunk: Uint8Array) {
     removeConnection(conn.id);
     return;
   }
-  // #971 — the queue only drains between event-loop ticks, so within a single
-  // synchronous fanout (a batch loop emitting >SSE_MAX_QUEUED_CHUNKS frames)
-  // desiredSize falls on liveness, not staleness. Closing inline here would kill
-  // healthy, actively-read dashboards mid-burst. Instead defer the verdict: mark
-  // the stream and re-check on a later tick, after the runtime has had a chance to
-  // flush to the socket. Recovered → keep it; still stuck across ticks → drop it.
+  if (conn.controller.desiredSize !== null && conn.controller.desiredSize >= 0) conn.queuedBytes = 0;
+  else conn.queuedBytes += chunk.byteLength;
   if (isBackpressured(conn)) scheduleDrainCheck(conn);
 }
 
 function scheduleDrainCheck(conn: Connection) {
   if (conn.drainCheck) return; // one deferred verdict per stream is enough
+  conn.drainCheckDesiredSize = conn.controller.desiredSize;
   conn.drainCheck = setTimeout(() => {
     conn.drainCheck = undefined;
-    // The connection may already have been removed (cancel/close) between ticks —
+    // The connection may already have been removed (cancel/close) during the grace —
     // closeConnection is idempotent, but bail early so we never touch a stale ref.
     if (connections.get(conn.id) !== conn) return;
-    // Drained across the tick → genuinely healthy-but-slow. Stayed backpressured →
-    // genuinely stalled/stale; drop it (the original #971 protection).
+    const desiredSize = conn.controller.desiredSize;
+    if (desiredSize !== null && desiredSize >= 0) {
+      conn.queuedBytes = 0;
+      conn.drainCheckDesiredSize = undefined;
+      return;
+    }
+    const improved = desiredSize !== null
+      && conn.drainCheckDesiredSize !== null
+      && conn.drainCheckDesiredSize !== undefined
+      && desiredSize > conn.drainCheckDesiredSize;
+    conn.drainCheckDesiredSize = undefined;
+    if (improved) {
+      scheduleDrainCheck(conn);
+      return;
+    }
     if (isBackpressured(conn)) closeConnection(conn.id);
-  }, 0);
+  }, SSE_DRAIN_GRACE_MS);
 }
 
 function send(conn: Connection, event: string, data: unknown) {
@@ -147,13 +164,14 @@ function sendNewMessage(msg: Message): void {
     ? new Set(matchingDeliveryAgents("broadcast", { from: msg.from, channel: msg.channel }).map((agent) => agent.id))
     : null;
   const chunk = sseFrame("message.new", msg);
+  const agentCache = new Map<string, AgentCard | null>();
   for (const conn of connections.values()) {
     if (!conn.agentId) {
       sendEncoded(conn, chunk);
       continue;
     }
     if (scopedBroadcastAgentIds && !scopedBroadcastAgentIds.has(conn.agentId)) continue;
-    if (!messageMatchesAgent(msg, conn.agentId, getAgent(conn.agentId))) continue;
+    if (!messageMatchesAgent(msg, conn.agentId, fanoutAgent(conn.agentId, agentCache))) continue;
     sendEncoded(conn, chunk);
   }
 }
@@ -263,8 +281,9 @@ export function emitMessageReactionUpdated(msg: Message) {
 
 function sendTaskChanged(task: Task, eventType = "task.updated"): void {
   const chunk = sseFrame(eventType, task);
+  const agentCache = new Map<string, AgentCard | null>();
   for (const conn of connections.values()) {
-    if (conn.agentId && !targetMatchesAgent(task.target, conn.agentId, getAgent(conn.agentId))) continue;
+    if (conn.agentId && !targetMatchesAgent(task.target, conn.agentId, fanoutAgent(conn.agentId, agentCache))) continue;
     sendEncoded(conn, chunk);
   }
 }

package/src/steward.ts

@@ -12,10 +12,11 @@ import type { Orchestrator, SpawnPolicy, StewardConfig } from "./types";
 import { isPathWithinBase } from "./utils";
 
 /** Stable, readable, collision-resistant policy name for a repo's steward. */
-export function repoStewardPolicyName(repoRoot: string): string {
+export function repoStewardPolicyName(repoRoot: string, orchestratorId?: string): string {
   const slug = basename(repoRoot).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "repo";
   const hash = createHash("sha1").update(resolve(repoRoot)).digest("hex").slice(0, 8);
-  return `steward-${slug}-${hash}`;
+  const owner = orchestratorId?.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return owner ? `steward-${slug}-${hash}-${owner}` : `steward-${slug}-${hash}`;
 }
 
 /**
@@ -54,7 +55,7 @@ function desiredStewardPolicy(repoRoot: string, owner: Orchestrator, config: Ste
   const resolved = resolveInternalSpawnTarget("landing-steward", pin);
 
   return {
-    name: repoStewardPolicyName(repoRoot),
+    name: repoStewardPolicyName(repoRoot, owner.id),
     description: `Autonomous repo steward for ${repoRoot} (issue #167).`,
     enabled: true,
     orchestratorId: owner.id,
@@ -118,13 +119,16 @@ function stewardPolicyDiffers(existing: SpawnPolicy, desired: SpawnPolicy): bool
  * owns the repo. Idempotent — refreshes the policy only when config-derived fields
  * change, so it can be called on every sweep without churn.
  */
-export function ensureRepoSteward(repoRoot: string): string | null {
+export function ensureRepoSteward(repoRoot: string, owningOrchestrator?: Orchestrator): string | null {
   const config = getStewardConfig();
   if (!config.enabled) return null;
-  const owner = listOrchestrators().find((orch) => isPathWithinBase(repoRoot, orch.baseDir));
+  const owner = owningOrchestrator ?? listOrchestrators().find((orch) =>
+    orch.status === "online" && isPathWithinBase(repoRoot, orch.baseDir)
+  );
+  if (owner && (owner.status !== "online" || !isPathWithinBase(repoRoot, owner.baseDir))) return null;
   if (!owner) return null;
 
-  const name = repoStewardPolicyName(repoRoot);
+  const name = repoStewardPolicyName(repoRoot, owner.id);
   const desired = desiredStewardPolicy(repoRoot, owner, config);
   const existing = getSpawnPolicy(name);
   if (existing && !stewardPolicyDiffers(existing.value, desired)) return name;

package/src/terminal-authz.ts

@@ -0,0 +1,50 @@
+import { getOrchestrator } from "./db";
+import { getIntegrationAuth, isFullReachRequest, isRequestAuthorizedFor } from "./security";
+
+type TerminalAccessMode = "read" | "write";
+
+interface TerminalOwner {
+  agentId: string;
+  policyName?: string;
+  spawnRequestId?: string;
+}
+
+function hasPresentedCredential(req: Request): boolean {
+  return Boolean(req.headers.get("authorization") || req.headers.get("x-agent-relay-token") || new URL(req.url).searchParams.get("token"));
+}
+
+function terminalOwner(orchestratorId: string, session: string): TerminalOwner | null {
+  const orch = getOrchestrator(orchestratorId);
+  if (!orch) return null;
+  for (const agent of orch.managedAgents ?? []) {
+    const sessions = [agent.terminalSession, agent.tmuxSession, agent.sessionName].filter((value): value is string => typeof value === "string" && value.length > 0);
+    if (!sessions.includes(session)) continue;
+    if (!agent.agentId) return null;
+    return {
+      agentId: agent.agentId,
+      ...(agent.policyName ? { policyName: agent.policyName } : {}),
+      ...(agent.spawnRequestId ? { spawnRequestId: agent.spawnRequestId } : {}),
+    };
+  }
+  return null;
+}
+
+export function isTerminalSessionRequestAuthorized(req: Request, orchestratorId: string, session: string, mode: TerminalAccessMode): boolean {
+  if (!hasPresentedCredential(req)) return true;
+  if (isFullReachRequest(req)) return true;
+  if (getIntegrationAuth(req)) return false;
+  const owner = terminalOwner(orchestratorId, session);
+  if (!owner) return false;
+  const terminalCapability = mode === "read" ? { terminalRead: true } : { terminalWrite: true };
+  return isRequestAuthorizedFor(req, {
+    scope: mode === "read" ? "terminal:read" : "terminal:write",
+    resource: {
+      orchestratorId,
+      agentId: owner.agentId,
+      policyName: owner.policyName,
+      spawnRequestId: owner.spawnRequestId,
+      terminalOwner: true,
+      ...terminalCapability,
+    },
+  });
+}

package/src/token-db.ts

@@ -67,8 +67,8 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Orchestrator Host",
     description: "Host supervisor access for spawn, command, log, and terminal operations.",
     role: "orchestrator",
-    scope: ["agent:read", "agent:write", "command:read", "command:write", "task:read", "task:write", "logs:read", "terminal:attach", "quota:write", "provisioning:read"],
-    constraints: { logsRead: true, terminalAttach: true },
+    scope: ["agent:read", "agent:write", "command:read", "command:write", "task:read", "task:write", "logs:read", "terminal:attach", "terminal:read", "terminal:write", "quota:write", "provisioning:read"],
+    constraints: { logsRead: true, terminalAttach: true, terminalRead: true, terminalWrite: true },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -100,7 +100,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
     scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "channel:egress", "insights:write", "quota:write"],
-    constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
+    constraints: { terminalAttach: false, terminalRead: false, terminalWrite: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",

package/src/validation.ts

@@ -109,7 +109,7 @@ export function cleanTokenConstraints(value: unknown): TokenConstraints | undefi
   if (teamId) constraints.teamId = teamId;
   const tenantId = cleanString(value.tenantId, "constraints.tenantId", { max: 120 });
   if (tenantId) constraints.tenantId = tenantId;
-  for (const key of ["terminalAttach", "logsRead", "canDelegate"] as const) {
+  for (const key of ["terminalAttach", "terminalRead", "terminalWrite", "logsRead", "canDelegate"] as const) {
     if (value[key] !== undefined) {
       if (typeof value[key] !== "boolean") throw new ValidationError(`constraints.${key} must be a boolean`);
       constraints[key] = value[key];

package/src/workspace-actions.ts

@@ -26,8 +26,9 @@ import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
 // tuple as the HTTP route without a second import hop (one source: workspace-merge, #304).
 export { LAND_STRATEGIES, DEFAULT_MERGE_STRATEGY } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
-import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES, worktreeReapable } from "./workspace-phase";
 import { CLEAR_MERGE_NO_PROGRESS, scheduleRepoMerge } from "./workspace-auto-merge";
+import { fetchHostMergePreview } from "./workspace-probe";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
@@ -129,7 +130,28 @@ function recordWorkspaceAudit(a: {
   }
 }
 
-export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWorkspaceActionInput): WorkspaceActionResult {
+function metadataNumber(metadata: Record<string, unknown>, key: string): number | undefined {
+  const value = metadata[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+async function cleanupWorkSafety(workspace: WorkspaceRecord): Promise<{ ok: true } | { ok: false; error: string }> {
+  const owner = workspaceOwnerOrchestrator(workspace, listOrchestrators(), { requireApiUrl: true });
+  if (!owner?.apiUrl) return { ok: false, error: "owning orchestrator unavailable for cleanup safety probe" };
+  const preview = await fetchHostMergePreview(owner.apiUrl, workspace, { checkPr: false });
+  if (!preview) return { ok: false, error: "cleanup safety probe unavailable" };
+  if ("available" in preview && preview.available === false) return { ok: false, error: "cleanup safety probe unavailable" };
+  const p = preview as Exclude<typeof preview, { available: false }>;
+  if (p.missing) return { ok: true };
+  if (p.error) return { ok: false, error: `cleanup safety probe error: ${p.error}` };
+  if (worktreeReapable({ landed: p.landed, ahead: p.ahead, unmergedAhead: p.unmergedAhead, dirtyCount: p.dirtyCount })) return { ok: true };
+  const dirtyCount = p.dirtyCount ?? 0;
+  if (dirtyCount > 0) return { ok: false, error: `${dirtyCount} uncommitted change(s)` };
+  const ahead = p.unmergedAhead ?? p.ahead ?? 0;
+  return { ok: false, error: `${ahead} unlanded commit(s)` };
+}
+
+export async function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWorkspaceActionInput): Promise<WorkspaceActionResult> {
   const { action } = input;
   const agentId = input.agentId;
   const detail = input.detail;
@@ -228,6 +250,17 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   const nextStatus = STATUS_BY_ACTION[action];
   if (!nextStatus) return { ok: false, httpStatus: 400, error: `unsupported action: ${action}` };
 
+  if (READY_TO_LAND_STATUSES.has(nextStatus)) {
+    const dirtyCount = metadataNumber(workspace.metadata, "gitDirtyCount") ?? 0;
+    if (dirtyCount > 0) {
+      return {
+        ok: false,
+        httpStatus: 409,
+        error: `workspace ${workspace.id} cannot be marked ${nextStatus}: ${DIRTY_WORKTREE_LAND_SKIP_REASON} (${dirtyCount} dirty file${dirtyCount === 1 ? "" : "s"}); commit or stash first`,
+      };
+    }
+  }
+
   if (
     action === "cleanup" &&
     input.force !== true &&
@@ -245,7 +278,15 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   let command: Command | undefined;
   if (requiresCommand) {
     // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", { force: input.force === true });
+    const safety = await cleanupWorkSafety(workspace);
+    if (!safety.ok && !(input.force === true && Boolean(detail?.trim()))) {
+      return {
+        ok: false,
+        httpStatus: 409,
+        error: `workspace ${workspace.id} cannot be cleaned up safely: ${safety.error}; pass force:true with a detail reason only if intentionally discarding work`,
+      };
+    }
+    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", { force: input.force === true, reason: detail });
     if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
     command = built.command;
   }
@@ -287,7 +328,7 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
 export function buildWorkspaceCleanupCommand(
   workspace: WorkspaceRecord,
   requestedBy: string,
-  opts: { force?: boolean } = {},
+  opts: { force?: boolean; reason?: string } = {},
 ): { ok: true; command: Command } | { ok: false; status: number; error: string } {
   if (
     opts.force !== true &&
@@ -319,6 +360,7 @@ export function buildWorkspaceCleanupCommand(
       requestedBy,
       requestedAt: Date.now(),
       deleteBranch: true,
+      ...(opts.force === true && opts.reason ? { force: true, reason: opts.reason } : {}),
       queued: false,
     },
   });

package/src/workspace-auto-merge.ts

@@ -36,11 +36,14 @@ import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
 import { emitWorkspaceTaskSemanticNotifications } from "./services/task-lifecycle";
 import { ensureRepoSteward } from "./steward";
 import { requestWorkspaceMerge, workspaceMergeOrchestrators } from "./workspace-merge";
+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 { 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;
@@ -52,6 +55,21 @@ type AutoMergeRequestOptions = {
   reviewer?: string;
 };
 
+function stewardOwnerForWorkspace(ws: WorkspaceRecord): { owner: Orchestrator } | { error: string } {
+  const orchestrators = listOrchestrators();
+  if (ws.orchestratorId) {
+    const owner = orchestrators.find((orch) => orch.id === ws.orchestratorId);
+    if (!owner) return { error: `cannot spawn steward: owning host ${ws.orchestratorId} is not registered` };
+    if (owner.status !== "online") return { error: `cannot spawn steward: owning host ${owner.id} is ${owner.status}` };
+    if (!isPathWithinBase(ws.worktreePath, owner.baseDir)) {
+      return { error: `cannot spawn steward: worktree is not on owning host ${owner.id}` };
+    }
+    return { owner };
+  }
+  const owner = workspaceOwnerOrchestrator(ws, orchestrators, { requireApiUrl: true });
+  return owner ? { owner } : { error: "cannot spawn steward: no online owner for workspace host path" };
+}
+
 function workspaceLandStrategy(metadata: Record<string, unknown>): WorkspaceLandingPolicy | undefined {
   const value = metadata.landStrategy;
   return typeof value === "string" && (WORKSPACE_LAND_STRATEGIES as readonly string[]).includes(value)
@@ -91,8 +109,8 @@ function autoMergeRequestOptions(ws: WorkspaceRecord): AutoMergeRequestOptions {
 
 // 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.
-// 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
+// Wake the managed per-host/repo steward (issue #167/#977) for a workspace it should handle:
+// auto-provision the policy on the workspace-owning host, 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).
@@ -100,8 +118,16 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
   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;
+  const ownerResult = stewardOwnerForWorkspace(ws);
+  if ("error" in ownerResult) {
+    patchWorkspaceMetadata(ws.id, { stewardWakeError: ownerResult.error, stewardWakeErrorAt: Date.now() });
+    return null;
+  }
+  const policyName = ensureRepoSteward(ws.repoRoot, ownerResult.owner);
+  if (!policyName) {
+    patchWorkspaceMetadata(ws.id, { stewardWakeError: "cannot spawn steward: steward policy could not be provisioned", stewardWakeErrorAt: Date.now() });
+    return null;
+  }
   // #640 — resolve the identity triangle so the steward isn't blind to the people-graph:
   // the workspace's branch agent (owner) and that agent's coordinator (owner's `spawnedBy`).
   const { ownerAgentId, coordinatorAgentId } = resolveStewardIdentity(ws);
@@ -132,11 +158,18 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
       },
     });
     getLifecycleManager().onMessageForPolicy(policyName);
-    patchWorkspaceMetadata(ws.id, { stewardWokenAt: Date.now(), stewardPolicy: policyName, coordinatorAgentId: coordinatorAgentId ?? undefined });
+    patchWorkspaceMetadata(ws.id, {
+      stewardWokenAt: Date.now(),
+      stewardPolicy: policyName,
+      coordinatorAgentId: coordinatorAgentId ?? undefined,
+      stewardWakeError: undefined,
+      stewardWakeErrorAt: undefined,
+    });
     // #641/#642 — tell the owner which steward took over and proactively loop in its coordinator.
     notifyStewardHandoff({ workspace: ws, stewardId: policyName, coordinatorAgentId, reason });
     return policyName;
-  } catch {
+  } catch (e) {
+    patchWorkspaceMetadata(ws.id, { stewardWakeError: e instanceof Error ? e.message : "failed to wake steward", stewardWakeErrorAt: Date.now() });
     return null;
   }
 }
@@ -247,6 +280,36 @@ function escalateNoProgressMerge(ws: WorkspaceRecord): void {
   });
 }
 
+function notifyProtectedTipRestore(ws: WorkspaceRecord, preview: WorkspaceMergePreview): void {
+  const discardedRef = preview.protectedTipDiscardedRef;
+  const discardedHead = preview.protectedTipDiscardedHead;
+  if (!discardedRef || !discardedHead) return;
+  const { coordinatorAgentId } = resolveStewardIdentity(ws);
+  const recipients = [...new Set([coordinatorAgentId, ws.ownerAgentId].filter((r): r is string => Boolean(r)))];
+  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}\`.`;
+  createActivityEvent({
+    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 },
+  });
+  if (!recipients.length) return;
+  routeNotification({
+    type: "workspace.land_gate_warning",
+    scope: { workspaceId: ws.id, repoRoot: ws.repoRoot, author: ws.ownerAgentId, parent: coordinatorAgentId ?? undefined },
+    recipients,
+    message: {
+      subject: "Workspace protected tip restored",
+      body,
+      payload: { kind: "workspace.protected-tip-restore", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, protectedTip: preview.protectedTip, discardedHead, discardedRef },
+    },
+  });
+}
+
 interface LandSweepResult {
   scanned: number;
   merged: string[];
@@ -255,13 +318,14 @@ interface LandSweepResult {
   heldByPause: string[];
   heldAwaitingApproval: string[];
   previewUnavailable: string[];
+  dirtyWorktree: string[];
   backedOff: string[];
   leftForSteward: string[];
   wokeStewards: string[];
 }
 
 function emptyLandSweep(): LandSweepResult {
-  return { scanned: 0, merged: [], heldByLease: [], heldByClaim: [], heldByPause: [], heldAwaitingApproval: [], previewUnavailable: [], backedOff: [], leftForSteward: [], wokeStewards: [] };
+  return { scanned: 0, merged: [], heldByLease: [], heldByClaim: [], heldByPause: [], heldAwaitingApproval: [], previewUnavailable: [], dirtyWorktree: [], backedOff: [], leftForSteward: [], wokeStewards: [] };
 }
 
 async function fetchFirstUsableMergePreview(
@@ -270,7 +334,7 @@ async function fetchFirstUsableMergePreview(
 ): Promise<WorkspaceMergePreview | { available: false } | null> {
   for (const orch of workspaceMergeOrchestrators(ws, orchestrators)) {
     if (!orch.apiUrl) continue;
-    const preview = await fetchHostMergePreview(orch.apiUrl, ws);
+    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;
@@ -288,7 +352,7 @@ async function landCandidates(
 ): Promise<LandSweepResult> {
   const stewardEnabled = getStewardConfig().enabled;
   const merged: string[] = [], previewUnavailable: string[] = [];
-  const heldByLease: string[] = [], heldByClaim: string[] = [], heldByPause: string[] = [], heldAwaitingApproval: string[] = [], backedOff: string[] = [], leftForSteward: string[] = [], wokeStewards: string[] = [];
+  const heldByLease: string[] = [], heldByClaim: string[] = [], heldByPause: string[] = [], heldAwaitingApproval: string[] = [], dirtyWorktree: string[] = [], backedOff: string[] = [], leftForSteward: string[] = [], wokeStewards: string[] = [];
 
   for (const ws of candidates) {
     if (isAwaitingReviewerApproval(ws)) { heldAwaitingApproval.push(ws.id); continue; }
@@ -310,8 +374,22 @@ async function landCandidates(
       continue;
     }
     const p = preview as WorkspaceMergePreview;
-    if (p.reason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
-      patchWorkspaceMetadata(ws.id, { lastLandSkipReason: p.reason, lastLandSkipAt: Date.now() });
+    if (p.protectedTipRestored) notifyProtectedTipRestore(ws, p);
+    const dirtyCount = p.dirtyCount ?? 0;
+    if (p.reason === DIRTY_WORKTREE_LAND_SKIP_REASON || dirtyCount > 0) {
+      const mergeError = p.reason ?? DIRTY_WORKTREE_LAND_SKIP_REASON;
+      const heldDirty = patchWorkspaceMetadata(ws.id, {
+        ...noteMergeNoProgress(ws.metadata),
+        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);
+        escalateNoProgressMerge(heldDirty);
+      }
+      continue;
     } else if (ws.metadata.lastLandSkipReason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
       patchWorkspaceMetadata(ws.id, { lastLandSkipReason: undefined, lastLandSkipAt: undefined });
     }
@@ -328,11 +406,40 @@ async function landCandidates(
     // the steward every sweep for a workspace with no work.
     const canLand = p.noop === true || (p.conflict === false && ahead > 0);
     if (!canLand) {
+      let handoffWorkspace = ws;
+      if (p.conflict !== true) {
+        const mergeError = p.protectedTipReachable === false
+          ? p.protectedTipError ?? "protected worker tip is no longer reachable"
+          : p.reason ?? p.error ?? "merge state unknown";
+        handoffWorkspace = patchWorkspaceMetadata(ws.id, {
+          ...noteMergeNoProgress(ws.metadata),
+          mergeError,
+          lastMergeStateUnknownAt: Date.now(),
+        }) ?? ws;
+        if (mergeNoProgressCount(handoffWorkspace.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+          backedOff.push(ws.id);
+          escalateNoProgressMerge(handoffWorkspace);
+          continue;
+        }
+      }
       leftForSteward.push(ws.id);
+      let woke: string | null = null;
       if (stewardEnabled) {
-        const woke = wakeRepoSteward(ws, p.conflict === true ? "conflict" : "merge state unknown");
+        woke = wakeRepoSteward(handoffWorkspace, p.conflict === true ? "conflict" : "merge state unknown");
         if (woke) wokeStewards.push(woke);
       }
+      if (stewardEnabled && !woke && p.conflict === true) {
+        const failedHandoff = patchWorkspaceMetadata(ws.id, {
+          ...noteMergeNoProgress(ws.metadata),
+          mergeError: "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);
+          escalateNoProgressMerge(failedHandoff);
+          continue;
+        }
+      }
       if (p.conflict === true) {
         emitWorkspaceTaskSemanticNotifications({
           workspace: ws,
@@ -372,7 +479,7 @@ async function landCandidates(
     });
   }
 
-  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldByPause, heldAwaitingApproval, previewUnavailable, backedOff, leftForSteward, wokeStewards };
+  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldByPause, heldAwaitingApproval, previewUnavailable, dirtyWorktree, backedOff, leftForSteward, wokeStewards };
 }
 
 // Coalesced, fire-and-forget per-repo land trigger (see module header). A run already

package/src/workspace-orphans.ts

@@ -556,7 +556,7 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
       // Route through the guarded action (#279): no `force`, so a flipped-alive owner
       // is rejected (409) — our safety net. Also does the cleanup_requested transition
       // + audit. Attributed to a distinct requester so incidents are traceable.
-      const result = applyWorkspaceAction(workspace, {
+      const result = await applyWorkspaceAction(workspace, {
         action: "cleanup",
         agentId: "workspace-dead-owner-reaper",
         auditMetadata: { source: "server", maintenanceJobId: "workspace-orphan-reaper", requestedBy: "workspace-dead-owner-reaper", deadOwner: workspace.ownerAgentId },

package/src/workspace-probe.ts

@@ -32,12 +32,16 @@ export const workspacePathWithinBase = isPathWithinBase;
 export async function fetchHostMergePreview(
   apiUrl: string,
   workspace: WorkspaceRecord,
-  opts: { checkPr?: boolean } = {},
+  opts: { checkPr?: boolean; protectTip?: boolean } = {},
 ): Promise<WorkspaceMergePreview | { available: false } | null> {
   const checkPr = opts.checkPr !== false;
   const query = new URLSearchParams({ path: workspace.worktreePath, ...(checkPr ? { checkPr: "1" } : {}) });
   if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
+  if (opts.protectTip) {
+    query.set("workspaceId", workspace.id);
+    query.set("protectTip", "1");
+  }
   const headers: Record<string, string> = {};
   const token = relayToken();
   if (token) headers[RELAY_TOKEN_HEADER] = token;
@@ -84,6 +88,18 @@ interface ProbeResult {
   skipped?: string;
 }
 
+export async function refreshWorkspaceGitState(ws: WorkspaceRecord): Promise<ProbeResult> {
+  if (!ws.worktreePath) return { probed: false, workspaceId: ws.id, skipped: "workspace has no worktree" };
+  const orch = workspaceOwnerOrchestrator(ws, listOrchestrators(), { requireApiUrl: true });
+  if (!orch?.apiUrl) return { probed: false, workspaceId: ws.id, skipped: "no online orchestrator owns this path" };
+  const preview = await fetchHostMergePreview(orch.apiUrl, ws, { checkPr: false });
+  if (!preview || (preview as { available?: false }).available === false) return { probed: false, workspaceId: ws.id, skipped: "host preview unavailable" };
+  const p = preview as WorkspaceMergePreview;
+  if (p.error || p.missing) return { probed: false, workspaceId: ws.id, skipped: "host preview error" };
+  const flipped = applyBranchFreshness(ws, p);
+  return { probed: true, flipped, workspaceId: ws.id };
+}
+
 /**
  * Probe THIS agent's branch worktree on turn-end (#237). Single scoped host round-trip
  * (not the full fan-out scan) so the changes badge flips at the exact moment work
@@ -96,15 +112,8 @@ export async function probeWorkspaceState(agentId: string): Promise<ProbeResult>
   const ws = ownedIsolatedWorkspace(agentId);
   if (!ws || !ws.worktreePath) return { probed: false, skipped: "no live isolated workspace" };
   if (ws.status !== "active") return { probed: false, workspaceId: ws.id, skipped: `status ${ws.status} derives badge without git counts` };
-  const orch = workspaceOwnerOrchestrator(ws, listOrchestrators(), { requireApiUrl: true });
-  if (!orch?.apiUrl) return { probed: false, workspaceId: ws.id, skipped: "no online orchestrator owns this path" };
-  // checkPr:false — a badge probe never needs the gh round-trip (#304).
-  const preview = await fetchHostMergePreview(orch.apiUrl, ws, { checkPr: false });
-  if (!preview || (preview as { available?: false }).available === false) return { probed: false, workspaceId: ws.id, skipped: "host preview unavailable" };
-  const p = preview as WorkspaceMergePreview;
-  if (p.error || p.missing) return { probed: false, workspaceId: ws.id, skipped: "host preview error" };
-  const flipped = applyBranchFreshness(ws, p);
-  return { probed: true, flipped, workspaceId: ws.id };
+  // checkPr:false — a badge/readiness probe never needs the gh round-trip (#304).
+  return refreshWorkspaceGitState(ws);
 }
 
 /**