agent-relay-server 0.117.1 → 0.118.0

package/runner/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.117.1",
+  "version": "0.118.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/artifact-text.ts

@@ -0,0 +1,36 @@
+import { getArtifactStorage } from "./artifact-storage";
+import { bytesToStream } from "./http-body";
+import { createArtifact, upsertArtifactBlob } from "./db/artifacts";
+import type { ArtifactKind } from "./types";
+
+/**
+ * Persist a UTF-8 text blob as a relay artifact and return its id, composing the
+ * same store→blob→record pipeline the MCP upload tool uses. Used by the land-gate
+ * pipeline (#902) to stream a failing gate's FULL output to an artifact so the
+ * worker/coordinator notification carries only the tail + this ref — never the
+ * flood of full output.
+ */
+export async function storeTextArtifact(input: {
+  text: string;
+  filename: string;
+  createdBy: string;
+  kind?: ArtifactKind;
+  mediaType?: string;
+  metadata?: Record<string, unknown>;
+}): Promise<{ id: string; size: number }> {
+  const bytes = new TextEncoder().encode(input.text);
+  const mediaType = input.mediaType ?? "text/plain; charset=utf-8";
+  const storage = getArtifactStorage();
+  const stored = await storage.store(bytesToStream(bytes), { mediaType, size: bytes.byteLength });
+  upsertArtifactBlob({ digest: stored.digest, storageUri: stored.storageUri, mediaType, size: stored.size });
+  const artifact = createArtifact({
+    blobDigest: stored.digest,
+    mediaType,
+    kind: input.kind ?? "document",
+    filename: input.filename,
+    size: stored.size,
+    createdBy: input.createdBy,
+    metadata: input.metadata,
+  });
+  return { id: artifact.id, size: stored.size };
+}

package/src/auto-spawn-dispatch.ts

