agent-relay-server 0.117.1 → 0.118.1

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.1",
   "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/db/migrations.ts

@@ -26,8 +26,8 @@ import { seedBundledProvisioningAssets, seedSharedCallmuxProvisioningAssets } fr
 import { provisioningAssetsColumnNames, provisioningAssetsNeedsRebuild, rebuildProvisioningAssetsTable } from "./provisioning-assets-migration.ts";
 import { normalizeReactionEmoji } from "./mappers.ts";
 import { normalizeProviderQuotaAccountKeys } from "./provider-quotas.ts";
-import { projectRootsMissingIssueRepo, setProjectIssueRepo } from "./projects.ts";
-import { repoFromGitRemote } from "../services/git-remote.ts";
+import { projectRootsMissingIssueRepo, projectRootsMissingRemoteUrl, setProjectIssueRepo, setProjectRootRemoteUrl } from "./projects.ts";
+import { remoteUrlFromGitRemote, repoFromGitRemote } from "../services/git-remote.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -136,6 +136,17 @@ function backfillProjectIssueRepos(): void {
   }
 }
 
+function backfillProjectRootRemoteUrls(): void {
+  for (const row of projectRootsMissingRemoteUrl()) {
+    try {
+      const remoteUrl = remoteUrlFromGitRemote(row.rootPath);
+      if (remoteUrl) setProjectRootRemoteUrl(row.projectId, row.rootPath, remoteUrl, { onlyIfNull: true });
+    } catch {
+      // Best-effort startup repair: a missing root or unavailable git must not block Relay.
+    }
+  }
+}
+
 
 // Incremental schema migrations + one-shot backfills, applied after the base DDL
 // in initDb(). Ordering matters: each block guards on the current column/table
@@ -512,7 +523,16 @@ export function applyMigrations(): void {
     getDb().run("ALTER TABLE projects ADD COLUMN anchor_key TEXT");
   }
   getDb().run("CREATE INDEX IF NOT EXISTS idx_projects_scope_anchor ON projects(scope, anchor_key)");
+  // Migration: project_roots.remote_url/ref (#410) — clone/sync manifest metadata.
+  const projectRootCols = (getDb().query("PRAGMA table_info(project_roots)").all() as any[]).map((c: any) => c.name);
+  if (!projectRootCols.includes("remote_url")) {
+    getDb().run("ALTER TABLE project_roots ADD COLUMN remote_url TEXT");
+  }
+  if (!projectRootCols.includes("ref")) {
+    getDb().run("ALTER TABLE project_roots ADD COLUMN ref TEXT");
+  }
   backfillProjectIssueRepos();
+  backfillProjectRootRemoteUrls();
 
   // Migration: orchestrators.api_url
   const orchCols = getDb().query("PRAGMA table_info(orchestrators)").all() as any[];

package/src/db/projects.ts

