agent-relay-server 0.117.1 → 0.118.1

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",
+            });
+          }
         }
       }
     }

package/src/services/git-remote.ts

@@ -16,31 +16,42 @@ export function parseOwnerRepoFromRemote(url: string | undefined): string | unde
 }
 
 let remoteRepoCache: Map<string, string | undefined> | undefined;
+let remoteUrlCache: Map<string, string | undefined> | undefined;
 
-/**
- * `owner/repo` from a repo root's `origin` remote, cached per root. Works from any
- * subdirectory of the repo (`git -C` walks up). Returns undefined when the dir isn't a
- * git repo, has no `origin`, or the URL doesn't parse.
- */
-export function repoFromGitRemote(repoRoot: string | undefined): string | undefined {
+export function remoteUrlFromGitRemote(repoRoot: string | undefined): string | undefined {
   if (!repoRoot) return undefined;
-  if (!remoteRepoCache) remoteRepoCache = new Map();
-  if (remoteRepoCache.has(repoRoot)) return remoteRepoCache.get(repoRoot);
-  let repo: string | undefined;
+  if (!remoteUrlCache) remoteUrlCache = new Map();
+  if (remoteUrlCache.has(repoRoot)) return remoteUrlCache.get(repoRoot);
+  let url: string | undefined;
   try {
     const proc = Bun.spawnSync(["git", "-C", repoRoot, "remote", "get-url", "origin"], {
       stdin: "ignore",
       stdout: "pipe",
       stderr: "ignore",
     });
-    if (proc.exitCode === 0) repo = parseOwnerRepoFromRemote(Buffer.from(proc.stdout).toString("utf8"));
+    if (proc.exitCode === 0) url = Buffer.from(proc.stdout).toString("utf8").trim() || undefined;
   } catch {
-    repo = undefined;
+    url = undefined;
   }
+  remoteUrlCache.set(repoRoot, url);
+  return url;
+}
+
+/**
+ * `owner/repo` from a repo root's `origin` remote, cached per root. Works from any
+ * subdirectory of the repo (`git -C` walks up). Returns undefined when the dir isn't a
+ * git repo, has no `origin`, or the URL doesn't parse.
+ */
+export function repoFromGitRemote(repoRoot: string | undefined): string | undefined {
+  if (!repoRoot) return undefined;
+  if (!remoteRepoCache) remoteRepoCache = new Map();
+  if (remoteRepoCache.has(repoRoot)) return remoteRepoCache.get(repoRoot);
+  const repo = parseOwnerRepoFromRemote(remoteUrlFromGitRemote(repoRoot));
   remoteRepoCache.set(repoRoot, repo);
   return repo;
 }
 
 export function __resetRemoteRepoCacheForTests(): void {
   remoteRepoCache = undefined;
+  remoteUrlCache = undefined;
 }

package/src/services/project.ts

@@ -2,7 +2,7 @@ import { statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { addProjectRoot, ensureProject, resolveProjectForCwd, rootsForProject, setProjectIssueRepo } from "../db";
 import { ingestClaudeMd } from "../project-ingest";
-import { repoFromGitRemote } from "./git-remote";
+import { remoteUrlFromGitRemote, repoFromGitRemote } from "./git-remote";
 import type { Project, ProjectRoot } from "../types";
 
 interface EnsureProjectRootInput {
@@ -13,6 +13,10 @@ interface EnsureProjectRootInput {
   tenantId?: string;
   /** Explicit `owner/repo` override (#533); wins over the git-remote-derived default. */
   issueRepo?: string;
+  /** Explicit clone URL for host acquisition (#410); auto-derived from origin when omitted. */
+  remoteUrl?: string;
+  /** Optional branch/tag/ref for host acquisition (#410). */
+  ref?: string;
 }
 
 interface EnsureProjectRootResult {
@@ -38,7 +42,8 @@ export function ensureProjectRoot(input: EnsureProjectRootInput): EnsureProjectR
     ...(input.tenantId !== undefined ? { tenantId: input.tenantId } : {}),
     ...(input.issueRepo !== undefined ? { issueRepo: input.issueRepo } : {}),
   });
-  const roots = addProjectRoot(project.id, input.rootPath);
+  const remoteUrl = input.remoteUrl ?? remoteUrlFromGitRemote(input.rootPath);
+  const roots = addProjectRoot(project.id, input.rootPath, { remoteUrl, ref: input.ref });
   // Auto-derive issueRepo from the root's git remote (#533) when not explicitly provided.
   // `onlyIfNull` ensures an explicit override (or earlier derivation) is never clobbered.
   if (input.issueRepo === undefined && !project.issueRepo) {

package/src/services/spawn-agent.ts

@@ -86,6 +86,30 @@ function assertIsolatedSpawnHasGitRepo(cwd: string): void {
   throw new ValidationError(`workspaceMode "isolated" requires a git repo, but ${cwd} is not one. Pass an explicit cwd under a repo, or use workspaceMode "shared"/"inherit".`);
 }
 
+function acquisitionManifestFor(projectId: string, cwd: string): {
+  mode: "project-root";
+  projectId: string;
+  rootPath: string;
+  cwd: string;
+  remoteUrl: string;
+  ref?: string;
+  sync: "ff-only";
+} | undefined {
+  const root = rootsForProject(projectId)
+    .filter((candidate) => candidate.remoteUrl && isPathWithinBase(cwd, candidate.rootPath))
+    .sort((a, b) => b.rootPath.length - a.rootPath.length)[0];
+  if (!root?.remoteUrl) return undefined;
+  return {
+    mode: "project-root",
+    projectId,
+    rootPath: root.rootPath,
+    cwd,
+    remoteUrl: root.remoteUrl,
+    ...(root.ref ? { ref: root.ref } : {}),
+    sync: "ff-only",
+  };
+}
+
 function taskLinkedRepoCwd(taskId: number, callerCwd?: string): string {
   const task = getTaskDetail(taskId);
   if (!task) throw new ValidationError(`task ${taskId} not found or not a deliverable task`);
@@ -389,9 +413,10 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // #838 — spawn-with-task hydration. When a taskId is given, relay assembles the worker's
   // first-turn context FROM the durable Task (intent + linked-issue spec/acceptance + recorded
   // decisions + history + latest steer), resolved server-side ONCE, and projects it onto the
-  // provider-appropriate channel (Claude → systemPromptAppend; Codex/other → first message). The
-  // caller-supplied systemPromptAppend/prompt are preserved. Absent (no taskId) = byte-identical
-  // to today: `resolvedSystemPromptAppend`/`resolvedPrompt` stay the raw inputs.
+  // provider-appropriate channel (Claude → systemPromptAppend; Codex/other → first message).
+  // Caller prompt is not re-appended after hydration: auto-scaffolded prompt is already the Task
+  // intent, and explicit task spawns should use taskId + steer as their single instruction source.
+  // Absent (no taskId) = byte-identical to today: raw prompt/system append pass through.
   let resolvedSystemPromptAppend = input.systemPromptAppend;
   let resolvedPrompt = input.prompt;
   let hydratedTask: Awaited<ReturnType<typeof hydrateTaskContext>> | undefined;
@@ -441,8 +466,9 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // branch unless explicitly narrowed.
   const workspaceMode = input.workspaceMode ?? (callerId || input.taskId !== undefined ? ("isolated" as WorkspaceMode) : undefined);
   const lifecycle = input.lifecycle ?? "persistent";
+  const acquisition = callerProject ? acquisitionManifestFor(callerProject.id, resolvedCwd) : undefined;
   if (workspaceMode === "isolated" && (input.taskId !== undefined || input.workspaceMode === "isolated")) {
-    assertIsolatedSpawnHasGitRepo(resolvedCwd);
+    if (!acquisition) assertIsolatedSpawnHasGitRepo(resolvedCwd);
   }
 
   const spawnRequestId = input.spawnRequestId ?? generateSpawnRequestId();
@@ -580,6 +606,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       reviewer: input.reviewer,
       taskId: input.taskId,
       resumeWorkspace: input.resumeWorkspace,
+      acquisition,
       ...(expectReply ? { expectReply } : {}),
       policyName: input.policyName,
       spawnRequestId,

package/src/services/task-context-hydration.ts

@@ -333,9 +333,12 @@ function joinBlocks(...parts: Array<string | undefined>): string | undefined {
 
 /**
  * PURE projection: map the hydration brief onto the provider-contract spawn channel.
- * Caller-supplied systemPromptAppend/prompt are preserved (appended after the relay material).
- * The steer used as a first-message kick is sentinel-stripped so it cannot forge the
- * data fence in the (instruction-bearing) systemPromptAppend brief.
+ * Once a Task brief is hydrated, the caller prompt is not re-appended: for auto-scaffolded
+ * spawns it is already the Task intent, and for explicit task spawns the Task + steer are the
+ * single instruction source. Caller system append is preserved unless it already embeds the
+ * hydrated brief, which avoids delivering the same brief through both provider channels.
+ * The steer used as a first-message kick is sentinel-stripped so it cannot forge the data fence
+ * in the (instruction-bearing) systemPromptAppend brief.
  */
 export function projectTaskHydration(
   provider: SpawnProvider | string,
@@ -344,18 +347,29 @@ export function projectTaskHydration(
   callerSystemPromptAppend: string | undefined,
   callerPrompt: string | undefined,
 ): TaskHydrationProjection {
+  void callerPrompt;
+  const callerAppend = removeDuplicateContext(context, callerSystemPromptAppend);
   if (taskHydrationChannel(provider) === "append-system-prompt") {
     return {
-      systemPromptAppend: joinBlocks(context, callerSystemPromptAppend),
-      prompt: joinBlocks(steer ? stripSentinels(steer) : undefined, callerPrompt),
+      systemPromptAppend: joinBlocks(context, callerAppend),
+      prompt: joinBlocks(steer ? stripSentinels(steer) : undefined),
     };
   }
   return {
-    systemPromptAppend: joinBlocks(callerSystemPromptAppend),
-    prompt: joinBlocks(context, callerPrompt),
+    systemPromptAppend: joinBlocks(callerAppend),
+    prompt: joinBlocks(context),
   };
 }
 
+function removeDuplicateContext(context: string, value: string | undefined): string | undefined {
+  const ctx = context.trim();
+  const raw = value?.trim();
+  if (!raw) return undefined;
+  if (!ctx) return raw;
+  const cleaned = raw.split(ctx).map((part) => part.trim()).filter(Boolean).join("\n\n");
+  return cleaned || undefined;
+}
+
 function taskHydrationChannel(provider: SpawnProvider | string): "prompt" | "append-system-prompt" {
   return getManifest(provider)?.launch?.taskHydration?.channel ?? "prompt";
 }

package/src/spawn-command.ts

@@ -121,6 +121,16 @@ interface BuildSpawnCommandOptions {
   requestedVia?: string;
   /** #635 — relay-enriched resume-workspace target. Relayed verbatim to the orchestrator. */
   resumeWorkspace?: { branch: string; mode: "attach" | "branch-from"; worktreePath?: string; workspaceId?: string; baseRef?: string; baseSha?: string };
+  /** #410 — host-side lazy clone/sync manifest, applied before worktree prep. */
+  acquisition?: {
+    mode: "project-root";
+    projectId: string;
+    rootPath: string;
+    cwd: string;
+    remoteUrl: string;
+    ref?: string;
+    sync: "ff-only";
+  };
 
   /** Extra params merged last (e.g. Claude-resume fields). */
   extra?: Record<string, unknown>;
@@ -172,6 +182,7 @@ export function buildSpawnCommand(opts: BuildSpawnCommandOptions): Record<string
     ...def(opts.requestedVia, "requestedVia"),
     ...def(opts.spawnRequestId, "spawnRequestId"),
     ...def(opts.resumeWorkspace, "resumeWorkspace"),
+    ...def(opts.acquisition, "acquisition"),
     env: opts.env,
     requestedBy: opts.requestedBy,
     requestedAt: opts.requestedAt ?? Date.now(),

package/src/steward.ts

@@ -5,6 +5,9 @@ import { getSpawnPolicy, getStewardConfig, setConfig } from "./config-store";
 import { listOrchestrators } from "./db";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { renderTemplate } from "./prompt-resolver";
+import { resolveInternalSpawnTarget } from "./auto-spawn-dispatch";
+import type { DispatchPin } from "./task-dispatcher";
+import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import type { Orchestrator, SpawnPolicy, StewardConfig } from "./types";
 import { isPathWithinBase } from "./utils";
 
@@ -39,16 +42,27 @@ function desiredStewardPolicy(repoRoot: string, owner: Orchestrator, config: Ste
   // repo and those worktrees, and its provider-agent token's cwdPrefixes derive
   // from this cwd — baseDir is their common ancestor, so the merge action against a
   // worktree path passes authorization. The prompt scopes it to the specific repo.
+
+  // #901 — resolve via the auto-spawn dispatcher so routing policy + quota bands pick
+  // the model. StewardConfig.provider/model/effort are OPTIONAL EXPLICIT PINS: when set
+  // by the operator they fold into the DispatchPin and win over the router's choice.
+  const pin: DispatchPin = {
+    provider: config.provider,
+    ...(config.model ? { model: config.model } : {}),
+    ...(config.effort ? { effort: config.effort } : {}),
+  };
+  const resolved = resolveInternalSpawnTarget("landing-steward", pin);
+
   return {
     name: repoStewardPolicyName(repoRoot),
     description: `Autonomous repo steward for ${repoRoot} (issue #167).`,
     enabled: true,
     orchestratorId: owner.id,
     cwd: owner.baseDir,
-    provider: config.provider,
+    provider: resolved.target.provider,
     workspaceMode: "inherit",
-    ...(config.model ? { model: config.model } : {}),
-    ...(config.effort ? { effort: config.effort } : {}),
+    ...(resolved.target.model ? { model: resolved.target.model } : {}),
+    ...(resolved.target.effort ? { effort: resolved.target.effort } : {}),
     providerArgs: [],
     prompt: buildStewardPrompt(repoRoot),
     tags: ["steward"],
@@ -65,18 +79,36 @@ function desiredStewardPolicy(repoRoot: string, owner: Orchestrator, config: Ste
 
 // Fields whose change means the persisted policy should be refreshed. Avoids
 // churning the config version (and the lifecycle reconcile) every sweep.
+//
+// Churn guard (#901): model-only diffs are suppressed when the stored model is still
+// enabled+available — quota-band oscillation would otherwise change the resolved model on
+// every sweep and trigger a lifecycle reconcile each time. Provider changes ARE compared —
+// a genuine provider switch must always propagate.
+// Self-heal exception: if the stored model is explicitly disabled/unavailable in the
+// effective catalog, allow the diff so the steward refreshes onto an enabled model.
 function stewardPolicyDiffers(existing: SpawnPolicy, desired: SpawnPolicy): boolean {
-  return (
+  if (
     existing.enabled !== desired.enabled ||
     existing.provider !== desired.provider ||
-    existing.model !== desired.model ||
     existing.effort !== desired.effort ||
     existing.permissionMode !== desired.permissionMode ||
     existing.cwd !== desired.cwd ||
     existing.orchestratorId !== desired.orchestratorId ||
     existing.prompt !== desired.prompt ||
     existing.onDemand?.keepaliveSeconds !== desired.onDemand?.keepaliveSeconds
-  );
+  ) return true;
+
+  // Model-only diff: suppress (anti-thrash) unless the stored model is disabled/unavailable.
+  if (existing.model !== desired.model && existing.model) {
+    const catalog = effectiveProviderCatalogList();
+    const providerEntry = catalog.find((c) => c.provider === existing.provider);
+    const storedModel = providerEntry?.models.find((m) => m.alias === existing.model || m.providerModel === existing.model);
+    // Only trigger refresh when the model is EXPLICITLY disabled/unavailable in the catalog.
+    // If it's simply absent (incomplete catalog data), suppress to avoid false churn.
+    if (storedModel && (storedModel.disabled || storedModel.unavailable)) return true;
+  }
+
+  return false;
 }
 
 /**