@@ -0,0 +1,136 @@
+// #901 — resolver shim + configurable per-type work-shape config for internal auto-spawns.
+// PURE ADDITIONS — zero behavior change at existing call sites. The dispatch brain
+// (dispatchTask) is reused verbatim; this module only drives it with the configured
+// work-shape for each InternalSpawnType and the #901 degrade-never-refuse flag.
+import { getConfig, setConfig } from "./config-store";
+import { dispatchTask, type DispatchDecision, type DispatchPin } from "./task-dispatcher";
+import {
+  INTERNAL_SPAWN_TYPES,
+  TASK_DISPATCH_COMPLEXITIES,
+  TASK_DISPATCH_CRITICALITIES,
+  TASK_DISPATCH_FOOTPRINTS,
+  TASK_DISPATCH_TYPES,
+  isRecord,
+} from "agent-relay-sdk";
+import type {
+  AutoSpawnDispatchConfig,
+  InternalSpawnType,
+  TaskDispatch,
+  TaskDispatchCriticality,
+  WorkShapeProfile,
+} from "agent-relay-sdk";
+
+export const AUTO_SPAWN_DISPATCH_NAMESPACE = "auto-spawn-dispatch";
+export const AUTO_SPAWN_DISPATCH_KEY = "default";
+
+// Re-export so callers only need this module.
+export type { InternalSpawnType } from "agent-relay-sdk";
+
+const ALL_AUTO_PROFILE: WorkShapeProfile = {
+  complexity: "auto",
+  type: "auto",
+  contextFootprint: "auto",
+  criticality: "auto",
+};
+
+export const DEFAULT_AUTO_SPAWN_DISPATCH_CONFIG: AutoSpawnDispatchConfig = {
+  schemaVersion: 1,
+  profiles: {
+    "landing-steward": { ...ALL_AUTO_PROFILE },
+    "file-size-ratchet-heal": { ...ALL_AUTO_PROFILE },
+    "spawn-smoke": { ...ALL_AUTO_PROFILE },
+  },
+};
+
+// Built-in criticality for each spawn type when the profile's criticality dimension is "auto".
+// landing-steward is high because it is the critical-infra auto-land path; the degrade-never-refuse
+// safety (mustResolveAvailable) is therefore always on for it unless the operator overrides.
+const BUILT_IN_CRITICALITY: Record<InternalSpawnType, TaskDispatchCriticality> = {
+  "landing-steward": "high",
+  "file-size-ratchet-heal": "normal",
+  "spawn-smoke": "low",
+};
+
+// ---------------------------------------------------------------------------
+// Config store
+// ---------------------------------------------------------------------------
+
+export function getAutoSpawnDispatchConfig(): AutoSpawnDispatchConfig {
+  const entry = getConfig<AutoSpawnDispatchConfig>(AUTO_SPAWN_DISPATCH_NAMESPACE, AUTO_SPAWN_DISPATCH_KEY);
+  return entry ? normalizeAutoSpawnDispatchConfig(entry.value) : { ...DEFAULT_AUTO_SPAWN_DISPATCH_CONFIG };
+}
+
+export function setAutoSpawnDispatchConfig(value: unknown, opts: { updatedBy?: string } = {}): AutoSpawnDispatchConfig {
+  const normalized = normalizeAutoSpawnDispatchConfig(value);
+  const current = getAutoSpawnDispatchConfig();
+  if (JSON.stringify(normalized) === JSON.stringify(current)) return normalized;
+  setConfig(AUTO_SPAWN_DISPATCH_NAMESPACE, AUTO_SPAWN_DISPATCH_KEY, normalized, opts.updatedBy);
+  return normalized;
+}
+
+// ---------------------------------------------------------------------------
+// Normalizer — coerces arbitrary input into a valid AutoSpawnDispatchConfig.
+// "auto" is the safe default for every dimension, so a partial config is always valid.
+// ---------------------------------------------------------------------------
+
+export function normalizeAutoSpawnDispatchConfig(value: unknown): AutoSpawnDispatchConfig {
+  const input = isRecord(value) ? value : {};
+  const rawProfiles = isRecord(input.profiles) ? input.profiles : {};
+  const profiles = {} as AutoSpawnDispatchConfig["profiles"];
+  for (const type of INTERNAL_SPAWN_TYPES) {
+    const raw = isRecord(rawProfiles[type]) ? rawProfiles[type] : {};
+    profiles[type] = normalizeWorkShapeProfile(raw);
+  }
+  return { schemaVersion: 1, profiles };
+}
+
+export function validateAutoSpawnDispatchConfig(value: unknown): AutoSpawnDispatchConfig {
+  return normalizeAutoSpawnDispatchConfig(value);
+}
+
+function normalizeWorkShapeProfile(raw: Record<string, unknown>): WorkShapeProfile {
+  return {
+    complexity: normalizeAutoDim(raw.complexity, TASK_DISPATCH_COMPLEXITIES),
+    type: normalizeAutoDim(raw.type, TASK_DISPATCH_TYPES),
+    contextFootprint: normalizeAutoDim(raw.contextFootprint, TASK_DISPATCH_FOOTPRINTS),
+    criticality: normalizeAutoDim(raw.criticality, TASK_DISPATCH_CRITICALITIES),
+  };
+}
+
+function normalizeAutoDim<T extends string>(value: unknown, allowed: readonly T[]): "auto" | T {
+  if (value === "auto") return "auto";
+  if (typeof value === "string" && (allowed as readonly string[]).includes(value)) return value as T;
+  return "auto";
+}
+
+// ---------------------------------------------------------------------------
+// Resolver shim
+// ---------------------------------------------------------------------------
+
+function effectiveCriticality(type: InternalSpawnType, profile: WorkShapeProfile): TaskDispatchCriticality {
+  return profile.criticality === "auto" ? BUILT_IN_CRITICALITY[type] : profile.criticality;
+}
+
+/**
+ * Resolve a concrete spawn target for an internal auto-spawn. Reads the configured work-shape
+ * for `type`, maps each "auto" dimension → undefined (wildcard), and calls dispatchTask.
+ * Returns the full DispatchDecision so callers can log WHY and surface the rationale.
+ *
+ * For high-criticality types (landing-steward by default) the degrade-never-refuse flag is set,
+ * guaranteeing a provider is returned even when all quota pools are blocked.
+ */
+export function resolveInternalSpawnTarget(type: InternalSpawnType, pin?: DispatchPin): DispatchDecision {
+  const config = getAutoSpawnDispatchConfig();
+  const profile = config.profiles[type];
+
+  // Map "auto" → undefined; a concrete value is passed through to constrain the dispatch match.
+  const shape: TaskDispatch = {
+    ...(profile.complexity !== "auto" ? { complexity: profile.complexity } : {}),
+    ...(profile.type !== "auto" ? { type: profile.type } : {}),
+    ...(profile.contextFootprint !== "auto" ? { contextFootprint: profile.contextFootprint } : {}),
+    ...(profile.criticality !== "auto" ? { criticality: profile.criticality } : {}),
+  };
+
+  const mustResolveAvailable = effectiveCriticality(type, profile) === "high";
+  return dispatchTask(shape, pin ?? {}, { mustResolveAvailable });
+}

