agent-relay-server 0.120.4 → 0.120.6

package/src/db/provisioning-resolve.ts

@@ -0,0 +1,245 @@
+// Profile provisioning resolution lives outside provisioning-registry.ts so the
+// registry CRUD/vendoring module stays under the file-size ratchet.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getManifest, type ProviderManifest } from "agent-relay-providers";
+import { isRecord } from "agent-relay-sdk";
+import type {
+  AgentProfile,
+  AgentProfileAssetRef,
+  AgentProfileProvider,
+  PluginAssetDefinition,
+  ProvisioningAssetKind,
+  ProvisioningMcpServer,
+  ProvisioningSkip,
+  ResolvedAssetDefinition,
+  ResolvedProvisioning,
+  SkillAssetDefinition,
+  SpawnProvider,
+} from "agent-relay-sdk";
+import { getDb } from "./connection.ts";
+import { parseJson } from "../utils";
+
+type ProviderBundledSkillSetDescriptor = NonNullable<NonNullable<ProviderManifest["provisioning"]>["bundledSkills"]>;
+
+interface ProvisioningCapabilityResolutionRow {
+  id: string;
+  slug: string;
+  kind: ProvisioningAssetKind;
+  status: string;
+}
+
+interface ProvisioningAssetResolutionRow {
+  kind: ProvisioningAssetKind;
+  name: string;
+  provider: AgentProfileProvider;
+  definition: string;
+  enabled: number;
+  approval_status?: string | null;
+  validation_status?: string | null;
+  validation_errors?: string | null;
+}
+
+interface RegistryResolution {
+  definition: ResolvedAssetDefinition | null;
+  skip?: ProvisioningSkip;
+}
+
+export function bundledSkillRefs(descriptor: ProviderBundledSkillSetDescriptor): string[] {
+  const skillsDir = resolve(import.meta.dir, "../../", descriptor.dir);
+  const entryFile = descriptor.entryFile ?? "SKILL.md";
+  if (!existsSync(skillsDir)) return [];
+  return readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && existsSync(join(skillsDir, entry.name, entryFile)))
+    .map((entry) => descriptor.refPrefix + entry.name).sort();
+}
+
+export function stringRecord(value: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}
+
+function rowDefinition(row: ProvisioningAssetResolutionRow): ResolvedAssetDefinition {
+  return parseJson<ResolvedAssetDefinition>(row.definition, { kind: row.kind, name: row.name } as ResolvedAssetDefinition);
+}
+
+function skip(kind: ProvisioningAssetKind, ref: string, provider: SpawnProvider, reason: ProvisioningSkip["reason"], detail: string): ProvisioningSkip {
+  return { kind, ref, provider, reason, detail };
+}
+
+function variantSkipReason(row: ProvisioningAssetResolutionRow): Pick<ProvisioningSkip, "reason" | "detail"> | null {
+  if (row.enabled !== 1) return { reason: "disabled", detail: "Registry variant is disabled." };
+  if (row.approval_status !== "approved") return { reason: "unapproved", detail: `Registry variant approval_status is ${row.approval_status ?? "unset"}.` };
+  if (row.validation_status !== "valid") {
+    const errors = parseJson<unknown[]>(row.validation_errors ?? "[]", []);
+    const detail = errors.length ? `Registry variant validation_status is ${row.validation_status}; ${JSON.stringify(errors)}` : `Registry variant validation_status is ${row.validation_status ?? "unset"}.`;
+    return { reason: "invalid", detail };
+  }
+  return null;
+}
+
+// Resolve a registry ref for a target provider: an approved/valid/enabled exact
+// provider match wins, else provider-neutral "any". MCP is intentionally
+// provider-neutral in v1, so only "any" MCP variants are candidates.
+function resolveRegistryDefinition(kind: ProvisioningAssetKind, ref: string, provider: SpawnProvider): RegistryResolution {
+  const capability = getDb()
+    .query("SELECT id, slug, kind, status FROM provisioning_capabilities WHERE kind = ? AND slug = ?")
+    .get(kind, ref) as ProvisioningCapabilityResolutionRow | undefined;
+  if (!capability) {
+    return { definition: null, skip: skip(kind, ref, provider, "missing", "No provisioning capability exists for this ref.") };
+  }
+
+  const rows = getDb()
+    .query("SELECT * FROM provisioning_assets WHERE capability_id = ? ORDER BY CASE provider WHEN ? THEN 0 WHEN 'any' THEN 1 ELSE 2 END, provider")
+    .all(capability.id, provider) as ProvisioningAssetResolutionRow[];
+  const providerCandidates = rows.filter((row) => kind === "mcp" ? row.provider === "any" : row.provider === provider || row.provider === "any");
+  if (!providerCandidates.length) {
+    const label = getManifest(provider)?.label ?? provider;
+    return { definition: null, skip: skip(kind, ref, provider, "provider_mismatch", `No ${label} variant exists for capability ${ref}.`) };
+  }
+
+  for (const row of providerCandidates) {
+    if (!variantSkipReason(row)) return { definition: rowDefinition(row) };
+  }
+
+  const blocked = variantSkipReason(providerCandidates[0]!);
+  return { definition: null, skip: skip(kind, ref, provider, blocked?.reason ?? "missing", blocked?.detail ?? "No resolvable registry variant exists.") };
+}
+
+// A ref applies to a launch iff it's enabled and its provider scope includes the
+// target ("any"/undefined → all providers).
+function refAppliesToProvider(ref: AgentProfileAssetRef, provider: SpawnProvider): boolean {
+  return ref.enabled && (!ref.provider || ref.provider === "any" || ref.provider === provider);
+}
+
+function hasAssetRef(refs: AgentProfileAssetRef[], source: AgentProfileAssetRef["source"], ref: string): boolean {
+  return refs.some((item) => item.source === source && item.ref === ref);
+}
+
+function relayBundledProvisioningRefs(profile: AgentProfile, provider: SpawnProvider): Pick<AgentProfile, "skills" | "plugins"> {
+  const skills = [...(profile.skills ?? [])];
+  const plugins = [...(profile.plugins ?? [])];
+  const provisioning = getManifest(provider)?.provisioning;
+  if (profile.relay.skills !== false && provisioning?.bundledSkills) {
+    for (const ref of bundledSkillRefs(provisioning.bundledSkills)) {
+      if (!hasAssetRef(skills, "relay", ref)) skills.push({ source: "relay", ref, enabled: true, provider });
+    }
+  }
+  if (profile.relay.plugins !== false && provisioning?.bundledPlugin && !hasAssetRef(plugins, "relay", provisioning.bundledPlugin.ref)) {
+    plugins.push({ source: "relay", ref: provisioning.bundledPlugin.ref, enabled: true, provider });
+  }
+  return { skills, plugins };
+}
+
+function withRelayBundledProvisioningRefs(profile: AgentProfile, provider: SpawnProvider): AgentProfile {
+  const { skills, plugins } = relayBundledProvisioningRefs(profile, provider);
+  return { ...profile, skills, plugins };
+}
+
+function inlineFilesFromMeta(meta: Record<string, unknown> | undefined): { path: string; content: string }[] | undefined {
+  const raw = meta?.files;
+  if (!Array.isArray(raw)) return undefined;
+  const files = raw
+    .filter(isRecord)
+    .filter((f) => typeof f.path === "string" && typeof f.content === "string")
+    .map((f) => ({ path: f.path as string, content: f.content as string }));
+  return files.length ? files : undefined;
+}
+
+// Resolve a skill/plugin asset ref into a concrete definition. relay → registry;
+// inline → built from ref.meta (files or dir); repo → a cwd-relative dir token the
+// runner resolves against the launch cwd; provider → skipped (provider built-in).
+function resolveDirAssetRef(
+  kind: "skill" | "plugin",
+  ref: AgentProfileAssetRef,
+  provider: SpawnProvider,
+): { definition: SkillAssetDefinition | PluginAssetDefinition | null; skip?: ProvisioningSkip } {
+  if (ref.source === "relay") {
+    const resolved = resolveRegistryDefinition(kind, ref.ref, provider);
+    const def = resolved.definition;
+    return { definition: def && def.kind === kind ? def : null, skip: resolved.skip };
+  }
+  if (ref.source === "inline") {
+    const files = inlineFilesFromMeta(ref.meta);
+    const dir = typeof ref.meta?.dir === "string" ? ref.meta.dir : undefined;
+    if (!files && !dir) return { definition: null, skip: skip(kind, ref.ref, provider, "invalid_inline", `Inline ${kind} ref requires files or dir metadata.`) };
+    return { definition: { kind, name: ref.ref, ...(files ? { files } : {}), ...(dir ? { dir } : {}) } };
+  }
+  if (ref.source === "repo") {
+    return { definition: { kind, name: ref.ref, dir: ref.ref } };
+  }
+  return { definition: null };
+}
+
+// A profile.mcp.servers entry is either an inline server spec or a registry
+// reference (`{ source: "relay", ref }`). Returns the concrete server spec.
+function resolveMcpEntry(name: string, value: unknown, provider: SpawnProvider): { server: ProvisioningMcpServer | null; skip?: ProvisioningSkip } {
+  if (!isRecord(value)) return { server: null };
+  if (value.source === "relay" && typeof value.ref === "string") {
+    const resolved = resolveRegistryDefinition("mcp", value.ref, provider);
+    const def = resolved.definition;
+    return { server: def && def.kind === "mcp" ? def.server : null, skip: resolved.skip };
+  }
+  if (value.enabled === false) return { server: null };
+  // Inline spec: keep the recognized server fields only.
+  const server: ProvisioningMcpServer = {};
+  if (typeof value.type === "string") server.type = value.type as ProvisioningMcpServer["type"];
+  if (typeof value.command === "string") server.command = value.command;
+  if (Array.isArray(value.args)) server.args = value.args.filter((a): a is string => typeof a === "string");
+  if (isRecord(value.env)) server.env = stringRecord(value.env);
+  if (isRecord(value.configEnv)) server.configEnv = stringRecord(value.configEnv);
+  if (typeof value.url === "string") server.url = value.url;
+  if (isRecord(value.headers)) server.headers = stringRecord(value.headers);
+  return { server: server.command || server.url ? server : null, skip: server.command || server.url ? undefined : skip("mcp", name, provider, "invalid_inline", "Inline MCP server requires command or url.") };
+}
+
+// Resolve a profile's declared skill/plugin/MCP refs against the registry into the
+// concrete bundle the runner materializes. Relay-side (needs the DB); the result is
+// attached to the in-flight profile (profile.provisioning) before it's serialized
+// into the spawn env. Pure read — never mutates the registry.
+export function resolveProfileProvisioning(profile: AgentProfile, provider: SpawnProvider): ResolvedProvisioning {
+  const skills: SkillAssetDefinition[] = [];
+  const skipped: ProvisioningSkip[] = [];
+  for (const ref of profile.skills ?? []) {
+    if (!refAppliesToProvider(ref, provider)) {
+      if (ref.enabled && ref.source === "relay") skipped.push(skip("skill", ref.ref, provider, "provider_mismatch", `Profile ref is scoped to provider ${ref.provider}.`));
+      continue;
+    }
+    const resolved = resolveDirAssetRef("skill", ref, provider);
+    if (resolved.definition) skills.push(resolved.definition as SkillAssetDefinition);
+    else if (resolved.skip) skipped.push(resolved.skip);
+  }
+
+  const plugins: PluginAssetDefinition[] = [];
+  for (const ref of profile.plugins ?? []) {
+    if (!refAppliesToProvider(ref, provider)) {
+      if (ref.enabled && ref.source === "relay") skipped.push(skip("plugin", ref.ref, provider, "provider_mismatch", `Profile ref is scoped to provider ${ref.provider}.`));
+      continue;
+    }
+    const resolved = resolveDirAssetRef("plugin", ref, provider);
+    if (resolved.definition) plugins.push(resolved.definition as PluginAssetDefinition);
+    else if (resolved.skip) skipped.push(resolved.skip);
+  }
+
+  const mcpServers: Record<string, ProvisioningMcpServer> = {};
+  for (const [name, value] of Object.entries(profile.mcp?.servers ?? {})) {
+    const resolved = resolveMcpEntry(name, value, provider);
+    if (resolved.server) mcpServers[name] = resolved.server;
+    else if (resolved.skip) skipped.push(resolved.skip);
+  }
+
+  return { skills, plugins, mcpServers, ...(skipped.length ? { skipped } : {}) };
+}
+
+// Attach the resolved bundle to a spawn-bound profile. Returns a shallow copy so the
+// cached config-store value is never mutated. undefined passes through (an unresolved
+// profile name stays undefined so callers' not-found guards still fire); the runner
+// treats an absent and an empty bundle identically.
+export function withResolvedProvisioning(profile: AgentProfile | undefined, provider: SpawnProvider): AgentProfile | undefined {
+  if (!profile) return undefined;
+  const composed = withRelayBundledProvisioningRefs(profile, provider);
+  return { ...composed, provisioning: resolveProfileProvisioning(composed, provider) };
+}