@@ -25,6 +25,8 @@ interface ProjectRow {
 interface ProjectRootRow {
   project_id: string;
   root_path: string;
+  remote_url: string | null;
+  ref: string | null;
   created_at: number;
 }
 
@@ -49,7 +51,13 @@ function rowToProject(row: ProjectRow): Project {
 }
 
 function rowToRoot(row: ProjectRootRow): ProjectRoot {
-  return { projectId: row.project_id, rootPath: row.root_path, createdAt: row.created_at };
+  return {
+    projectId: row.project_id,
+    rootPath: row.root_path,
+    ...(row.remote_url ? { remoteUrl: row.remote_url } : {}),
+    ...(row.ref ? { ref: row.ref } : {}),
+    createdAt: row.created_at,
+  };
 }
 
 export function getProject(id: string): Project | null {
@@ -103,6 +111,26 @@ export function projectRootsMissingIssueRepo(): Array<{ projectId: string; rootP
   `).all() as Array<{ projectId: string; rootPath: string }>;
 }
 
+export function projectRootsMissingRemoteUrl(): Array<{ projectId: string; rootPath: string }> {
+  return getDb().query(`
+    SELECT project_id AS projectId, root_path AS rootPath
+    FROM project_roots
+    WHERE remote_url IS NULL OR trim(remote_url) = ''
+    ORDER BY project_id ASC, root_path ASC
+  `).all() as Array<{ projectId: string; rootPath: string }>;
+}
+
+export function setProjectRootRemoteUrl(projectId: string, rootPath: string, remoteUrl: string | null, opts: { onlyIfNull?: boolean } = {}): ProjectRoot[] {
+  const value = remoteUrl?.trim() || null;
+  const current = getDb()
+    .query("SELECT remote_url FROM project_roots WHERE project_id = ? AND root_path = ?")
+    .get(projectId, rootPath) as { remote_url: string | null } | undefined;
+  if (!current) throw new ValidationError(`project root not found: ${rootPath}`);
+  if (opts.onlyIfNull && current.remote_url) return rootsForProject(projectId);
+  getDb().query("UPDATE project_roots SET remote_url = ? WHERE project_id = ? AND root_path = ?").run(value, projectId, rootPath);
+  return rootsForProject(projectId);
+}
+
 interface EnsureProjectInput {
   slug: string;
   title?: string;
@@ -216,16 +244,20 @@ export function setProjectIssueRepo(id: string, issueRepo: string | null, opts:
 }
 
 /** Register a root path for a project (idempotent — UNIQUE(project_id, root_path)). */
-export function addProjectRoot(id: string, rootPath: string): ProjectRoot[] {
+export function addProjectRoot(id: string, rootPath: string, opts: { remoteUrl?: string | null; ref?: string | null } = {}): ProjectRoot[] {
   const project = getProject(id);
   if (!project) throw new ValidationError(`project ${id} not found`);
   const path = rootPath.trim();
   if (!path) throw new ValidationError("rootPath required");
+  const remoteUrl = opts.remoteUrl?.trim() || null;
+  const ref = opts.ref?.trim() || null;
   getDb().query(`
-    INSERT INTO project_roots (project_id, root_path, created_at)
-    VALUES (?, ?, ?)
-    ON CONFLICT(project_id, root_path) DO NOTHING
-  `).run(id, path, Date.now());
+    INSERT INTO project_roots (project_id, root_path, remote_url, ref, created_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(project_id, root_path) DO UPDATE SET
+      remote_url = coalesce(excluded.remote_url, project_roots.remote_url),
+      ref = coalesce(excluded.ref, project_roots.ref)
+  `).run(id, path, remoteUrl, ref, Date.now());
   return rootsForProject(id);
 }
 

package/src/db/schema.ts

@@ -268,6 +268,8 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE TABLE IF NOT EXISTS project_roots (
       project_id TEXT NOT NULL,
       root_path TEXT NOT NULL,
+      remote_url TEXT,
+      ref TEXT,
       created_at INTEGER NOT NULL,
       UNIQUE(project_id, root_path)
     );

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/mcp-project-tools.ts

@@ -59,6 +59,8 @@ export const PROJECT_TOOLS = [
       properties: {
         slug: { type: "string" },
         rootPath: { type: "string" },
+        remoteUrl: { type: "string" },
+        ref: { type: "string" },
         title: { type: "string" },
         description: { type: "string" },
         tenantId: { type: "string" },
@@ -271,6 +273,8 @@ export function relayProjectTool(auth: McpAuthLike, name: string, args: Record<s
     const { project, roots } = ensureProjectRoot({
       slug,
       rootPath,
+      remoteUrl: cleanString(args.remoteUrl, "remoteUrl", { max: 4000 }),
+      ref: cleanString(args.ref, "ref", { max: 240 }),
       title: cleanString(args.title, "title", { max: 240 }),
       description: cleanString(args.description, "description", { max: 16_000 }),
       tenantId: cleanString(args.tenantId, "tenantId", { max: 200 }),

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,