package/src/branch-landed.ts

@@ -1,4 +1,4 @@
-import { errMessage, type BaseWorktreeSyncResult } from "agent-relay-sdk";
+import { errMessage, type BaseWorktreeSyncResult, type LandGateRunResult } from "agent-relay-sdk";
 import { emitRelayEvent } from "./events";
 import { routeNotification, INFORMATIONAL_TTL_MS } from "./notification-router";
 import { registerDefaultAudienceRules, audiencePredicates } from "./notification-rules";
@@ -357,6 +357,132 @@ export function notifyBranchLandFailed(input: {
   });
 }
 
+function gateOutcomeLabel(gate: LandGateRunResult): string {
+  if (gate.timedOut) return "timed out";
+  if (gate.exitCode === null) return "could not run";
+  return `exited ${gate.exitCode}`;
+}
+
+/**
+ * #902 — a REQUIRED land gate failed against the candidate merged tree, so the land was
+ * aborted WITHOUT advancing `main` (ref unchanged). This is a CORRECTNESS gate, orthogonal
+ * to merge conflicts: it NEVER routes through the steward/conflict path. Wake the worker
+ * (owner) AND its coordinator with the failing gate name + a bounded output TAIL + the relay
+ * artifact ref holding the full output, so the worker fixes the gate and re-lands cleanly.
+ * Durable (ttl null): the owner is parked idle after `ready` and must still learn why its
+ * land bounced. The full gate output lives in the artifact — the notice carries only the tail,
+ * so a noisy gate never floods relay.
+ */
+export function notifyLandGateFailed(input: {
+  workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
+  gate: LandGateRunResult;
+  /** Relay artifact id holding the full gate output, when the upload succeeded. */
+  artifactId?: string;
+}): void {
+  const { workspace, gate } = input;
+  const base = workspace.baseRef ?? "base";
+  const owner = workspace.ownerAgentId;
+  const coordinator = resolveCoordinatorAgentId(owner ?? undefined);
+  const fallback = stewardFallbackTarget();
+  const branchLabel = workspace.branch ? `\`${workspace.branch}\`` : "Your branch";
+  const reasonLabel = gateOutcomeLabel(gate);
+  const artifactLabel = input.artifactId ? ` Full output: artifact \`${input.artifactId}\`.` : "";
+  const tail = gate.outputTail?.trim() ? `\n\n\`\`\`\n${gate.outputTail.trim()}\n\`\`\`` : "";
+  const body = `🚦 ${branchLabel} did NOT land: required land gate \`${gate.name}\` ${reasonLabel} against the candidate merge into \`${base}\`. \`${base}\` was NOT advanced — fix the gate and re-land (\`agent-relay workspace ready\`).${artifactLabel}${tail}`;
+
+  const payload = {
+    kind: "workspace.land-gate-failed",
+    workspaceId: workspace.id,
+    repoRoot: workspace.repoRoot,
+    branch: workspace.branch,
+    base,
+    author: owner,
+    gateName: gate.name,
+    gateCommand: gate.command,
+    exitCode: gate.exitCode,
+    timedOut: gate.timedOut,
+    durationMs: gate.durationMs,
+    artifactId: input.artifactId,
+  };
+
+  emitRelayEvent({ type: "workspace.land_gate_failed", source: "server", subject: workspace.id, data: payload });
+
+  createActivityEvent({
+    clientId: `workspace-land-gate-failed-${workspace.id}-${Date.now()}`,
+    kind: "state",
+    title: "Land blocked by gate failure",
+    body: `${workspace.branch ?? workspace.id} → ${base}: required gate "${gate.name}" ${reasonLabel} — ${base} not advanced`,
+    meta: workspace.branch ?? workspace.id,
+    icon: "ti-alert-octagon",
+    view: "orchestrators",
+    metadata: { source: "server", maintenanceJobId: "workspace-land-gate", workspaceId: workspace.id, repoRoot: workspace.repoRoot, gateName: gate.name, ...(input.artifactId ? { artifactId: input.artifactId } : {}) },
+  });
+
+  // Worker + coordinator (spec). Fall back to the configured steward target only when no
+  // coordinator resolves (a teamless land) so the bounce always reaches a human/agent.
+  const recipients = [...new Set([owner, coordinator ?? fallback].filter((r): r is string => Boolean(r)))];
+  if (!recipients.length) return;
+  routeNotification({
+    type: "workspace.land_gate_failed",
+    scope: { author: owner, parent: coordinator ?? undefined, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+    recipients,
+    ttlMs: null,
+    message: {
+      subject: `Land blocked: gate "${gate.name}" failed`,
+      body,
+      payload: { ...payload, notification: "land-gate-failed" },
+      replyExpected: false,
+    },
+  });
+}
+
+/**
+ * #902 — OPTIONAL land gates that failed but did NOT block the land (the land succeeded and
+ * `main` advanced). Surface a single low-priority warning to the worker with the gate names
+ * + the artifact ref holding the combined output, so the warn signal isn't lost but doesn't
+ * bounce a successful land. Informational TTL: a stale warning shouldn't wake a late joiner.
+ */
+export function notifyLandGateWarnings(input: {
+  workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
+  warnings: LandGateRunResult[];
+  artifactId?: string;
+}): void {
+  const { workspace, warnings } = input;
+  if (warnings.length === 0) return;
+  const base = workspace.baseRef ?? "base";
+  const owner = workspace.ownerAgentId;
+  const branchLabel = workspace.branch ? `\`${workspace.branch}\`` : "Your branch";
+  const names = warnings.map((w) => `\`${w.name}\` (${gateOutcomeLabel(w)})`).join(", ");
+  const artifactLabel = input.artifactId ? ` Full output: artifact \`${input.artifactId}\`.` : "";
+
+  const payload = {
+    kind: "workspace.land-gate-warning",
+    workspaceId: workspace.id,
+    repoRoot: workspace.repoRoot,
+    branch: workspace.branch,
+    base,
+    author: owner,
+    gateNames: warnings.map((w) => w.name),
+    artifactId: input.artifactId,
+  };
+
+  emitRelayEvent({ type: "workspace.land_gate_warning", source: "server", subject: workspace.id, data: payload });
+
+  if (!owner) return;
+  routeNotification({
+    type: "workspace.land_gate_warning",
+    scope: { author: owner, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+    recipients: [owner],
+    ttlMs: INFORMATIONAL_TTL_MS,
+    message: {
+      subject: `Land gate warning${warnings.length > 1 ? "s" : ""} (landed anyway)`,
+      body: `⚠️ ${branchLabel} landed to \`${base}\`, but optional land gate${warnings.length > 1 ? "s" : ""} failed: ${names}. Not blocking — review when convenient.${artifactLabel}`,
+      payload: { ...payload, notification: "land-gate-warning" },
+      replyExpected: false,
+    },
+  });
+}
+
 /**
  * Steward-handoff awareness wake (#641/#642). When the relay can't auto-merge a branch and
  * hands the workspace to a steward, the two ends used to be mutually blind: the branch agent

package/src/db/connection.ts

@@ -68,5 +68,9 @@ export function runDbMaintenance(options: { vacuum?: boolean } = {}): {
 }
 
 // Shared error types thrown across query domains and unwrapped at call sites.
-export class ValidationError extends Error {}
+// `ValidationError` now lives in the SDK (agent-relay-sdk) as the single canonical
+// home shared with the orchestrator package; re-exported here so the ~120 server
+// call sites (and #892's `toThrow(ValidationError)` tests) stay byte-unchanged and
+// keep the same class identity.
+export { ValidationError } from "agent-relay-sdk";
 export class ClaimError extends Error {}

package/src/land-gates.ts

@@ -1,80 +1,8 @@
-import { isAbsolute, relative, resolve } from "node:path";
-import { readFileSync } from "node:fs";
-import { isRecord } from "agent-relay-sdk";
-import type { LandGate } from "agent-relay-sdk";
-import { ValidationError } from "./db/connection.ts";
-import { cleanString } from "./validation.ts";
-import { parseJson, isPathWithinBase } from "./utils.ts";
-
-const LAND_GATES_FILE = ".agent-relay/land-gates.json";
-
-export function cleanLandGate(value: unknown, index: number, worktreePath?: string): LandGate {
-  if (!isRecord(value)) throw new ValidationError(`gates[${index}] must be an object`);
-  const name = cleanString(value.name, `gates[${index}].name`, { required: true, max: 120 });
-  if (!name) throw new ValidationError(`gates[${index}].name required`);
-  const command = cleanString(value.command, `gates[${index}].command`, { required: true, max: 4096 });
-  if (!command) throw new ValidationError(`gates[${index}].command required`);
-
-  let cwd: string | undefined;
-  if (value.cwd !== undefined && value.cwd !== null) {
-    const rawCwd = cleanString(value.cwd, `gates[${index}].cwd`, { max: 1000 });
-    if (rawCwd) {
-      if (worktreePath) {
-        const resolved = resolve(worktreePath, rawCwd);
-        if (!isPathWithinBase(resolved, worktreePath)) {
-          throw new ValidationError(`gates[${index}].cwd must be within the worktree`);
-        }
-        cwd = relative(worktreePath, resolved) || ".";
-      } else {
-        if (isAbsolute(rawCwd)) throw new ValidationError(`gates[${index}].cwd must be a relative path when no worktreePath is provided`);
-        cwd = rawCwd;
-      }
-    }
-  }
-
-  if (value.timeoutMs !== undefined && value.timeoutMs !== null) {
-    if (typeof value.timeoutMs !== "number" || !Number.isSafeInteger(value.timeoutMs) || value.timeoutMs <= 0) {
-      throw new ValidationError(`gates[${index}].timeoutMs must be a positive integer`);
-    }
-  }
-  if (value.optional !== undefined && value.optional !== null) {
-    if (typeof value.optional !== "boolean") {
-      throw new ValidationError(`gates[${index}].optional must be a boolean`);
-    }
-  }
-
-  return {
-    name,
-    command,
-    ...(cwd !== undefined ? { cwd } : {}),
-    ...(typeof value.timeoutMs === "number" ? { timeoutMs: value.timeoutMs as number } : {}),
-    ...(typeof value.optional === "boolean" ? { optional: value.optional as boolean } : {}),
-  };
-}
-
-/** Parse + validate a raw `.agent-relay/land-gates.json` object. */
-export function cleanLandGatesConfig(value: unknown, worktreePath?: string): LandGate[] {
-  if (!isRecord(value)) throw new ValidationError("land-gates config must be an object");
-  const { gates } = value;
-  if (!Array.isArray(gates)) throw new ValidationError("gates must be an array");
-  if (gates.length > 50) throw new ValidationError("gates: at most 50 gates allowed");
-  return gates.map((g, i) => cleanLandGate(g, i, worktreePath));
-}
-
-/**
- * Read + validate `.agent-relay/land-gates.json` from a worktree path.
- * Missing file → empty list (opt-in, zero regression).
- */
-export function loadRepoLandGates(worktreePath: string): LandGate[] {
-  const filePath = resolve(worktreePath, LAND_GATES_FILE);
-  let raw: string;
-  try {
-    raw = readFileSync(filePath, "utf8");
-  } catch (err: unknown) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
-    throw err;
-  }
-  const parsed = parseJson<unknown>(raw, null);
-  if (parsed === null) throw new ValidationError(`${LAND_GATES_FILE}: invalid JSON`);
-  return cleanLandGatesConfig(parsed, worktreePath);
-}
+// The land-gates config loader (#892) now lives in the SDK so the orchestrator
+// package — which advances `refs/heads/main` and therefore runs the gates — can
+// import the SAME implementation across the package boundary (it can only depend
+// on agent-relay-sdk, not this server package). Re-exported here so #892's
+// importers and co-located tests stay byte-unchanged. The canonical home is
+// `agent-relay-sdk/land-gates` (a non-barrel subpath: it reads from disk, so it
+// stays out of browser bundles).
+export { cleanLandGate, cleanLandGatesConfig, loadRepoLandGates } from "agent-relay-sdk/land-gates";

package/src/notification-types.ts

@@ -40,6 +40,8 @@ export type NotificationType =
   | "workspace.steward_reassigned"
   | "workspace.stranded_escalation"
   | "workspace.base_checkout_strand"
+  | "workspace.land_gate_failed"
+  | "workspace.land_gate_warning"
   | "workspace.auto_abandoned"
   | "workspace.review_request"
   | "workspace.review_changes_requested"
@@ -136,6 +138,13 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "workspace.steward_reassigned": null,
   "workspace.stranded_escalation": null,
   "workspace.base_checkout_strand": null,
+  // #902 — a required land gate blocked a land; the worker is parked idle after `ready` and
+  // must learn why its land bounced, so this is durable (about the recipient's own work).
+  "workspace.land_gate_failed": null,
+  // Optional-gate warning on an already-successful land — only useful while fresh, so it
+  // expires like other bystander/informational notices (= INFORMATIONAL_TTL_MS, inlined to
+  // avoid referencing that const before its declaration below).
+  "workspace.land_gate_warning": 30 * MINUTES,
   "workspace.auto_abandoned": null,
   "workspace.review_request": null,
   "workspace.review_changes_requested": null,

package/src/routes/agents-spawn.ts

@@ -1,5 +1,5 @@
 // Auto-split from routes.ts (#299). Domain: agents-spawn.
-import { APPROVAL_MODES, AUTO_MERGE_POLICIES, SPAWN_PROVIDERS, VALID_AGENT_LIFECYCLES, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
+import { APPROVAL_MODES, AUTO_MERGE_POLICIES, INTERNAL_SPAWN_TYPES, SPAWN_PROVIDERS, VALID_AGENT_LIFECYCLES, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { VALID_AGENT_STATUSES, error, json, parseBody, type Handler } from "./_shared";
 import { ValidationError, listAgents } from "../db";
@@ -15,6 +15,7 @@ import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
 import { quotaStateFromUnknown } from "../quota";
+import { resolveInternalSpawnTarget, type InternalSpawnType } from "../auto-spawn-dispatch";
 import { type AgentKind, type AgentLifecycle, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceAutoMergePolicy, type WorkspaceLandingPolicy, type WorkspaceMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 
@@ -118,8 +119,36 @@ export const postAgentSpawn: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("provider required");
-    const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider | undefined;
-    if (!provider) return error("provider required");
+
+    // #901 — server-side internalSpawnType: when present, the resolver picks provider/model/effort
+    // from routing policy + quota bands so no internal caller needs to hard-code a raw model alias.
+    // Explicit caller model/effort are forwarded as pins so they still win over the resolver.
+    // Spawns that omit internalSpawnType are byte-identical to before (normal user/coordinator spawns).
+    const internalSpawnType = cleanString(parsed.body.internalSpawnType, "internalSpawnType", { max: 80 });
+    let resolvedProvider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider | undefined;
+    let resolvedModel = cleanString(parsed.body.model, "model", { max: 120 });
+    let resolvedEffort = cleanString(parsed.body.effort, "effort", { max: 120 }) as ProviderEffort | undefined;
+
+    if (internalSpawnType) {
+      if (!(INTERNAL_SPAWN_TYPES as readonly string[]).includes(internalSpawnType)) {
+        return error(`internalSpawnType must be one of: ${INTERNAL_SPAWN_TYPES.join(", ")}`);
+      }
+      // Fold explicit caller pins into the resolver so "explicit pin wins" applies here too —
+      // a provider:"codex" pin with internalSpawnType (no model) must not assemble codex +
+      // the resolver's claude-specific model.
+      const callerPin = {
+        ...(resolvedProvider ? { provider: resolvedProvider } : {}),
+        ...(resolvedModel ? { model: resolvedModel } : {}),
+        ...(resolvedEffort ? { effort: resolvedEffort } : {}),
+      };
+      const decision = resolveInternalSpawnTarget(internalSpawnType as InternalSpawnType, callerPin);
+      resolvedProvider = decision.target.provider;
+      resolvedModel = decision.target.model;
+      resolvedEffort = decision.target.effort as ProviderEffort | undefined;
+    }
+
+    if (!resolvedProvider) return error("provider required");
+
     // Thin transport: parse wire → AuthContext → spawnAgent service → serialize. The gate
     // (command:spawn scope, #221 no-grandchild + quota, #323 resource), caller-context
     // inheritance (#328/#331/#324), profile validation, lineage stamping, host selection, and
@@ -127,11 +156,11 @@ export const postAgentSpawn: Handler = async (req) => {
     // (epic #342, #349). The dashboard authenticates with an admin `*` token, so the tightened
     // command:spawn requirement is transparent to it.
     const input: SpawnAgentInput = {
-      provider,
+      provider: resolvedProvider,
       orchestratorId: cleanString(parsed.body.orchestratorId, "orchestratorId", { max: 200 }),
       cwd: cleanString(parsed.body.cwd, "cwd", { max: 500 }),
-      model: cleanString(parsed.body.model, "model", { max: 120 }),
-      effort: cleanString(parsed.body.effort, "effort", { max: 120 }) as ProviderEffort | undefined,
+      model: resolvedModel,
+      effort: resolvedEffort,
       approvalMode: optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
       workspaceMode: optionalEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
       lifecycle: optionalEnum(parsed.body.lifecycle, "lifecycle", VALID_AGENT_LIFECYCLES) as AgentLifecycle | undefined,

package/src/routes/commands.ts

@@ -8,12 +8,13 @@ import { clearActiveMemories, injectAlwaysReloadMemories } from "../memory-servi
 import { getCommand, listCommands, updateCommand } from "../commands-db";
 import { emitOrchestratorStatus } from "../sse";
 import { getCompactionWatch } from "../compaction-watch";
-import { isRecord } from "agent-relay-sdk";
+import { isRecord, sanitizeFsName, type LandGateRunResult } from "agent-relay-sdk";
+import { storeTextArtifact } from "../artifact-text";
 import { authContextFromRequest } from "../services/auth-context";
 import { commandAuthorizationResource as dispatchCommandAuthorizationResource, dispatchCommand } from "../services/dispatch-command";
 import { emitWorkspaceTaskSemanticNotifications } from "../services/task-lifecycle";
 import { ServiceAuthError } from "../services/errors";
-import { notifyBaseWorktreeStrand, notifyBranchLandFailed, notifyBranchLanded } from "../branch-landed";
+import { notifyBaseWorktreeStrand, notifyBranchLandFailed, notifyBranchLanded, notifyLandGateFailed, notifyLandGateWarnings } from "../branch-landed";
 import { applyIdleRefreshResult } from "../maintenance/workspaces";
 import { seedProviderConfigs } from "../provider-config-store";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
@@ -24,6 +25,50 @@ import { type Command, type CommandStatus, type CreateCommandInput, type Workspa
 
 const VALID_COMMAND_STATUSES = ["pending", "accepted", "running", "succeeded", "failed", "timed_out", "rejected", "canceled"] as const;
 
+// #902 — normalize a land-gate run result that round-tripped through the command bus
+// (JSON, loosely typed) back into a LandGateRunResult. Returns undefined when the value
+// isn't a gate result, so the caller falls back to the generic land-failed path.
+function normalizeGateRunResult(value: unknown): LandGateRunResult | undefined {
+  if (!isRecord(value)) return undefined;
+  const name = typeof value.name === "string" ? value.name : undefined;
+  const command = typeof value.command === "string" ? value.command : "";
+  if (!name) return undefined;
+  return {
+    name,
+    command,
+    optional: value.optional === true,
+    passed: value.passed === true,
+    exitCode: typeof value.exitCode === "number" ? value.exitCode : null,
+    timedOut: value.timedOut === true,
+    durationMs: typeof value.durationMs === "number" ? value.durationMs : 0,
+    outputTail: typeof value.outputTail === "string" ? value.outputTail : "",
+    output: typeof value.output === "string" ? value.output : (typeof value.outputTail === "string" ? value.outputTail : ""),
+  };
+}
+
+function normalizeGateWarnings(value: unknown): LandGateRunResult[] {
+  if (!Array.isArray(value)) return [];
+  return value.map(normalizeGateRunResult).filter((g): g is LandGateRunResult => Boolean(g));
+}
+
+// Upload a gate's full output to a relay artifact; returns its id, or undefined on any
+// failure (artifact upload is best-effort — the tail still rides in the notification).
+async function uploadGateOutputArtifact(workspaceId: string, gate: LandGateRunResult): Promise<string | undefined> {
+  try {
+    const safeName = sanitizeFsName(gate.name, { replacement: "-", maxLen: 60, trimEdge: true, fallback: "gate" });
+    const stored = await storeTextArtifact({
+      text: gate.output || gate.outputTail || "(no output)",
+      filename: `land-gate-${safeName}-${workspaceId}.log`,
+      createdBy: "server",
+      metadata: { kind: "land-gate-output", workspaceId, gateName: gate.name, gateCommand: gate.command, exitCode: gate.exitCode, timedOut: gate.timedOut },
+    });
+    return stored.id;
+  } catch (error) {
+    console.warn(`land-gate artifact upload failed for ${workspaceId} gate "${gate.name}": ${String(error)}`);
+    return undefined;
+  }
+}
+
 function auditCommandOutcome(command: Command): void {
   if (command.status !== "succeeded" && command.status !== "failed") return;
   if (command.type !== "agent.restart" && command.type !== "agent.shutdown" && command.type !== "agent.reconnect") return;
@@ -284,6 +329,27 @@ export const patchCommand: Handler = async (req, params) => {
               pushed: prLanded ? true : typeof command.result.pushed === "boolean" ? command.result.pushed : undefined,
             });
           }
+          // #902 — OPTIONAL land gates that failed on a SUCCESSFUL land (merged:true, ref
+          // advanced). Warn the worker (tail + combined-output artifact) without blocking.
+          // Best-effort + isolated so a warn-notify throw can't undo the completed land.
+          const gateWarnings = command.result.merged === true ? normalizeGateWarnings(command.result.gateWarnings) : [];
+          if (gateWarnings.length && landedWorkspace) {
+            const warnWorkspace = landedWorkspace;
+            void (async () => {
+              const combined = gateWarnings.map((g) => `### ${g.name} (${g.command}) — ${g.timedOut ? "timed out" : g.exitCode === null ? "could not run" : `exited ${g.exitCode}`}\n${g.output || g.outputTail || "(no output)"}`).join("\n\n");
+              let artifactId: string | undefined;
+              try {
+                artifactId = (await storeTextArtifact({ text: combined, filename: `land-gate-warnings-${warnWorkspace.id}.log`, createdBy: "server", metadata: { kind: "land-gate-warnings", workspaceId: warnWorkspace.id, gateNames: gateWarnings.map((g) => g.name) } })).id;
+              } catch (error) {
+                console.warn(`land-gate-warnings artifact upload failed for ${warnWorkspace.id}: ${String(error)}`);
+              }
+              try {
+                notifyLandGateWarnings({ workspace: warnWorkspace, warnings: gateWarnings, artifactId });
+              } catch (error) {
+                console.warn(`land-gate-warnings notify threw for ${warnWorkspace.id}: ${String(error)}`);
+              }
+            })();
+          }
         }
       } else if (command.status === "failed" && command.correlationId) {
         // Merge couldn't complete — don't leave it stuck in merge_planned. A no-progress
@@ -319,11 +385,29 @@ export const patchCommand: Handler = async (req, params) => {
               },
             });
           }
-          notifyBranchLandFailed({
-            workspace: current,
-            commandId: command.id,
-            reason: command.error ?? "merge failed",
-          });
+          const gateFailure = isRecord(command.result) ? normalizeGateRunResult(command.result.gateFailure) : undefined;
+          if (gateFailure) {
+            // #902 — a REQUIRED land gate failed: the orchestrator aborted WITHOUT advancing
+            // the ref and settled status "review_requested" (not "conflict", so the steward
+            // path above is never taken). Send the richer worker+coordinator notice (gate name
+            // + output tail + full-output artifact) INSTEAD of the generic land-failed wake.
+            // Best-effort + isolated: the land already (didn't) happen; a notify/upload throw
+            // must not break command settling.
+            void (async () => {
+              const artifactId = await uploadGateOutputArtifact(current.id, gateFailure);
+              try {
+                notifyLandGateFailed({ workspace: current, gate: gateFailure, artifactId });
+              } catch (error) {
+                console.warn(`land-gate-failed notify threw for ${current.id}: ${String(error)}`);
+              }
+            })();
+          } else {
+            notifyBranchLandFailed({
+              workspace: current,
+              commandId: command.id,
+              reason: command.error ?? "merge failed",
+            });
+          }
         }
       }
     }