agent-relay-server 0.37.0 → 0.38.0

package/src/config-store.ts

@@ -8,6 +8,7 @@ import type {
   ConfigEntry,
   ConfigHistoryEntry,
   InsightsConfig,
+  LandingConfig,
   ManagedAgentState,
   ManagedAgentStatus,
   NotificationsConfig,
@@ -16,6 +17,7 @@ import type {
   SpawnProvider,
   StewardConfig,
   WorkspaceConfig,
+  WorkspaceLandingPolicy,
 } from "./types";
 
 const CONFIG_HISTORY_LIMIT = 50;
@@ -29,6 +31,9 @@ const NOTIFICATIONS_NAMESPACE = "notifications";
 const NOTIFICATIONS_KEY = "default";
 const WORKSPACE_NAMESPACE = "workspace";
 const WORKSPACE_KEY = "default";
+const LANDING_NAMESPACE = "landing";
+const LANDING_KEY = "default";
+const VALID_LANDING_STRATEGIES = ["direct", "pr"] as const;
 const VALID_PROFILE_PROVIDERS = ["any", "claude", "codex"] as const;
 const VALID_PROFILE_BASES = ["host", "minimal", "isolated"] as const;
 const VALID_PROFILE_INSTRUCTION_POLICIES = ["allow", "ignore"] as const;
@@ -239,6 +244,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Parti
     env: input.env ?? {},
     providerOptions: input.providerOptions ?? {},
     ...(input.maxSpawnedAgents === undefined ? {} : { maxSpawnedAgents: input.maxSpawnedAgents }),
+    ...(input.landingStrategy === undefined ? {} : { landingStrategy: input.landingStrategy }),
   };
 }
 
@@ -317,6 +323,9 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
     maxSpawnedAgents: value.maxSpawnedAgents === undefined || value.maxSpawnedAgents === null
       ? undefined
       : cleanNumber(value.maxSpawnedAgents, "maxSpawnedAgents", { min: 0, max: 100 }),
+    landingStrategy: value.landingStrategy === undefined || value.landingStrategy === null
+      ? undefined
+      : cleanEnum(value.landingStrategy, "landingStrategy", VALID_LANDING_STRATEGIES) as WorkspaceLandingPolicy,
   });
 }
 
@@ -508,6 +517,19 @@ function validateWorkspaceConfig(value: unknown): WorkspaceConfig {
   return { symlinkPaths };
 }
 
+const LANDING_CONFIG_DEFAULTS: LandingConfig = {
+  strategy: "direct",
+};
+
+function validateLandingConfig(value: unknown): LandingConfig {
+  if (!isRecord(value)) throw new ValidationError("landing config value must be an object");
+  return {
+    strategy: value.strategy === undefined || value.strategy === null
+      ? LANDING_CONFIG_DEFAULTS.strategy
+      : cleanEnum(value.strategy, "strategy", VALID_LANDING_STRATEGIES) as WorkspaceLandingPolicy,
+  };
+}
+
 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);
@@ -516,6 +538,7 @@ function normalizeValue(namespace: string, key: string, value: unknown): unknown
   if (namespace === INSIGHTS_NAMESPACE) return validateInsightsConfig(value);
   if (namespace === NOTIFICATIONS_NAMESPACE) return validateNotificationsConfig(value);
   if (namespace === WORKSPACE_NAMESPACE) return validateWorkspaceConfig(value);
+  if (namespace === LANDING_NAMESPACE) return validateLandingConfig(value);
   if (JSON.stringify(value) === undefined) throw new ValidationError("value must be valid JSON");
   return value;
 }
@@ -682,6 +705,29 @@ export function setWorkspaceConfig(value: unknown, updatedBy?: string): ConfigEn
   return setConfig(WORKSPACE_NAMESPACE, WORKSPACE_KEY, value as WorkspaceConfig, updatedBy);
 }
 