package/src/db/stats.ts

@@ -16,7 +16,7 @@ import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_ME
 import { matchAgents } from "../agent-ref";
 import { listAgents } from "./agents.ts";
 import { listChannels } from "./channels.ts";
-import { countExpiredUndeliveredMessages } from "./delivery.ts";
+import { summarizeExpiredUndeliveredMessages } from "./delivery.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { claimTaskWhere } from "./task-core.ts";
 import { getDb } from "./connection.ts";
@@ -489,14 +489,17 @@ export function getHealth(now: number = Date.now()): HealthReport {
       : undefined,
   });
 
-  const expiredUndelivered = countExpiredUndeliveredMessages(now);
+  const expiredUndelivered = summarizeExpiredUndeliveredMessages(now);
   checks.push({
     name: "expired-undelivered-messages",
-    status: expiredUndelivered > 0 ? "warn" : "ok",
-    count: expiredUndelivered,
-    detail: expiredUndelivered > 0
-      ? `${expiredUndelivered} queued message(s) expired undelivered at max_age in the last 24h (silent data loss)`
-      : undefined,
+    status: expiredUndelivered.unexplainedCount > 0 ? "warn" : "ok",
+    count: expiredUndelivered.unexplainedCount,
+    detail: expiredUndelivered.unexplainedCount > 0
+      ? `${expiredUndelivered.unexplainedCount} queued message(s) expired undelivered at max_age in the last 24h (silent data loss)${expiredUndelivered.explainedManagedPolicyCount > 0 ? `; ${expiredUndelivered.explainedManagedPolicyCount} managed-policy expiry(s) explained by policy health` : ""}`
+      : expiredUndelivered.explainedManagedPolicyCount > 0
+        ? `${expiredUndelivered.explainedManagedPolicyCount} queued managed-policy message(s) expired while the policy target was unavailable; tracked by spawn-policy health, not silent data loss`
+        : undefined,
+    subjects: expiredUndelivered.subjects.length > 0 ? expiredUndelivered.subjects : undefined,
   });
 
   const rootTokenRuntimeAgents = listAgents().filter((agent) => {
@@ -539,4 +542,3 @@ export function getHealth(now: number = Date.now()): HealthReport {
       : "ok";
   return { status, version: VERSION, generatedAt: now, checks };
 }
-

package/src/db/task-entity.ts

@@ -152,7 +152,7 @@ export interface CreateDeliverableTaskInput {
   intent: string;
   complexity?: TaskComplexity;
   context?: string;
-  doneWhen?: string;
+  doneWhen?: string; branch?: string;
   teamId?: string;
   projectId?: string;
   repo?: string;
@@ -171,25 +171,24 @@ export function createDeliverableTask(input: CreateDeliverableTaskInput): TaskDe
   const dispatch = cleanDispatch(input.dispatch);
   const complexity = cleanTaskComplexity(input.complexity ?? dispatch?.complexity, "complexity") ?? DEFAULT_TASK_COMPLEXITY;
   const context = optionalText(input.context, "context", 1_000_000);
+  const branch = optionalText(input.branch, "branch", 500);
   const taskProject = cleanTaskProject(input);
   // Legacy NOT-NULL columns have no DB defaults (#834 finding 6) — set them explicitly.
   const result = getDb().query(`
     INSERT INTO tasks (
       source, title, body, severity, status, target, occurrence_count, metadata,
       created_at, updated_at, last_seen_at,
-      kind, intent, complexity, context, latest_steer, deliverable_stage, done_when, team_id, project_id, repo, created_by, dispatch
-    ) VALUES (?, ?, ?, 'info', 'open', ?, 1, '{}', ?, ?, ?, '${DELIVERABLE_TASK_KIND}', ?, ?, ?, ?, 'none', ?, ?, ?, ?, ?, ?)
+      kind, intent, complexity, context, latest_steer, deliverable_stage, done_when, branch, team_id, project_id, repo, created_by, dispatch
+    ) VALUES (?, ?, ?, 'info', 'open', ?, 1, '{}', ?, ?, ?, '${DELIVERABLE_TASK_KIND}', ?, ?, ?, ?, 'none', ?, ?, ?, ?, ?, ?, ?)
   `).run(
     optionalText(input.source, "source", 200) ?? "coordinator",
     title,
     intent,
     optionalText(input.target, "target", 200) ?? createdBy,
-    now, now, now,
-    intent,
-    complexity,
-    context ?? null,
+    now, now, now, intent, complexity, context ?? null,
     optionalText(input.latestSteer, "latestSteer", 1_000_000) ?? null,
     optionalText(input.doneWhen, "doneWhen", 1_000_000) ?? null,
+    branch ?? null,
     optionalText(input.teamId, "teamId", 200) ?? null,
     taskProject.projectId ?? null,
     taskProject.repo ?? null,
@@ -203,7 +202,7 @@ export function createDeliverableTask(input: CreateDeliverableTaskInput): TaskDe
     severity: "info",
     title: `Task created: ${title}`,
     body: intent,
-    metadata: { createdBy, complexity, ...(context ? { context } : {}), ...(taskProject.projectId ? { projectId: taskProject.projectId } : {}), ...(taskProject.repo ? { repo: taskProject.repo } : {}), ...(dispatch ? { dispatch } : {}) },
+    metadata: { createdBy, complexity, ...(context ? { context } : {}), ...(branch ? { branch } : {}), ...(taskProject.projectId ? { projectId: taskProject.projectId } : {}), ...(taskProject.repo ? { repo: taskProject.repo } : {}), ...(dispatch ? { dispatch } : {}) },
   }, now);
   return getTaskDetail(id)!;
 }

package/src/lifecycle-manager.ts

@@ -2,14 +2,10 @@ import { createCommand } from "./commands-db";
 import { workspaceOwnerOrchestrator } from "./workspace-host";
 import { agentProviderState } from "./provider-state";
 import { createActivityEvent, deleteWorkspace, getAgent, getDb, getOrchestrator, listOrchestrators, listWorkspaces } from "./db";
-import {
-  getManagedAgentState,
-  listSpawnPolicies,
-  updateManagedAgentState,
-  upsertManagedAgentState,
-} from "./config-store";
+import { getManagedAgentState, listSpawnPolicies, updateManagedAgentState, upsertManagedAgentState } from "./config-store";
 import { emitRelayEvent } from "./events";
 import { alwaysReloadTags, reconcileLifecycleContextPressure, requestAgentCompact } from "./lifecycle-context-pressure";
+import { escalateOfflineOrchestrator } from "./managed-policy-escalation";
 import { markManagedAgentRunning, emitManagedState } from "./services/managed-running";
 import { authContextFromSystem } from "./services/auth-context";
 import { emitCommandEvent } from "./command-events";
@@ -189,15 +185,18 @@ export class LifecycleManager {
   spawnAgent(policy: SpawnPolicy, reason = "reconcile"): Command | null {
     const orch = getOrchestrator(policy.orchestratorId);
     if (!orch || orch.status !== "online") {
-      const state = upsertManagedAgentState({
+      const state = getManagedAgentState(policy.name) ?? {
         policyName: policy.name,
-        status: "backoff",
+        status: "stopped" as const,
         orchestratorId: policy.orchestratorId,
         provider: policy.provider,
-        backoffUntil: this.now() + this.backoffDelay(policy, getManagedAgentState(policy.name)) * 1000,
-        lastError: "orchestrator offline",
-      });
-      this.emitState(state);
+        restartCount: 0,
+        consecutiveFailures: 0,
+        updatedAt: this.now(),
+      };
+      this.markBackoff(policy, state, "orchestrator offline");
+      const next = getManagedAgentState(policy.name);
+      if (next) escalateOfflineOrchestrator(policy, next, orch);
       return null;
     }
     const spawnRequestId = generateSpawnRequestId();

package/src/maintenance/jobs.ts

@@ -27,10 +27,11 @@ import { isAgentUnavailable } from "../db/agent-predicates";
 import { flushQueuedDirectMessages } from "../services/managed-running";
 import { notifyAgentOffline } from "../agent-lifecycle-events";
 import { diagnoseAgentDeath } from "../agent-death-diagnosis";
-import { autoMergeCleanFastForwards, runAutoMergeWatchdog } from "../workspace-auto-merge";
+import { autoMergeCleanFastForwards, runAutoMergeWatchdog, scheduleRepoMerge } from "../workspace-auto-merge";
 import { reapOrphanedWorktrees } from "../workspace-orphans";
 import { getLifecycleManager } from "../lifecycle-manager";
 import { applyCommandToRecipe } from "../recipe-runner";
+import { settleWorkspaceCommand } from "../workspace-command-settle";
 import {
   emitAgentRemoved,
   emitAgentStatus,
@@ -237,6 +238,7 @@ export const definitions: MaintenanceJobDefinition[] = [
     handler() {
       const commands = expireCommands();
       for (const command of commands) {
+        settleWorkspaceCommand(command, { onMergeSettled: scheduleRepoMerge });
         applyCommandToRecipe(command);
         emitCommand(command);
       }

package/src/maintenance/workspaces.ts

@@ -21,6 +21,7 @@ import { preparePrCompletionScan, reconcileLandedPr } from "../workspace-pr-comp
 import { applyBranchFreshness, fetchHostMergePreview, workspacePathWithinBase } from "../workspace-probe";
 import { wakeRepoSteward } from "../workspace-auto-merge";
 import { workspaceOwnerOrchestrator } from "../workspace-host";
+import { routeWorkspaceCustodyEscalation } from "../workspace-escalation";
 import {
   CONFLICT_SCAN_STATUSES,
   DAY_MS,
@@ -175,74 +176,53 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
   const escalationTargets: string[] = [];
   const reconciledLandedIds: string[] = [];
   const escalationMs = stewardEscalationMs();
-  const fallbackTarget = stewardFallbackTarget();
   for (const ws of all) {
     if (!STRANDABLE_STATUSES.has(ws.status) || ws.mode !== "isolated" || !ws.worktreePath) continue;
     reelectRepoSteward(ws.repoRoot);
     const fresh = getWorkspace(ws.id);
     if (!fresh || !STRANDABLE_STATUSES.has(fresh.status)) continue;
     const meta = fresh.metadata as Record<string, unknown>;
-    const steward = fresh.stewardAgentId;
-    const stewardOnline = Boolean(steward && getAgent(steward) && getAgent(steward)!.status !== "offline");
     const strandedAt = typeof meta.strandedAt === "number" ? meta.strandedAt : undefined;
 
-    if (!stewardOnline) {
-      const orch = workspaceOwnerOrchestrator(fresh, listOrchestrators().filter((o) => o.status === "online" && o.apiUrl), { requireApiUrl: true });
-      const preview = orch?.apiUrl ? await fetchHostMergePreview(orch.apiUrl, fresh, { checkPr: true }) : null;
-      if (preview && !("available" in preview) && !preview.error && !preview.missing) {
-        const landed = previewProvesLanded(preview);
-        if (landed) {
-          reconcileLandedWorkspace(fresh, preview);
-          patchWorkspaceMetadata(fresh.id, { strandedAt: undefined, escalatedAt: undefined, strandedNotifiedSteward: undefined });
-          reconciledLandedIds.push(fresh.id);
-          continue;
-        }
+    const orch = workspaceOwnerOrchestrator(fresh, listOrchestrators().filter((o) => o.status === "online" && o.apiUrl), { requireApiUrl: true });
+    const preview = orch?.apiUrl ? await fetchHostMergePreview(orch.apiUrl, fresh, { checkPr: true }) : null;
+    if (preview && !("available" in preview) && !preview.error && !preview.missing) {
+      const landed = previewProvesLanded(preview);
+      if (landed) {
+        reconcileLandedWorkspace(fresh, preview);
+        patchWorkspaceMetadata(fresh.id, { strandedAt: undefined, escalatedAt: undefined, strandedNotifiedSteward: undefined });
+        reconciledLandedIds.push(fresh.id);
+        continue;
       }
     }
 
-    if (stewardOnline) {
-      if (strandedAt !== undefined && meta.strandedNotifiedSteward !== steward) {
-        const sent = notifyTarget(
-          "workspace.steward_reassigned",
-          { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
-          steward!,
-          "Workspace stewardship reassigned",
-          `You are now steward for ${fresh.repoRoot}. Workspace \`${fresh.branch ?? fresh.id}\` is ${fresh.status} and was stranded without an online steward - please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"}.`,
-          { kind: "workspace.steward-reassigned", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status },
-        );
-        if (sent) reassignedIds.push(fresh.id);
-      }
-      patchWorkspaceMetadata(fresh.id, { strandedAt: undefined, escalatedAt: undefined, strandedNotifiedSteward: steward });
-      continue;
-    }
-
     if (strandedAt === undefined) { patchWorkspaceMetadata(fresh.id, { strandedAt: now }); continue; }
-    if (now - strandedAt < escalationMs || meta.escalatedAt) continue;
-    // #642 — escalate to the branch agent's coordinator (owner's `spawnedBy`), falling back to
-    // the configured `stewardFallbackTarget` only when no coordinator resolves. The bare
-    // fallback was an unset `system` dead-end in the live incident.
-    const { coordinatorAgentId } = resolveStewardIdentity(fresh);
-    const escalationTarget = coordinatorAgentId ?? fallbackTarget;
-    const sent = notifyTarget(
-      "workspace.stranded_escalation",
-      { workspaceId: fresh.id, repoRoot: fresh.repoRoot, author: fresh.ownerAgentId, parent: coordinatorAgentId ?? undefined },
-      escalationTarget,
-      "Stranded workspace needs an owner",
-      `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} with no online steward (all repo agents offline) for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h.${coordinatorAgentId ? ` You are the branch agent \`${fresh.ownerAgentId ?? "?"}\`'s coordinator.` : ""} Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
-      { kind: "workspace.stranded-escalation", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status, strandedAt, coordinatorAgentId },
-    );
-    if (sent) escalationTargets.push(sent);
+    const escalatedAt = typeof meta.escalatedAt === "number" ? meta.escalatedAt : 0;
+    if (now - strandedAt < escalationMs) continue;
+    if (escalatedAt && now - escalatedAt < escalationMs) continue;
+
+    if (getStewardConfig().enabled) {
+      wakeRepoSteward(fresh, `workspace ${fresh.status} stranded for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h`);
+    }
+    const targets = routeWorkspaceCustodyEscalation({
+      workspace: fresh,
+      subject: "Stranded workspace needs an owner",
+      body: `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} and has been stranded for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h. Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
+      payload: { kind: "workspace.stranded-escalation", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status, strandedAt },
+      idempotencyKey: `workspace-stranded:${fresh.id}:${strandedAt}:${Math.floor(now / escalationMs)}`,
+    });
+    escalationTargets.push(...targets);
     patchWorkspaceMetadata(fresh.id, { escalatedAt: now });
     escalatedIds.push(fresh.id);
     createActivityEvent({
       clientId: `workspace-gc-escalate-${fresh.id}-${now}`,
       kind: "state",
       title: "Workspace escalated",
-      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - stranded ${fresh.status} escalated${escalationTarget ? ` to ${escalationTarget}${coordinatorAgentId ? " (coordinator)" : ""}` : " (no coordinator or fallback configured)"}`,
+      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - stranded ${fresh.status} escalated${targets.length ? ` to ${targets.join(", ")}` : " (no owner, coordinator, or fallback configured)"}`,
       meta: fresh.branch ?? fresh.id,
       icon: "ti-alert-octagon",
       view: "orchestrators",
-      metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id, escalationTarget: escalationTarget || null, coordinatorAgentId: coordinatorAgentId ?? null },
+      metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id, escalationTargets: targets },
     });
   }
 
@@ -250,6 +230,7 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
   const autoAbandonDeferred: string[] = [];
   const notifiedStewards: string[] = [];
   const reviewOrchestrators = listOrchestrators();
+  const fallbackTarget = stewardFallbackTarget();
   for (const ws of all) {
     if (ws.status === "review_requested" && ws.updatedAt < reviewCutoff) {
       const fresh = getWorkspace(ws.id);

package/src/managed-policy-escalation.ts

@@ -0,0 +1,47 @@
+import { getAgent, getDb } from "./db";
+import { getSpawnPolicy } from "./config-store";
+import { stewardFallbackTarget } from "./config";
+import { routeNotification } from "./notification-router";
+import type { ManagedAgentState, Orchestrator, SpawnPolicy } from "./types";
+
+const ORCHESTRATOR_OFFLINE_ESCALATION_FAILURES = 3;
+
+export function escalateOfflineOrchestrator(policy: SpawnPolicy, state: ManagedAgentState, orch: Orchestrator | null | undefined): void {
+  if (state.consecutiveFailures < ORCHESTRATOR_OFFLINE_ESCALATION_FAILURES) return;
+  const updatedBy = getSpawnPolicy(policy.name)?.updatedBy?.trim();
+  const previousParent = state.agentId ? getAgent(state.agentId)?.spawnedBy?.trim() : undefined;
+  const fallback = stewardFallbackTarget();
+  const recipients = [...new Set([updatedBy, previousParent, fallback].filter((item): item is string => Boolean(item && item !== "system")))];
+  if (!recipients.length) return;
+  const host = orch?.hostname ? `${orch.hostname} (${policy.orchestratorId})` : policy.orchestratorId;
+  const queuedMessages = queuedPolicyMessageCount(policy.name);
+  const nextRetry = state.backoffUntil ? new Date(state.backoffUntil).toISOString() : "not scheduled";
+  routeNotification({
+    type: "agent.spawn_failed",
+    scope: { target: `policy:${policy.name}` },
+    recipients,
+    message: {
+      subject: "Managed policy pinned host offline",
+      body: [
+        `Managed policy \`${policy.name}\` cannot spawn because pinned orchestrator \`${host}\` is offline.`,
+        `Queued messages: ${queuedMessages}. Consecutive failures: ${state.consecutiveFailures}. Next retry: ${nextRetry}.`,
+      ].join("\n"),
+      payload: {
+        kind: "managed-policy.orchestrator-offline",
+        policyName: policy.name,
+        orchestratorId: policy.orchestratorId,
+        orchestratorHostname: orch?.hostname,
+        queuedMessages,
+        consecutiveFailures: state.consecutiveFailures,
+        backoffUntil: state.backoffUntil,
+      },
+      idempotencyKey: `managed-policy-orchestrator-offline:${policy.name}:${policy.orchestratorId}`,
+      replyExpected: false,
+    },
+  });
+}
+
+function queuedPolicyMessageCount(policyName: string): number {
+  const row = getDb().query("SELECT COUNT(*) AS count FROM messages WHERE to_target = ? AND delivery_status = 'queued'").get(`policy:${policyName}`) as { count?: number } | undefined;
+  return row?.count ?? 0;
+}

package/src/mcp-task-tools.ts

@@ -88,6 +88,7 @@ export const TASK_TOOLS = [
         teamId: { type: "string" },
         projectId: { type: "string" },
         repo: { type: "string", description: "owner/repo for the task's project/repository" },
+        branch: { type: "string", description: "optional branch ref to seed on the task" },
         dispatch: DISPATCH_SCHEMA,
         issueRefs: { type: "array", items: { type: "string" }, description: "#n, owner/repo#n, GitHub URL, or issue_<id>" },
         defaultRepo: { type: "string", description: "owner/repo for bare #n issue refs" },
@@ -140,14 +141,12 @@ export function relayTaskTool(auth: McpAuthLike, name: string, args: Record<stri
       teamId: cleanString(args.teamId, "teamId", { max: 200 }),
       projectId: cleanString(args.projectId, "projectId", { max: 120 }),
       repo: cleanString(args.repo, "repo", { max: 500 }),
+      branch: cleanString(args.branch, "branch", { max: 500 }),
       dispatch: args.dispatch as TaskDispatch | undefined,
+      issueRefs: Array.isArray(args.issueRefs) ? args.issueRefs.filter((ref): ref is string => typeof ref === "string") : undefined,
+      defaultRepo: cleanString(args.defaultRepo, "defaultRepo", { max: 500 }),
       createdBy: actor,
     });
-    if (Array.isArray(args.issueRefs)) {
-      for (const ref of args.issueRefs) {
-        if (typeof ref === "string" && ref.trim()) addTaskEntityRef(created.id, { issue: ref, defaultRepo: cleanString(args.defaultRepo, "defaultRepo", { max: 500 }), actor });
-      }
-    }
     if (Array.isArray(args.dependsOn)) {
       for (const dep of args.dependsOn) addTaskEntityDependency(created.id, taskIdArg(dep), actor);
     }