+/** Instance-wide landing config, merged over defaults (always returns a usable value). */
+export function getLandingConfig(): LandingConfig {
+  const entry = getConfig<Partial<LandingConfig>>(LANDING_NAMESPACE, LANDING_KEY);
+  if (!entry) return { ...LANDING_CONFIG_DEFAULTS };
+  return validateLandingConfig({ ...LANDING_CONFIG_DEFAULTS, ...entry.value });
+}
+
+export function getLandingConfigEntry(): ConfigEntry<LandingConfig> {
+  const entry = getConfig<LandingConfig>(LANDING_NAMESPACE, LANDING_KEY);
+  return entry ?? {
+    namespace: LANDING_NAMESPACE,
+    key: LANDING_KEY,
+    value: { ...LANDING_CONFIG_DEFAULTS },
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function setLandingConfig(value: unknown, updatedBy?: string): ConfigEntry<LandingConfig> {
+  return setConfig(LANDING_NAMESPACE, LANDING_KEY, value as LandingConfig, updatedBy);
+}
+
 /**
  * Spawn-param fragment carrying the global workspace symlink list to the orchestrator.
  * Spread into every spawn command's params next to `agentProfile` so any isolated

package/src/maintenance.ts

@@ -37,7 +37,7 @@ import { reconcileLandedWorkspace } from "./branch-landed";
 import { notifyAgentOffline } from "./agent-lifecycle-events";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
-import { deriveBranchState, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { deriveBranchState, DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { getStewardConfig } from "./config-store";
 import { ensureRepoSteward } from "./steward";
@@ -716,6 +716,11 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     if (!preview || (preview as { available?: false }).available === false) continue;
     const p = preview as WorkspaceMergePreview;
     if (p.error || p.missing) continue;
+    if (p.reason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
+      patchWorkspaceMetadata(ws.id, { lastLandSkipReason: p.reason, lastLandSkipAt: Date.now() });
+    } else if (ws.metadata.lastLandSkipReason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
+      patchWorkspaceMetadata(ws.id, { lastLandSkipReason: undefined, lastLandSkipAt: undefined });
+    }
 
     const ahead = p.unmergedAhead ?? p.ahead ?? 0;
     const behind = p.behind ?? 0;

package/src/mcp.ts

@@ -44,8 +44,9 @@ import {
 } from "./security";
 import { sendMessageService } from "./services/send-message";
 import { ServiceAuthError } from "./services/errors";
-import type { ActivityKind, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
+import type { ActivityKind, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
+import { AUTO_MERGE_POLICIES } from "./workspace-merge";
 import { describeWorkspacePhase, landReceipt, readyContract, worktreeMcpInstructions } from "./workspace-phase";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, stringValue, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
@@ -395,10 +396,12 @@ const TOOLS: ToolDefinition[] = [
       type: "object",
       properties: {
         workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
-        strategy: { type: "string", enum: ["pr", "rebase-ff", "auto"], description: "Merge strategy (default auto)." },
+        strategy: { type: "string", enum: ["pr", "rebase-ff", "auto"], description: "Merge strategy (default auto). Falls back to the instance landing.strategy config when unset." },
         deleteBranch: { type: "boolean", description: "Delete the branch after a successful merge (default true)." },
         prTitle: { type: "string" },
         prBody: { type: "string" },
+        autoMerge: { type: "string", enum: AUTO_MERGE_POLICIES, description: "Auto-merge policy for PR-strategy lands. Defaults to 'on-green' when strategy resolves to 'pr'. Ignored for rebase-ff/auto strategies." },
+        reviewer: { type: "string", description: "GitHub login or team slug to request as a reviewer on the opened PR (pr strategy only)." },
         detail: { type: "string" },
       },
       additionalProperties: false,
@@ -919,6 +922,8 @@ function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, a
     deleteBranch: action === "merge" ? optionalBoolean(args.deleteBranch, "deleteBranch") : undefined,
     prTitle: optionalString(args.prTitle, "prTitle", 240),
     prBody: optionalString(args.prBody, "prBody", 8000),
+    autoMerge: action === "merge" ? (optionalEnum(args.autoMerge, "autoMerge", AUTO_MERGE_POLICIES) as WorkspaceAutoMergePolicy | undefined) : undefined,
+    reviewer: action === "merge" ? optionalString(args.reviewer, "reviewer", 240) : undefined,
     purpose: optionalString(args.purpose, "purpose", 120),
     checkOnly: action === "deps-refresh" ? optionalBoolean(args.checkOnly, "checkOnly") === true : undefined,
     auditMetadata: { via: "mcp", actor: auth.actor },

package/src/routes/workspaces.ts

@@ -10,7 +10,8 @@ import { createCommand } from "../commands-db";
 import { LAND_STRATEGIES, isOwnerAlive, withOwnerOnline } from "../workspace-merge";
 import { isPathWithinBase } from "../utils";
 import { resolve } from "node:path";
-import { type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecord, type WorkspaceStatus } from "../types";
+import { type WorkspaceAutoMergePolicy, type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecord, type WorkspaceStatus } from "../types";
+import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import { workspaceActiveClaim } from "../workspace-claim";
 
 export const getWorkspaces: Handler = (req) => {
@@ -327,6 +328,8 @@ export const postWorkspaceAction: Handler = async (req, params) => {
       force: parsed.body.force === true,
       prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
       prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
+      autoMerge: optionalEnum(parsed.body.autoMerge, "autoMerge", AUTO_MERGE_POLICIES) as WorkspaceAutoMergePolicy | undefined,
+      reviewer: cleanString(parsed.body.reviewer, "reviewer", { max: 240 }),
       purpose: cleanString(parsed.body.purpose, "purpose", { max: 120 }),
       checkOnly: parsed.body.checkOnly === true,
       auditMetadata: authAuditMetadata(req),

package/src/services/send-message.ts

@@ -53,10 +53,28 @@ export interface SendMessageOptions {
  * the runner reporting an agent's turn ON ITS BEHALF, so the wire `from` (the reported agent) is
  * authoritative there and the token's own identity must NOT override it. This is the relay's own
  * lane (not agent-directed), the agentId authz predicate is dropped for it too, and it preserves
- * the pre-convergence behavior — a steward/runner token managing other agents can still mirror. */
+ * the pre-convergence behavior — a steward/runner token managing other agents can still mirror.
+ *
+ * LINEAGE GATE (#362): the reserved-sink exception is NOT blanket lane access — the wire `from`
+ * must be an agent the caller is authorised to speak as. The caller qualifies when the wire
+ * `from` matches its own resolved identity (`callerAgentId`), OR when `from` is explicitly
+ * listed in the token's managed set (`constraints.agents`), OR when the caller carries no
+ * agent-level constraints at all (admin/server/integration). Any other combination is an
+ * impersonation attempt and is rejected. */
 function resolveFrom(input: SendMessageInput, ctx: AuthContext, reservedSink: boolean): string {
   const from = reservedSink ? (input.from || ctx.callerAgentId) : (ctx.callerAgentId ?? input.from);
   if (!from) throw new ValidationError("from is required");
+  if (reservedSink && from !== ctx.callerAgentId) {
+    // Constrained component tokens: the wire `from` must be in the token's managed agents list.
+    // Unconstrained callers (admin, server, integration — ctx.constraints is undefined) are
+    // allowed through unchanged; they hold full reach by design.
+    const managed = ctx.constraints?.agents;
+    if (managed !== undefined && !managed.includes(from)) {
+      throw new ServiceAuthError(
+        `reserved-sink wire from "${from}" is not in the caller's managed agents — impersonation rejected (#362)`,
+      );
+    }
+  }
   return from;
 }
 

package/src/services/spawn-agent.ts

@@ -190,6 +190,12 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     policyName: input.policyName,
     spawnRequestId,
     createdBy: requestedBy,
+    // Thread the resolved profile into the mint so the spawn grant (command:spawn/shutdown +
+    // maxSpawnedAgents quota) is honored — parity with the HTTP path (agent-sessions.ts). #349
+    // dropped this when it unified the spawn service, silently un-spawning every default-spawner
+    // (P0 regression #364). For an agent caller, agentInitiated still forces a non-spawn-capable
+    // child regardless of profile (no grandchildren).
+    profile: input.profile || undefined,
     ...(callerId ? { agentInitiated: true, spawnedBy: callerId } : {}),
   });
 

package/src/workspace-actions.ts

@@ -25,7 +25,7 @@ import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
 export { LAND_STRATEGIES, DEFAULT_MERGE_STRATEGY } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
 import { TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
-import type { Command, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
+import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
 // the MCP tool surface both import this so they can never drift out of sync.
@@ -54,6 +54,8 @@ interface ApplyWorkspaceActionInput {
   deleteBranch?: boolean;
   prTitle?: string;
   prBody?: string;
+  autoMerge?: WorkspaceAutoMergePolicy;
+  reviewer?: string;
   // cleanup
   force?: boolean;
   // claim / release-claim
@@ -171,6 +173,8 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
       deleteBranch: input.deleteBranch !== false,
       prTitle: input.prTitle,
       prBody: input.prBody,
+      autoMerge: input.autoMerge,
+      reviewer: input.reviewer,
       metadata: { ...metadata, ...(detail ? { detail } : {}), ...(agentId ? { updatedByAgentId: agentId } : {}) },
     });
     if (!result.ok) return { ok: false, httpStatus: result.status, error: result.error };

package/src/workspace-merge.ts

@@ -7,9 +7,21 @@ import {
   setMergeLeaseCommand,
   updateWorkspaceStatus,
 } from "./db";
-import type { Command, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
+import { getLandingConfig } from "./config-store";
+import type {
+  Command,
+  WorkspaceAutoMergePolicy,
+  WorkspaceLandingPolicy,
+  WorkspaceMergeStrategy,
+  WorkspaceRecord,
+} from "./types";
+import { AUTO_MERGE_POLICIES } from "./types";
 import { isPathWithinBase } from "./utils";
 
+// Re-export so consumers can import the tuple from the strategy home without a
+// second import hop.
+export { AUTO_MERGE_POLICIES } from "./types";
+
 // One home for the land-strategy contract, shared by BOTH land surfaces — the HTTP
 // route (`POST /api/workspaces/:id/actions`, driven by `agent-relay workspace land`)
 // and the `relay_workspace_land` MCP tool. They validate against the same tuple and
@@ -21,6 +33,60 @@ import { isPathWithinBase } from "./utils";
 export const LAND_STRATEGIES = ["pr", "rebase-ff", "auto"] as const;
 export const DEFAULT_MERGE_STRATEGY: WorkspaceMergeStrategy = "auto";
 
+/** Normalize a user-facing policy word or a raw WorkspaceMergeStrategy to a WorkspaceMergeStrategy. */
+function normalizeToMergeStrategy(value: string): WorkspaceMergeStrategy {
+  if (value === "direct") return "auto";
+  if (value === "pr" || value === "rebase-ff" || value === "auto") return value;
+  return "auto";
+}
+
+/**
+ * Resolve the effective merge strategy from the three-level precedence chain.
+ *
+ * Precedence (highest → lowest):
+ *   explicit (per-invocation --strategy or relay_workspace_land.strategy)
+ *   > profileStrategy (per-profile landingStrategy)
+ *   > instanceStrategy (instance-wide landing.strategy from config-store)
+ *   > "direct" (hard-coded default, which maps to "auto")
+ *
+ * `explicit` accepts BOTH raw WorkspaceMergeStrategy literals ("pr", "rebase-ff",
+ * "auto") and policy words ("direct", "pr") so callers don't need to pre-normalise.
+ */
+export function resolveLandStrategy(opts: {
+  explicit?: string;
+  profileStrategy?: WorkspaceLandingPolicy;
+  instanceStrategy?: WorkspaceLandingPolicy;
+}): WorkspaceMergeStrategy {
+  if (opts.explicit !== undefined && opts.explicit !== null) {
+    return normalizeToMergeStrategy(opts.explicit);
+  }
+  if (opts.profileStrategy !== undefined) {
+    return normalizeToMergeStrategy(opts.profileStrategy);
+  }
+  if (opts.instanceStrategy !== undefined) {
+    return normalizeToMergeStrategy(opts.instanceStrategy);
+  }
+  return DEFAULT_MERGE_STRATEGY;
+}
+
+/**
+ * Derive the issue number from a workspace metadata bag.
+ * Checks `metadata.issueNumber` (number or numeric string) and
+ * `metadata.taskId` (number or numeric string) — both common shapes.
+ * Returns the integer if found, otherwise undefined.
+ */
+function resolveIssueNumber(metadata: Record<string, unknown>): number | undefined {
+  for (const key of ["issueNumber", "taskId"]) {
+    const raw = metadata[key];
+    if (typeof raw === "number" && Number.isSafeInteger(raw) && raw > 0) return raw;
+    if (typeof raw === "string") {
+      const n = Number.parseInt(raw, 10);
+      if (Number.isSafeInteger(n) && n > 0) return n;
+    }
+  }
+  return undefined;
+}
+
 interface RequestWorkspaceMergeOptions {
   /** Who asked for the merge (lease holder + audit). e.g. an agent id, "dashboard", "auto-merge". */
   requestedBy: string;
@@ -33,6 +99,15 @@ interface RequestWorkspaceMergeOptions {
   push?: boolean;
   prTitle?: string;
   prBody?: string;
+  /**
+   * Auto-merge policy for a PR-strategy land. When the effective strategy is "pr" and
+   * this is unset, defaults to "on-green" — a pr land MUST always reach a terminal
+   * state and should not block on a human hitting the merge button. Ignored for non-pr
+   * strategies (omitted from the command params entirely so the host stays clean).
+   */
+  autoMerge?: WorkspaceAutoMergePolicy;
+  /** Optional reviewer handle (GitHub login or team slug) to request on the opened PR. */
+  reviewer?: string;
   /** Extra metadata merged onto the workspace row when moving to merge_planned. */
   metadata?: Record<string, unknown>;
 }
@@ -101,6 +176,28 @@ export function requestWorkspaceMerge(workspace: WorkspaceRecord, opts: RequestW
       releaseMergeLease({ repoRoot: workspace.repoRoot, workspaceId: workspace.id });
       return { ok: false, status: 404, error: "workspace not found" };
     }
+    const effectiveStrategy = opts.strategy ?? DEFAULT_MERGE_STRATEGY;
+
+    // Slice 6 — issue auto-linkage: append "Closes #N" to the PR body when the
+    // workspace metadata carries an issue number, WITHOUT clobbering an explicit body.
+    const issueNumber = resolveIssueNumber(workspace.metadata);
+    let prBody = opts.prBody;
+    if (issueNumber !== undefined) {
+      const closesLine = `Closes #${issueNumber}`;
+      if (!prBody) {
+        prBody = closesLine;
+      } else if (!prBody.includes(closesLine)) {
+        prBody = `${prBody}\n\n${closesLine}`;
+      }
+    }
+
+    // Slice 3 — auto-merge default for PR lands: a pr-strategy land MUST reach a
+    // terminal state; default to "on-green" so CI can close the loop automatically.
+    const isPrStrategy = effectiveStrategy === "pr";
+    const autoMerge: WorkspaceAutoMergePolicy | undefined = isPrStrategy
+      ? (opts.autoMerge ?? "on-green")
+      : undefined;
+
     const command = createCommand({
       type: "workspace.merge",
       source: "system",
@@ -114,11 +211,13 @@ export function requestWorkspaceMerge(workspace: WorkspaceRecord, opts: RequestW
         branch: workspace.branch,
         baseRef: workspace.baseRef,
         baseSha: workspace.baseSha,
-        strategy: opts.strategy ?? DEFAULT_MERGE_STRATEGY,
+        strategy: effectiveStrategy,
         deleteBranch,
         push: opts.push !== false,
         prTitle: opts.prTitle,
-        prBody: opts.prBody,
+        prBody,
+        ...(autoMerge !== undefined ? { autoMerge } : {}),
+        ...(opts.reviewer !== undefined ? { reviewer: opts.reviewer } : {}),
         requestedBy: opts.requestedBy,
         requestedAt: Date.now(),
       },

package/src/workspace-phase.ts

@@ -80,6 +80,7 @@ export function worktreeReapable(state: WorktreeReapState | null | undefined): b
 // an unpushed branch, a wedged steward) and the agent/human should be told —
 // instead of the old behavior where it looked healthy for 90 minutes.
 export const LAND_PENDING_STALL_MS = 15 * 60 * 1000;
+export const DIRTY_WORKTREE_LAND_SKIP_REASON = "worktree has uncommitted changes";
 
 type WorkspacePhase =
   | "working" // active — your turn: commit, then mark ready
@@ -134,7 +135,7 @@ const READY_ACTION: WorkspaceNextAction = {
 // marks ready, immune to the heartbeat `updated_at` bump) — not `updatedAt`, which
 // keeps ticking on every heartbeat and made the stall look fresh forever.
 export function describeWorkspacePhase(
-  workspace: Pick<WorkspaceRecord, "status" | "branch" | "stewardAgentId" | "readyAt">,
+  workspace: Pick<WorkspaceRecord, "status" | "branch" | "stewardAgentId" | "readyAt"> & { metadata?: Record<string, unknown> },
   opts: { now?: number; stallMs?: number } = {},
 ): WorkspacePhaseView {
   switch (workspace.status) {
@@ -160,6 +161,19 @@ export function describeWorkspacePhase(
       // the agent (and the dashboard) stop reporting a wedged land as healthy.
       if (pendingMs !== undefined && pendingMs > stallMs) {
         const mins = Math.round(pendingMs / 60_000);
+        const lastLandSkipReason = typeof workspace.metadata?.lastLandSkipReason === "string"
+          ? workspace.metadata.lastLandSkipReason
+          : undefined;
+        if (lastLandSkipReason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
+          return {
+            phase: "land-pending",
+            headline: `Stalled — handed off ${mins} min ago but auto-merge is blocked by uncommitted worktree changes.`,
+            hint: "Commit or stash your uncommitted changes in the worktree, then wait for Relay to retry the auto-merge. Do NOT merge, push, rebase, or touch the main checkout yourself.",
+            actionNeeded: true,
+            nextActions: [WAIT_ACTION],
+            blockers: ["owner worktree has uncommitted changes — commit or stash them in the worktree"],
+          };
+        }
         return {
           phase: "land-pending",
           headline: `Stalled — handed off ${mins} min ago but still hasn't landed. A clean auto-merge runs every ~2 min, so this is past the healthy window and likely stuck (no online orchestrator, an unpushed branch, or a wedged merge/steward).`,