Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
105 KB
Raw Blame
import { createHash, webcrypto } from "node:crypto";
import { readFile } from "node:fs/promises";
import type { createOpencodeClient, McpStatus, ToolIds, ToolList } from "@opencode-ai/sdk/v2/client";
import { ApiError } from "./errors.js";
import { diagnoseMcpToolDenies, type McpToolDeny } from "./mcp.js";
import { omnirushPluginPath } from "./omnirush-extensions-plugin-path.js";
import { sanitizeDiagnosticString, sanitizeDiagnosticValue } from "./diagnostic-sanitizer.js";
import {
  ENGINE_GLOBAL_RUNTIME_CONFIG_ID,
  listRuntimeOpencodeConfigRows,
  readGlobalRuntimeOpencodeConfig,
  readRuntimeOpencodeConfig,
  runtimeMcpMap,
  type RuntimeOpencodeConfig,
  writeGlobalRuntimeOpencodeConfig,
  writeRuntimeOpencodeConfig,
} from "./runtime-opencode-config-store.js";
import { externalFetch } from "./server-fetch.js";
import type { ServerConfig, WorkspaceInfo } from "./types.js";
import { validateMcpConfig } from "./validators.js";

export const OMNIRUSH_CLOUD_MCP_NAME = "omnirush-cloud";
export const OMNIRUSH_CLOUD_EXPECTED_TOOLS = [
  "omnirush-cloud_search_capabilities",
  "omnirush-cloud_execute_capability",
] satisfies string[];
const OMNIRUSH_CLOUD_DIRECT_TOOL_NAMES = [
  "search_capabilities",
  "execute_capability",
] satisfies string[];
export const OMNIRUSH_CLOUD_PLUGIN_CANARIES = [
  "app_docs_search",
  "app_query",
] satisfies string[];

const POLL_DELAYS_MS = [0, 250, 750, 1500, 3000];
function engineProbeTimeoutMs(): number {
  return Number(process.env.OMNIRUSH_CLOUD_MCP_PROBE_TIMEOUT_MS ?? "") || 5_000;
}

type WorkspaceOpencodeClient = ReturnType<typeof createOpencodeClient>;

export type CloudMcpProviderModelContext = {
  provider: string;
  model: string;
};

export type CloudMcpFailureStage =
  | "prerequisites"
  | "token_mint"
  | "desired_config"
  | "engine_delivery"
  | "transport_auth"
  | "tool_registration"
  | "provider_projection"
  | "plugin_load"
  | "steering";

export type CloudMcpFailureCode =
  | "cloud_mcp_missing"
  | "cloud_mcp_disabled"
  | "cloud_endpoint_invalid"
  | "cloud_token_org_mismatch"
  | "cloud_mcp_needs_auth"
  | "missing_mcp_token"
  | "invalid_mcp_token"
  | "mcp_session_revoked"
  | "mcp_membership_revoked"
  | "insufficient_mcp_scope"
  | "wrong_mcp_resource"
  | "opencode_engine_unreachable"
  | "opencode_mcp_sync_failed"
  | "provider_tool_projection_missing"
  | "cloud_steering_stale"
  | "cloud_desired_missing"
  | "workspace_directory_ambiguous"
  | "opencode_unconfigured"
  | "opencode_unreachable"
  | "cloud_status_missing"
  | "cloud_disabled"
  | "omnirush_cloud_auth_required"
  | "omnirush_cloud_auth_invalid"
  | "omnirush_cloud_token_expired"
  | "omnirush_cloud_membership_required"
  | "omnirush_cloud_scope_missing"
  | "omnirush_cloud_resource_forbidden"
  | "omnirush_cloud_resource_not_found"
  | "omnirush_cloud_client_registration_required"
  | "cloud_connection_failed"
  | "cloud_registration_failed"
  | "cloud_tools_denied"
  | "opencode_tool_ids_unsupported"
  | "opencode_tool_ids_unavailable"
  | "probe_unreachable"
  | "cloud_tools_missing"
  | "provider_projection_unavailable"
  | "provider_projection_missing"
  | "extensions_plugin_missing";

export type CloudMcpHealthPhase =
  | "missing_desired"
  | "workspace_ambiguous"
  | "engine_unconfigured"
  | "engine_unreachable"
  | "engine_missing"
  | "engine_disabled"
  | "engine_needs_auth"
  | "engine_needs_client_registration"
  | "engine_failed"
  | "registration_failed"
  | "denied_by_tools"
  | "tool_ids_unsupported"
  | "cloud_tools_missing"
  | "provider_projection_missing"
  | "extensions_plugin_missing"
  | "ready";

export type CloudMcpFailure = {
  code: CloudMcpFailureCode;
  stage: CloudMcpFailureStage;
  retryable: boolean;
  recommendedAction: string;
  message: string;
  aliases?: string[];
  requestId?: string;
  referenceId?: string;
  details?: unknown;
};

export type CloudMcpRuntimeRegistrationFailure = {
  name: string;
  status?: number;
  body?: unknown;
  message?: string;
};

export type CloudMcpRuntimeRegistrationResult = {
  status: "ok" | "failed" | "skipped";
  syncedNames: string[];
  failures: CloudMcpRuntimeRegistrationFailure[];
};

export type CloudMcpRuntimeRegistrar = (
  config: ServerConfig,
  workspace: WorkspaceInfo,
  onlyNames?: string[],
  options?: { throwOnFailure?: boolean },
) => Promise<CloudMcpRuntimeRegistrationResult>;

export type CloudMcpLiveStatusObserver = (
  config: ServerConfig,
  workspace: WorkspaceInfo,
  name: string,
  mcpConfig: Record<string, unknown>,
  status: string,
  errorSummary?: string | null,
) => void;

export type CloudMcpServerMetadata = {
  serverVersion?: string;
  expectedOpencodeVersion?: string;
};

export type CloudMcpCompatibilitySnapshot = {
  omnirush: {
    serverVersion: string | null;
    app: Record<string, string | number | boolean | null> | null;
  };
  opencode: {
    expectedVersion: string | null;
    actualVersion: string | null;
    probe: "ok" | "unavailable" | "not_checked";
    error?: unknown;
  };
  pluginFileHashes: Array<{
    name: string;
    sha256: string | null;
    error?: string;
  }>;
  supportedFeatures: {
    dynamicMcp: boolean;
    directoryScoping: boolean;
    toolIds: boolean;
    providerToolProjection: boolean;
    pluginCanaries: boolean;
  };
  experimentalToolIds: CloudMcpExperimentalToolIdsSnapshot;
  experimentalProviderTools: CloudMcpExperimentalProviderToolsSnapshot;
};

export type CloudMcpExperimentalToolIdsSnapshot = {
  checked: boolean;
  expected: string[];
  present: string[];
  missing: string[];
  includesMcpTools: boolean | null;
  limitation?: string;
  error?: unknown;
};

export type CloudMcpExperimentalProviderToolsSnapshot = {
  checked: boolean;
  provider?: string;
  model?: string;
  expected: string[];
  present: string[];
  missing: string[];
  includesMcpTools: boolean | null;
  limitation?: string;
  error?: unknown;
};

export type CloudMcpHealth = {
  schemaVersion: 1;
  phase: CloudMcpHealthPhase;
  usable: boolean;
  usableByCurrentModel: boolean | null;
  connectCatalogEnabled: boolean;
  workspace: {
    id: string;
    type: WorkspaceInfo["workspaceType"];
    directory: string | null;
    path: string;
  };
  desired: {
    present: boolean;
    name: typeof OMNIRUSH_CLOUD_MCP_NAME;
    revision: string | null;
    config: RedactedCloudMcpConfig | null;
    token: CloudMcpTokenHealth;
    org?: Record<string, string | number | boolean | null>;
    app?: Record<string, string | number | boolean | null>;
    updatedAt?: number;
  };
  delivery: CloudMcpDeliverySnapshot;
  engine: {
    status: "not_checked" | "missing" | "connected" | "disabled" | "failed" | "needs_auth" | "needs_client_registration" | "unreachable" | "unknown";
    error?: unknown;
  };
  engineInspection: CloudMcpEngineInspection;
  tools: {
    expected: string[];
    present: string[];
    missing: string[];
    direct: {
      checked: boolean;
      source: "mcp_tools_list";
      expected: string[];
      present: string[];
      missing: string[];
      trace?: CloudMcpProbeTrace;
      error?: unknown;
      failure?: CloudMcpFailure;
    };
    providerProjection: {
      checked: boolean;
      provider?: string;
      model?: string;
      source?: "experimental_tool" | "provider_capability";
      limitation?: string;
      modelExists?: boolean;
      toolCalling?: boolean | null;
      present: string[];
      missing: string[];
      error?: unknown;
    };
  };
  pluginCanaries: {
    expected: string[];
    present: string[];
    missing: string[];
  };
  compatibility: CloudMcpCompatibilitySnapshot;
  toolDenies: McpToolDeny[];
  firstFailure: CloudMcpFailure | null;
  checkedAt: string;
  durationMs: number;
};

type RedactedCloudMcpConfig = {
  type: "remote";
  url: string;
  enabled?: boolean;
  oauth?: false | true | "configured";
  timeout?: number;
  headers?: {
    keys: string[];
    authorizationPresent: boolean;
  };
};

type CloudMcpTokenHealth = {
  present: boolean;
  metadata: Record<string, string | number | boolean | null>;
};

type CloudMcpDesiredMetadata = {
  token: CloudMcpTokenHealth;
  org?: Record<string, string | number | boolean | null>;
  app?: Record<string, string | number | boolean | null>;
  connectCatalogEnabled: boolean;
  trigger?: string;
  updatedAt: number;
};

type CloudMcpDeliveryStateName = "not_desired" | "pending" | "registering" | "ready" | "failed" | "stale";

export type CloudMcpDeliverySnapshot = {
  state: CloudMcpDeliveryStateName;
  desiredRevision: string | null;
  appliedRevision: string | null;
  updatedAt: number | null;
  appliedAt: number | null;
  lastAttemptAt: number | null;
  trigger?: string;
  failure?: CloudMcpFailure;
};

type CloudMcpDeliveryEntry = {
  workspaceId: string;
  directory: string | null;
  desiredRevision: string;
  metadata: CloudMcpDesiredMetadata;
  state: CloudMcpDeliveryStateName;
  updatedAt: number;
  appliedRevision?: string;
  appliedAt?: number;
  lastAttemptAt?: number;
  trigger?: string;
  failure?: CloudMcpFailure;
};

type CloudMcpDesiredState = {
  present: boolean;
  revision: string | null;
  config: Record<string, unknown> | null;
  redactedConfig: RedactedCloudMcpConfig | null;
  metadata: CloudMcpDesiredMetadata;
  validationProblem?: CloudMcpValidationProblem;
};

type CloudMcpValidationProblem = {
  code: CloudMcpFailureCode;
  stage: "desired_config";
  retryable: boolean;
  recommendedAction: string;
  message: string;
  aliases?: string[];
  details?: unknown;
};

type ToolSnapshot = {
  expected: string[];
  present: string[];
  missing: string[];
};

export type CloudMcpEngineServerStatus = {
  name: string;
  status: string;
  error?: string;
};

/**
 * The engine's own view of every MCP server it tracks, read over the OpenCode
 * SDK. Support triage needs the siblings: "everything failed" points at the
 * engine host's network path, "only omnirush-cloud failed" points at the Cloud
 * endpoint or token, and an absent entry means the dynamic registration was
 * lost (e.g. after an engine state rebuild) and must be re-applied.
 */
export type CloudMcpEngineInspection = {
  checked: boolean;
  cloudPresent?: boolean;
  serverCount?: number;
  servers?: CloudMcpEngineServerStatus[];
};

export type CloudMcpProbeStepName = "initialize" | "initialized_notice" | "tools_list";

export type CloudMcpProbeStep = {
  step: CloudMcpProbeStepName;
  ok: boolean;
  httpStatus?: number;
  latencyMs: number;
  error?: unknown;
};

export type CloudMcpProbeTrace = {
  endpoint: string | null;
  startedAt: string;
  latencyMs: number;
  protocolVersion: string | null;
  serverInfo: { name: string | null; version: string | null } | null;
  steps: CloudMcpProbeStep[];
};

type DirectCloudToolsSnapshot = {
  checked: boolean;
  source: "mcp_tools_list";
  expected: string[];
  present: string[];
  missing: string[];
  trace?: CloudMcpProbeTrace;
  error?: unknown;
  failure?: CloudMcpFailure;
};

const directCloudToolsProbeFlights = new Map<string, Promise<DirectCloudToolsSnapshot>>();

export function clearOmniRushCloudMcpProbeFlights(): void {
  directCloudToolsProbeFlights.clear();
}

type ProviderProjectionSnapshot = {
  checked: boolean;
  provider?: string;
  model?: string;
  source?: "experimental_tool" | "provider_capability";
  limitation?: string;
  modelExists?: boolean;
  toolCalling?: boolean | null;
  present: string[];
  missing: string[];
  error?: unknown;
  failure?: CloudMcpFailure;
};

type Inspection = {
  engine: CloudMcpHealth["engine"];
  engineInspection: CloudMcpEngineInspection;
  tools: ToolSnapshot;
  directTools: DirectCloudToolsSnapshot;
  providerProjection: ProviderProjectionSnapshot;
  pluginCanaries: ToolSnapshot;
  experimentalToolIds: CloudMcpExperimentalToolIdsSnapshot;
  experimentalProviderTools: CloudMcpExperimentalProviderToolsSnapshot;
  opencodeVersion: CloudMcpCompatibilitySnapshot["opencode"];
  failures: CloudMcpFailure[];
};

export class CloudMcpDeliveryStateStore {
  private entries = new Map<string, CloudMcpDeliveryEntry>();

  snapshot(workspace: WorkspaceInfo, directory: string | null, desiredRevision: string | null): CloudMcpDeliverySnapshot {
    if (!desiredRevision) {
      return {
        state: "not_desired",
        desiredRevision: null,
        appliedRevision: null,
        updatedAt: null,
        appliedAt: null,
        lastAttemptAt: null,
      };
    }
    const entry = this.entries.get(this.key(workspace.id, directory));
    if (!entry || entry.desiredRevision !== desiredRevision) {
      return {
        state: "pending",
        desiredRevision,
        appliedRevision: null,
        updatedAt: entry?.updatedAt ?? null,
        appliedAt: null,
        lastAttemptAt: entry?.lastAttemptAt ?? null,
        ...(entry?.trigger ? { trigger: entry.trigger } : {}),
      };
    }
    return this.entrySnapshot(entry);
  }

  metadata(workspace: WorkspaceInfo, directory: string | null, desiredRevision: string | null): CloudMcpDesiredMetadata | null {
    if (!desiredRevision) return null;
    const entry = this.entries.get(this.key(workspace.id, directory));
    if (!entry || entry.desiredRevision !== desiredRevision) return null;
    return entry.metadata;
  }

  latestMetadata(workspace: WorkspaceInfo, directory: string | null): CloudMcpDesiredMetadata | null {
    return this.entries.get(this.key(workspace.id, directory))?.metadata ?? null;
  }

  markDesired(
    workspace: WorkspaceInfo,
    directory: string | null,
    desiredRevision: string,
    metadata: CloudMcpDesiredMetadata,
  ): CloudMcpDeliverySnapshot {
    const now = Date.now();
    const key = this.key(workspace.id, directory);
    const existing = this.entries.get(key);
    const entry: CloudMcpDeliveryEntry = {
      workspaceId: workspace.id,
      directory,
      desiredRevision,
      metadata,
      state: existing?.appliedRevision === desiredRevision ? "ready" : "pending",
      updatedAt: now,
      appliedRevision: existing?.appliedRevision === desiredRevision ? existing.appliedRevision : undefined,
      appliedAt: existing?.appliedRevision === desiredRevision ? existing.appliedAt : undefined,
      lastAttemptAt: existing?.lastAttemptAt,
      trigger: metadata.trigger,
    };
    this.entries.set(key, entry);
    return this.entrySnapshot(entry);
  }

  markRegistering(workspace: WorkspaceInfo, directory: string | null, desiredRevision: string): void {
    this.update(workspace.id, directory, desiredRevision, (entry) => ({
      ...entry,
      state: "registering",
      lastAttemptAt: Date.now(),
      failure: undefined,
    }));
  }

  markReady(workspace: WorkspaceInfo, directory: string | null, desiredRevision: string): void {
    const now = Date.now();
    this.update(workspace.id, directory, desiredRevision, (entry) => ({
      ...entry,
      state: "ready",
      appliedRevision: desiredRevision,
      appliedAt: now,
      updatedAt: now,
      failure: undefined,
    }));
  }

  markFailed(workspace: WorkspaceInfo, directory: string | null, desiredRevision: string, failure: CloudMcpFailure): void {
    const now = Date.now();
    this.update(workspace.id, directory, desiredRevision, (entry) => ({
      ...entry,
      state: "failed",
      updatedAt: now,
      lastAttemptAt: now,
      failure,
      appliedRevision: entry.appliedRevision === desiredRevision ? entry.appliedRevision : undefined,
      appliedAt: entry.appliedRevision === desiredRevision ? entry.appliedAt : undefined,
    }));
  }

  markWorkspaceStale(workspace: WorkspaceInfo, directory: string | null): void {
    const entry = this.entries.get(this.key(workspace.id, directory));
    if (!entry) return;
    this.entries.set(this.key(workspace.id, directory), {
      ...entry,
      state: "stale",
      appliedRevision: undefined,
      appliedAt: undefined,
      updatedAt: Date.now(),
    });
  }

  clear(): void {
    this.entries.clear();
  }

  private key(workspaceId: string, directory: string | null): string {
    return `${workspaceId}\0${directory ?? ""}`;
  }

  private update(
    workspaceId: string,
    directory: string | null,
    desiredRevision: string,
    updater: (entry: CloudMcpDeliveryEntry) => CloudMcpDeliveryEntry,
  ): void {
    const key = this.key(workspaceId, directory);
    const entry = this.entries.get(key);
    if (!entry || entry.desiredRevision !== desiredRevision) return;
    this.entries.set(key, updater(entry));
  }

  private entrySnapshot(entry: CloudMcpDeliveryEntry): CloudMcpDeliverySnapshot {
    return {
      state: entry.state,
      desiredRevision: entry.desiredRevision,
      appliedRevision: entry.appliedRevision ?? null,
      updatedAt: entry.updatedAt,
      appliedAt: entry.appliedAt ?? null,
      lastAttemptAt: entry.lastAttemptAt ?? null,
      ...(entry.trigger ? { trigger: entry.trigger } : {}),
      ...(entry.failure ? { failure: entry.failure } : {}),
    };
  }
}

export const cloudMcpDeliveryState = new CloudMcpDeliveryStateStore();

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function hashString(value: string): string {
  return createHash("sha256").update(value).digest("hex");
}

function safeMetadataRecord(value: unknown): Record<string, string | number | boolean | null> | undefined {
  if (!isRecord(value)) return undefined;
  const output: Record<string, string | number | boolean | null> = {};
  for (const [key, nested] of Object.entries(value)) {
    if (typeof nested === "string") output[key] = sanitizeDiagnosticString(nested);
    else if (typeof nested === "number" || typeof nested === "boolean" || nested === null) output[key] = nested;
  }
  return Object.keys(output).length ? output : undefined;
}

function readString(value: unknown): string | undefined {
  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
}

function readBoolean(value: unknown): boolean | undefined {
  return typeof value === "boolean" ? value : undefined;
}

function readNumber(value: unknown): number | undefined {
  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
}

function normalizeStringRecord(value: unknown): Record<string, string> | undefined {
  if (!isRecord(value)) return undefined;
  const output: Record<string, string> = {};
  for (const [key, nested] of Object.entries(value)) {
    if (typeof nested === "string") output[key] = nested;
  }
  return Object.keys(output).length ? output : undefined;
}

function authorizationHeader(config: Record<string, unknown>): string | null {
  const headers = isRecord(config.headers) ? config.headers : null;
  if (!headers) return null;
  for (const [key, value] of Object.entries(headers)) {
    if (key.toLowerCase() === "authorization" && typeof value === "string") return value;
  }
  return null;
}

export function cloudMcpTokenHealthFromConfig(config: Record<string, unknown> | null, metadata?: Record<string, string | number | boolean | null>): CloudMcpTokenHealth {
  const authorization = config ? authorizationHeader(config) : null;
  const tokenMetadata: Record<string, string | number | boolean | null> = { ...(metadata ?? {}) };
  return {
    present: Boolean(authorization) || Object.keys(tokenMetadata).length > 0,
    metadata: tokenMetadata,
  };
}

function extractDesiredMetadata(body: Record<string, unknown>, config: Record<string, unknown>): CloudMcpDesiredMetadata {
  const tokenMetadata = safeMetadataRecord(body.tokenMetadata) ?? safeMetadataRecord(body.token);
  const org = safeMetadataRecord(body.org) ?? safeMetadataRecord(body.organization);
  const app = safeMetadataRecord(body.app) ?? safeMetadataRecord({
    version: body.appVersion,
    buildSha: body.buildSha ?? body.buildSHA,
  });
  const trigger = readString(body.trigger);
  const connectCatalogEnabled = readBoolean(body.connectCatalogEnabled) ?? true;
  return {
    token: cloudMcpTokenHealthFromConfig(config, tokenMetadata),
    ...(org ? { org } : {}),
    ...(app ? { app } : {}),
    connectCatalogEnabled,
    ...(trigger ? { trigger } : {}),
    updatedAt: Date.now(),
  };
}

function defaultDesiredMetadata(config: Record<string, unknown> | null, connectCatalogEnabled: boolean): CloudMcpDesiredMetadata {
  return {
    token: cloudMcpTokenHealthFromConfig(config),
    connectCatalogEnabled,
    updatedAt: Date.now(),
  };
}

function normalizeCloudEndpointUrl(value: string): string | null {
  try {
    const url = new URL(value);
    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
    if (url.search || url.hash) return null;
    const normalizedPath = url.pathname.replace(/\/+$/, "") || "/";
    if (!normalizedPath.endsWith("/mcp/agent")) return null;
    url.pathname = normalizedPath;
    return url.toString();
  } catch {
    return null;
  }
}

function canonicalizeCloudMcpConfig(config: Record<string, unknown>): Record<string, unknown> {
  const url = readString(config.url);
  const normalizedUrl = url ? normalizeCloudEndpointUrl(url) : null;
  return normalizedUrl ? { ...config, url: normalizedUrl } : config;
}

function isLoopbackHostname(hostname: string): boolean {
  const normalized = hostname.toLowerCase();
  return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "[::1]" || normalized === "::1";
}

/**
 * Whether a proposed omnirush-cloud endpoint may be persisted as the
 * account-global desired config by a collaborator-scoped client.
 *
 * The desired config is global: one write reconfigures Connect for every
 * workspace this server hosts. Only the administrator-activated enterprise Den
 * origin and loopback (local development Dens) are trusted. There are no
 * built-in hosted origins (omnirush.ai runs no hosted Den and the retired
 * hosted Den domains are not ours); anything else requires owner scope so a
 * collaborator on one shared workspace cannot silently redirect every other
 * workspace's Connect tools to an attacker-controlled endpoint.
 */
export async function isTrustedCloudMcpEndpointForGlobalPersist(rawUrl: string): Promise<boolean> {
  const normalized = normalizeCloudEndpointUrl(rawUrl);
  // An unnormalizable URL cannot be persisted at all: strict desired-config
  // validation fails closed downstream, so scope enforcement is moot here and
  // the caller keeps the richer stage-tagged validation error.
  if (!normalized) return true;
  let url: URL;
  try {
    url = new URL(normalized);
  } catch {
    return true;
  }
  if (isLoopbackHostname(url.hostname)) return true;
  if (url.protocol !== "https:") return false;
  const { readActivatedEnterpriseDenOrigin } = await import("./enterprise-den-origin.js");
  const enterpriseOrigin = await readActivatedEnterpriseDenOrigin();
  return enterpriseOrigin !== null && url.origin === enterpriseOrigin;
}

function normalizeCloudMcpConfig(input: unknown): Record<string, unknown> {
  if (!isRecord(input)) {
    throw new ApiError(400, "invalid_payload", "config is required");
  }
  const type = input.type ?? "remote";
  const url = readString(input.url);
  const output: Record<string, unknown> = { type };
  if (url) output.url = normalizeCloudEndpointUrl(url) ?? url;
  const enabled = readBoolean(input.enabled);
  if (enabled !== undefined) output.enabled = enabled;
  const headers = normalizeStringRecord(input.headers);
  if (headers) output.headers = headers;
  if (input.oauth === false) output.oauth = false;
  else if (input.oauth === true) output.oauth = {};
  else if (isRecord(input.oauth)) output.oauth = input.oauth;
  const timeout = readNumber(input.timeout);
  if (timeout !== undefined) output.timeout = timeout;
  return output;
}

function strictCloudMcpDesiredConfigProblem(config: Record<string, unknown>, metadata: CloudMcpDesiredMetadata): CloudMcpValidationProblem | null {
  if (config.type !== "remote") {
    return {
      code: "cloud_endpoint_invalid",
      stage: "desired_config",
      retryable: false,
      recommendedAction: "Reconnect OmniRush.ai Cloud",
      message: "omnirush-cloud must be configured as a remote MCP endpoint.",
      details: { type: typeof config.type === "string" ? config.type : null },
    };
  }

  if (config.enabled !== true) {
    return {
      code: "cloud_mcp_disabled",
      stage: "desired_config",
      retryable: false,
      recommendedAction: "Enable Agent access in Settings → Connect",
      message: "omnirush-cloud desired config is disabled.",
      aliases: ["cloud_disabled"],
      details: { enabled: config.enabled ?? null },
    };
  }

  const url = readString(config.url);
  const normalizedUrl = url ? normalizeCloudEndpointUrl(url) : null;
  if (!url || !normalizedUrl) {
    return {
      code: "cloud_endpoint_invalid",
      stage: "desired_config",
      retryable: false,
      recommendedAction: "Reconnect OmniRush.ai Cloud",
      message: "omnirush-cloud URL must be a valid http(s) endpoint at /mcp/agent.",
      details: { url: typeof config.url === "string" ? sanitizeDiagnosticString(config.url) : null },
    };
  }

  const authorization = authorizationHeader(config)?.trim();
  if (!authorization) {
    return {
      code: "invalid_mcp_token",
      stage: "desired_config",
      retryable: false,
      recommendedAction: "Reconnect OmniRush.ai Cloud",
      message: "omnirush-cloud desired config is missing an Authorization header.",
      aliases: ["omnirush_cloud_auth_required"],
    };
  }

  if (config.oauth !== false) {
    return {
      code: "invalid_mcp_token",
      stage: "desired_config",
      retryable: false,
      recommendedAction: "Reconnect OmniRush.ai Cloud",
      message: "omnirush-cloud desired config must use the minted bearer token, not OAuth.",
      aliases: ["omnirush_cloud_auth_invalid"],
      details: { oauth: config.oauth === undefined ? "missing" : "configured" },
    };
  }

  const tokenOrganizationId = typeof metadata.token.metadata.organizationId === "string" ? metadata.token.metadata.organizationId.trim() : "";
  const activeOrganizationId = typeof metadata.org?.id === "string" ? metadata.org.id.trim() : "";
  if (tokenOrganizationId && activeOrganizationId && tokenOrganizationId !== activeOrganizationId) {
    return {
      code: "cloud_token_org_mismatch",
      stage: "desired_config",
      retryable: false,
      recommendedAction: "Choose the matching organization, then Repair and test",
      message: "omnirush-cloud token organization does not match the active organization.",
      details: { tokenOrganizationId, activeOrganizationId },
    };
  }

  try {
    validateMcpConfig(canonicalizeCloudMcpConfig(config));
  } catch (error) {
    return {
      code: "cloud_endpoint_invalid",
      stage: "desired_config",
      retryable: false,
      recommendedAction: "Reconnect OmniRush.ai Cloud",
      message: "omnirush-cloud desired config is not a valid remote MCP config.",
      details: { error: error instanceof Error ? error.message : String(error) },
    };
  }

  return null;
}

function redactedConfig(config: Record<string, unknown>): RedactedCloudMcpConfig {
  const headers = isRecord(config.headers) ? config.headers : null;
  const headerKeys = headers ? Object.keys(headers).sort() : [];
  const oauth = config.oauth === false
    ? false
    : config.oauth === true
      ? true
      : isRecord(config.oauth)
        ? "configured"
        : undefined;
  return {
    type: "remote",
    url: typeof config.url === "string" ? sanitizeDiagnosticString(config.url) : "",
    ...(typeof config.enabled === "boolean" ? { enabled: config.enabled } : {}),
    ...(oauth !== undefined ? { oauth } : {}),
    ...(typeof config.timeout === "number" ? { timeout: config.timeout } : {}),
    ...(headers
      ? {
          headers: {
            keys: headerKeys.map((key) => sanitizeDiagnosticString(key)),
            authorizationPresent: headerKeys.some((key) => key.toLowerCase() === "authorization"),
          },
        }
      : {}),
  };
}

function revisionValue(value: unknown): unknown {
  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) return value;
  if (Array.isArray(value)) return value.map((item) => revisionValue(item));
  if (!isRecord(value)) return null;
  const output: Record<string, unknown> = {};
  for (const nestedKey of Object.keys(value).sort()) {
    const nested = value[nestedKey];
    if (nested !== undefined) output[nestedKey] = revisionValue(nested);
  }
  return output;
}

// Delivery state is process-local, so this process-local key keeps revisions
// useful for equality without exposing a reusable fingerprint of bearer auth.
const cloudMcpRevisionKey = webcrypto.subtle.generateKey(
  { name: "HMAC", hash: "SHA-256" },
  false,
  ["sign"],
);

export async function calculateCloudMcpDesiredRevision(config: Record<string, unknown>, metadata: CloudMcpDesiredMetadata): Promise<string> {
  const revisionKey = await cloudMcpRevisionKey;
  const revision = JSON.stringify(revisionValue({
    config,
    metadata: {
      token: metadata.token,
      org: metadata.org,
      connectCatalogEnabled: metadata.connectCatalogEnabled,
    },
  }));
  const tag = await webcrypto.subtle.sign("HMAC", revisionKey, new TextEncoder().encode(revision));
  return Buffer.from(tag).toString("hex");
}

async function readDesiredState(input: {
  config: ServerConfig;
  workspace: WorkspaceInfo;
  directory: string | null;
  connectCatalogEnabled?: boolean;
}): Promise<CloudMcpDesiredState> {
  const entry = await readPersistedDesiredConfig(input.config, input.workspace.id);
  if (!entry) {
    const metadata = defaultDesiredMetadata(null, input.connectCatalogEnabled ?? false);
    return { present: false, revision: null, config: null, redactedConfig: null, metadata };
  }
  const config = canonicalizeCloudMcpConfig(entry);
  const storedMetadata = cloudMcpDeliveryState.latestMetadata(input.workspace, input.directory);
  const metadata = storedMetadata ?? defaultDesiredMetadata(config, input.connectCatalogEnabled ?? true);
  const validationProblem = strictCloudMcpDesiredConfigProblem(config, metadata) ?? undefined;
  const revision = await calculateCloudMcpDesiredRevision(config, metadata);
  const revisionMetadata = cloudMcpDeliveryState.metadata(input.workspace, input.directory, revision) ?? metadata;
  return {
    present: true,
    revision,
    config,
    redactedConfig: redactedConfig(config),
    metadata: revisionMetadata,
    ...(validationProblem ? { validationProblem } : {}),
  };
}

async function readPersistedDesiredConfig(
  config: ServerConfig,
  workspaceId: string,
): Promise<Record<string, unknown> | undefined> {
  const globalEntry = runtimeMcpMap(await readGlobalRuntimeOpencodeConfig(config))[OMNIRUSH_CLOUD_MCP_NAME];
  if (globalEntry) return globalEntry;
  return runtimeMcpMap(await readRuntimeOpencodeConfig(config, workspaceId))[OMNIRUSH_CLOUD_MCP_NAME];
}

export async function migrateOmniRushCloudMcpRuntimeConfig(
  config: ServerConfig,
): Promise<{ config: Record<string, unknown> | null; changed: boolean }> {
  const rows = await listRuntimeOpencodeConfigRows(config);
  const globalRow = rows.find((row) => row.workspaceId === ENGINE_GLOBAL_RUNTIME_CONFIG_ID);
  const globalEntry = globalRow
    ? runtimeMcpMap(globalRow.value)[OMNIRUSH_CLOUD_MCP_NAME]
    : undefined;
  const legacyCandidates: Array<{ config: Record<string, unknown>; updatedAt: number; workspaceId: string }> = [];
  for (const row of rows) {
    if (row.workspaceId === ENGINE_GLOBAL_RUNTIME_CONFIG_ID) continue;
    const entry = runtimeMcpMap(row.value)[OMNIRUSH_CLOUD_MCP_NAME];
    if (!entry || !isRecord(entry)) continue;
    const normalized = canonicalizeCloudMcpConfig(entry);
    const metadata = defaultDesiredMetadata(normalized, true);
    if (strictCloudMcpDesiredConfigProblem(normalized, metadata)) continue;
    // Promotion escalates a workspace-scoped entry to account-global scope, so
    // it must clear the same trust bar as a collaborator reconcile: a stale or
    // planted workspace row pointing at an untrusted endpoint stays workspace-
    // scoped (pre-migration blast radius) instead of becoming global.
    const url = typeof normalized.url === "string" ? normalized.url : "";
    if (!await isTrustedCloudMcpEndpointForGlobalPersist(url)) continue;
    legacyCandidates.push({ config: normalized, updatedAt: row.updatedAt, workspaceId: row.workspaceId });
  }
  const newestValidLegacy = legacyCandidates
    .sort((left, right) => right.updatedAt - left.updatedAt || left.workspaceId.localeCompare(right.workspaceId))[0];
  const selected = globalEntry ?? newestValidLegacy?.config;
  if (!selected || config.readOnly) return { config: selected ?? null, changed: false };

  let changed = false;
  if (!globalEntry) {
    const result = await writeGlobalRuntimeOpencodeConfig(config, (current) => ({
      ...current,
      mcp: { ...runtimeMcpMap(current), [OMNIRUSH_CLOUD_MCP_NAME]: selected },
    }));
    changed = result.changed;
  }
  for (const row of rows) {
    if (
      row.workspaceId === ENGINE_GLOBAL_RUNTIME_CONFIG_ID
      || !Object.hasOwn(runtimeMcpMap(row.value), OMNIRUSH_CLOUD_MCP_NAME)
    ) continue;
    const result = await writeRuntimeOpencodeConfig(config, row.workspaceId, (current) => ({
      ...current,
      mcp: Object.fromEntries(Object.entries(runtimeMcpMap(current))
        .filter(([name]) => name !== OMNIRUSH_CLOUD_MCP_NAME)),
    }));
    changed = result.changed || changed;
  }
  return { config: selected, changed };
}

/**
 * Removes the `omnirush-cloud` entry everywhere, together with every directly
 * exposed connection entry: those carry the same member credential and have no
 * meaning once the member is signed out. Returns the runtime names removed so
 * the caller can disconnect them from the engine.
 */
export async function removeOmniRushCloudMcpDesiredConfig(
  config: ServerConfig,
): Promise<{ changed: boolean; removedNames: string[] }> {
  const { CONNECT_DIRECT_MCP_SERVER_NAME_PREFIX } = await import("./connect-mcp-server-catalog.js");
  const ownedByCloud = (name: string) =>
    name === OMNIRUSH_CLOUD_MCP_NAME || name.startsWith(CONNECT_DIRECT_MCP_SERVER_NAME_PREFIX);
  let changed = false;
  const removedNames = new Set<string>();
  for (const row of await listRuntimeOpencodeConfigRows(config)) {
    const owned = Object.keys(runtimeMcpMap(row.value)).filter(ownedByCloud);
    if (owned.length === 0) continue;
    const strip = (current: RuntimeOpencodeConfig) => ({
      ...current,
      mcp: Object.fromEntries(Object.entries(runtimeMcpMap(current)).filter(([name]) => !ownedByCloud(name))),
    });
    const result = row.workspaceId === ENGINE_GLOBAL_RUNTIME_CONFIG_ID
      ? await writeGlobalRuntimeOpencodeConfig(config, strip)
      : await writeRuntimeOpencodeConfig(config, row.workspaceId, strip);
    changed = result.changed || changed;
    for (const name of owned) removedNames.add(name);
  }
  const { writeConnectCloudMcp } = await import("./connect-state.js");
  await writeConnectCloudMcp(config, null);
  return { changed, removedNames: [...removedNames].sort() };
}

function locationParams(directory: string | null): { directory?: string } {
  return directory ? { directory } : {};
}

function expectedTools(): string[] {
  return [...OMNIRUSH_CLOUD_EXPECTED_TOOLS];
}

function expectedDirectToolNames(): string[] {
  return [...OMNIRUSH_CLOUD_DIRECT_TOOL_NAMES];
}

function prefixedCloudToolId(name: string): string {
  return `${OMNIRUSH_CLOUD_MCP_NAME}_${name}`;
}

function expectedCanaries(): string[] {
  return [...OMNIRUSH_CLOUD_PLUGIN_CANARIES];
}

function splitPresentMissing(ids: string[], expected: string[]): ToolSnapshot {
  return {
    expected,
    present: expected.filter((id) => ids.includes(id)),
    missing: expected.filter((id) => !ids.includes(id)),
  };
}

function failure(input: {
  code: CloudMcpFailureCode;
  stage: CloudMcpFailureStage;
  retryable: boolean;
  recommendedAction: string;
  message: string;
  aliases?: string[];
  details?: unknown;
}): CloudMcpFailure {
  const ids = extractDiagnosticIds(input.details);
  return {
    code: input.code,
    stage: input.stage,
    retryable: input.retryable,
    recommendedAction: input.recommendedAction,
    message: input.message,
    ...(input.aliases?.length ? { aliases: input.aliases.map(sanitizeDiagnosticString) } : {}),
    ...(ids.requestId ? { requestId: ids.requestId } : {}),
    ...(ids.referenceId ? { referenceId: ids.referenceId } : {}),
    ...(input.details !== undefined ? { details: sanitizeDiagnosticValue(input.details) } : {}),
  };
}

function failureFromValidationProblem(problem: CloudMcpValidationProblem): CloudMcpFailure {
  return failure(problem);
}

function extractDiagnosticIds(value: unknown): { requestId?: string; referenceId?: string } {
  const found: { requestId?: string; referenceId?: string } = {};
  const visit = (nested: unknown): void => {
    if (typeof nested === "string") {
      const requestMatch = nested.match(/(?:x-request-id|request[_ -]?id)[=: ]+([A-Za-z0-9._:-]+)/i);
      const referenceMatch = nested.match(/(?:reference[_ -]?id)[=: ]+([A-Za-z0-9._:-]+)/i);
      if (requestMatch?.[1] && !found.requestId) found.requestId = sanitizeDiagnosticString(requestMatch[1]);
      if (referenceMatch?.[1] && !found.referenceId) found.referenceId = sanitizeDiagnosticString(referenceMatch[1]);
      return;
    }
    if (Array.isArray(nested)) {
      for (const item of nested) visit(item);
      return;
    }
    if (!isRecord(nested)) return;
    for (const [key, item] of Object.entries(nested)) {
      const normalized = key.toLowerCase().replace(/[-_]/g, "");
      if ((normalized === "requestid" || normalized === "xrequestid") && typeof item === "string" && !found.requestId) {
        found.requestId = sanitizeDiagnosticString(item);
      }
      if (normalized === "referenceid" && typeof item === "string" && !found.referenceId) {
        found.referenceId = sanitizeDiagnosticString(item);
      }
      visit(item);
    }
  };
  visit(value);
  return found;
}

function opencodeRequestFailure(stage: CloudMcpFailureStage, path: string, response: Response, error: unknown): CloudMcpFailure {
  if (stage === "engine_delivery") {
    return failure({
      code: response.status >= 500 ? "opencode_engine_unreachable" : "opencode_mcp_sync_failed",
      stage,
      retryable: response.status >= 500,
      recommendedAction: response.status >= 500 ? "Restart OmniRush or retry when the engine is reachable" : "Check OmniRush MCP status support",
      message: "OmniRush request failed while checking MCP status.",
      aliases: response.status >= 500 ? ["opencode_unreachable"] : ["cloud_connection_failed"],
      details: { path, status: response.status, error },
    });
  }
  if (stage === "tool_registration" && (response.status === 404 || response.status === 405)) {
    return failure({
      code: "opencode_tool_ids_unsupported",
      stage,
      retryable: false,
      recommendedAction: "Update OmniRush.ai",
      message: "OmniRush does not support listing tool IDs.",
      details: { path, status: response.status, error },
    });
  }
  return failure({
    code: stage === "provider_projection" ? "provider_tool_projection_missing" : "opencode_tool_ids_unavailable",
    stage,
    retryable: response.status >= 500,
    recommendedAction: response.status >= 500 ? "Retry after OmniRush is healthy" : "Update OmniRush.ai",
    message: "OmniRush request failed while checking omnirush-cloud MCP readiness.",
    aliases: stage === "provider_projection" ? ["provider_projection_unavailable"] : undefined,
    details: { path, status: response.status, error },
  });
}

function thrownOpencodeFailure(stage: CloudMcpFailureStage, path: string, error: unknown): CloudMcpFailure {
  return failure({
    code: "opencode_engine_unreachable",
    stage,
    retryable: true,
    recommendedAction: "Restart OmniRush or retry when the engine is reachable",
    message: "OmniRush engine is not reachable.",
    aliases: ["opencode_unreachable"],
    details: { path, error: error instanceof Error ? error.message : String(error) },
  });
}

async function withEngineProbeTimeout<T>(task: () => Promise<T>): Promise<T> {
  return await new Promise<T>((resolve, reject) => {
    const timeoutMs = engineProbeTimeoutMs();
    const handle = setTimeout(() => {
      reject(new Error(`OmniRush health probe timed out after ${timeoutMs}ms`));
    }, timeoutMs);
    task()
      .then(resolve, reject)
      .finally(() => clearTimeout(handle));
  });
}

async function withCloudEndpointProbeTimeout(task: (signal: AbortSignal) => Promise<Response>): Promise<Response> {
  const controller = new AbortController();
  const timeoutMs = engineProbeTimeoutMs();
  const handle = setTimeout(() => controller.abort(), timeoutMs);
  try {
    return await task(controller.signal);
  } finally {
    clearTimeout(handle);
  }
}

function parseJsonOrText(raw: string): unknown {
  try {
    return JSON.parse(raw);
  } catch {
    return sanitizeDiagnosticString(raw);
  }
}

function parseSsePayload(raw: string): unknown {
  const frames: string[] = [];
  let dataLines: string[] = [];
  for (const line of raw.split(/\r?\n/)) {
    if (line.trim() === "") {
      if (dataLines.length) frames.push(dataLines.join("\n"));
      dataLines = [];
      continue;
    }
    if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
  }
  if (dataLines.length) frames.push(dataLines.join("\n"));
  for (const frame of frames) {
    const parsed = parseJsonOrText(frame);
    if (isRecord(parsed) && (parsed.result !== undefined || parsed.error !== undefined || parsed.id !== undefined)) return parsed;
  }
  return frames[0] ? parseJsonOrText(frames[0]) : null;
}

async function readMcpJsonRpcPayload(response: Response): Promise<unknown> {
  const raw = await response.text();
  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
  if (contentType.includes("text/event-stream") || raw.split(/\r?\n/).some((line) => line.startsWith("data:"))) {
    return parseSsePayload(raw);
  }
  return raw.trim() ? parseJsonOrText(raw) : null;
}

function jsonRpcRecord(payload: unknown): Record<string, unknown> | null {
  if (isRecord(payload)) return payload;
  if (!Array.isArray(payload)) return null;
  for (const item of payload) {
    if (isRecord(item) && (item.result !== undefined || item.error !== undefined)) return item;
  }
  return null;
}

function toolNamesFromMcpPayload(payload: unknown): { names?: string[]; error?: unknown } {
  const record = jsonRpcRecord(payload);
  if (!record) return { error: { message: "MCP tools/list response was not a JSON-RPC object", payload } };
  if (record.error !== undefined) return { error: record.error };
  const result = isRecord(record.result) ? record.result : null;
  if (!result || !Array.isArray(result.tools)) return { error: { message: "MCP tools/list result did not include a tools array", payload: record } };
  const names: string[] = [];
  for (const tool of result.tools) {
    if (isRecord(tool) && typeof tool.name === "string") names.push(tool.name);
  }
  return { names };
}

function directCloudToolsFailure(input: {
  message: string;
  retryable: boolean;
  details?: unknown;
}): CloudMcpFailure {
  return failure({
    code: "cloud_tools_missing",
    stage: "tool_registration",
    retryable: input.retryable,
    recommendedAction: "Reconnect OmniRush.ai Cloud or contact OmniRush.ai support",
    message: input.message,
    details: input.details,
  });
}

function directCloudAuthFailure(response: Response, payload: unknown, endpoint: string): CloudMcpFailure | null {
  if (response.status === 401) {
    return failure({
      code: "invalid_mcp_token",
      stage: "transport_auth",
      retryable: false,
      recommendedAction: "Reconnect OmniRush.ai Cloud",
      message: "The OmniRush.ai Cloud MCP endpoint rejected the persisted Authorization header.",
      aliases: ["omnirush_cloud_auth_invalid"],
      details: { endpoint, status: response.status, response: payload },
    });
  }
  if (response.status === 403) {
    return failure({
      code: "wrong_mcp_resource",
      stage: "transport_auth",
      retryable: false,
      recommendedAction: "Check organization policy and resource access",
      message: "The OmniRush.ai Cloud MCP endpoint denied access to this resource.",
      aliases: ["omnirush_cloud_resource_forbidden"],
      details: { endpoint, status: response.status, response: payload },
    });
  }
  return null;
}

async function mcpJsonRpcPost(input: {
  url: string;
  headers: Record<string, string>;
  body: unknown;
}): Promise<{ response: Response; payload: unknown }> {
  const response = await withCloudEndpointProbeTimeout((signal) => externalFetch(input.url, {
    method: "POST",
    headers: input.headers,
    body: JSON.stringify(input.body),
    signal,
  }));
  return { response, payload: await readMcpJsonRpcPayload(response) };
}

function directToolsFromNames(names: string[]): DirectCloudToolsSnapshot {
  const split = splitPresentMissing(names, expectedDirectToolNames());
  const failureResult = split.missing.length
    ? directCloudToolsFailure({
        retryable: false,
        message: "The OmniRush.ai Cloud MCP endpoint tools/list is missing required unprefixed tools.",
        details: { expected: split.expected, present: split.present, missing: split.missing },
      })
    : undefined;
  return {
    checked: true,
    source: "mcp_tools_list",
    expected: split.expected,
    present: split.present,
    missing: split.missing,
    ...(failureResult ? { failure: failureResult } : {}),
  };
}

function directToolsNotChecked(): DirectCloudToolsSnapshot {
  return {
    checked: false,
    source: "mcp_tools_list",
    expected: expectedDirectToolNames(),
    present: [],
    missing: [],
  };
}

function toolsFromDirectCloudTools(directTools: DirectCloudToolsSnapshot): ToolSnapshot {
  if (!directTools.checked) return { expected: expectedTools(), present: [], missing: [] };
  if (directTools.missing.length === 0) {
    return splitPresentMissing(directTools.present.map(prefixedCloudToolId), expectedTools());
  }
  return splitPresentMissing([], expectedTools());
}

function toolsFromEngineAttestation(): ToolSnapshot {
  const expected = expectedTools();
  return { expected, present: [...expected], missing: [] };
}

// OpenCode collapses a failed remote connect to `Error.message` (often the bare
// "fetch failed"), so the probe preserves the cause chain (code/errno/syscall)
// — it is the only place the network-level cause survives for support.
function describeTransportError(error: unknown): Record<string, unknown> {
  const chain: Array<Record<string, unknown>> = [];
  let current: unknown = error;
  for (let depth = 0; depth < 5 && current !== undefined && current !== null; depth += 1) {
    if (!(current instanceof Error)) {
      chain.push({ message: sanitizeDiagnosticString(String(current)) });
      break;
    }
    const entry: Record<string, unknown> = { message: sanitizeDiagnosticString(current.message) };
    if (current.name && current.name !== "Error") entry.name = sanitizeDiagnosticString(current.name);
    const withCode = current as Error & { code?: unknown; errno?: unknown; syscall?: unknown };
    if (typeof withCode.code === "string") entry.code = sanitizeDiagnosticString(withCode.code);
    if (typeof withCode.errno === "number") entry.errno = withCode.errno;
    if (typeof withCode.syscall === "string") entry.syscall = sanitizeDiagnosticString(withCode.syscall);
    chain.push(entry);
    current = current.cause;
  }
  const first = chain[0] ?? { message: "unknown transport error" };
  return { ...first, ...(chain.length > 1 ? { causes: chain.slice(1) } : {}) };
}

async function readDirectCloudTools(config: Record<string, unknown>): Promise<DirectCloudToolsSnapshot> {
  const url = readString(config.url);
  const authorization = authorizationHeader(config);
  const endpoint = url ? sanitizeDiagnosticString(url) : null;
  const startedAtMs = Date.now();
  const steps: CloudMcpProbeStep[] = [];
  let protocolVersionSeen: string | null = null;
  let serverInfo: CloudMcpProbeTrace["serverInfo"] = null;
  const trace = (): CloudMcpProbeTrace => ({
    endpoint,
    startedAt: new Date(startedAtMs).toISOString(),
    latencyMs: Date.now() - startedAtMs,
    protocolVersion: protocolVersionSeen,
    serverInfo,
    steps,
  });
  const timed = async <T>(input: {
    step: CloudMcpProbeStepName;
    task: () => Promise<T>;
    httpStatus?: (value: T) => number;
    ok?: (value: T) => boolean;
  }): Promise<T> => {
    const stepStarted = Date.now();
    try {
      const value = await input.task();
      const httpStatus = input.httpStatus?.(value);
      steps.push({
        step: input.step,
        ok: input.ok ? input.ok(value) : true,
        ...(httpStatus !== undefined ? { httpStatus } : {}),
        latencyMs: Date.now() - stepStarted,
      });
      return value;
    } catch (error) {
      steps.push({ step: input.step, ok: false, latencyMs: Date.now() - stepStarted, error: describeTransportError(error) });
      throw error;
    }
  };
  if (!url || !authorization) {
    const failureResult = directCloudToolsFailure({
      retryable: false,
      message: "The persisted OmniRush.ai Cloud MCP config cannot be used for direct tools/list verification.",
      details: { endpoint, authorizationPresent: Boolean(authorization) },
    });
    return { ...directToolsNotChecked(), checked: true, missing: expectedDirectToolNames(), trace: trace(), error: failureResult.details, failure: failureResult };
  }

  const baseHeaders: Record<string, string> = {
    accept: "application/json, text/event-stream",
    authorization,
    "content-type": "application/json",
  };
  try {
    const initialized = await timed({
      step: "initialize",
      task: () => mcpJsonRpcPost({
        url,
        headers: baseHeaders,
        body: {
          id: 1,
          jsonrpc: "2.0",
          method: "initialize",
          params: {
            capabilities: {},
            clientInfo: { name: "omnirush-server-cloud-mcp-health", version: "1.0.0" },
            protocolVersion: "2025-06-18",
          },
        },
      }),
      httpStatus: (value) => value.response.status,
      ok: (value) => value.response.ok,
    });
    if (!initialized.response.ok) {
      const authFailure = directCloudAuthFailure(initialized.response, initialized.payload, endpoint ?? "unknown");
      const failureResult = authFailure ?? directCloudToolsFailure({
        retryable: initialized.response.status >= 500,
        message: "The OmniRush.ai Cloud MCP endpoint initialize request failed during direct verification.",
        details: { endpoint, status: initialized.response.status, response: initialized.payload },
      });
      return { ...directToolsNotChecked(), checked: true, missing: expectedDirectToolNames(), trace: trace(), error: failureResult.details, failure: failureResult };
    }

    const initRecord = jsonRpcRecord(initialized.payload);
    const initResult = initRecord && isRecord(initRecord.result) ? initRecord.result : null;
    const serverInfoRecord = initResult && isRecord(initResult.serverInfo) ? initResult.serverInfo : null;
    if (serverInfoRecord) {
      serverInfo = {
        name: typeof serverInfoRecord.name === "string" ? sanitizeDiagnosticString(serverInfoRecord.name) : null,
        version: typeof serverInfoRecord.version === "string" ? sanitizeDiagnosticString(serverInfoRecord.version) : null,
      };
    }

    const sessionId = initialized.response.headers.get("mcp-session-id");
    const protocolVersion = initialized.response.headers.get("mcp-protocol-version");
    protocolVersionSeen = protocolVersion
      ?? (initResult && typeof initResult.protocolVersion === "string" ? sanitizeDiagnosticString(initResult.protocolVersion) : null);
    const sessionHeaders: Record<string, string> = {
      ...baseHeaders,
      ...(sessionId ? { "mcp-session-id": sessionId } : {}),
      ...(protocolVersion ? { "mcp-protocol-version": protocolVersion } : {}),
    };
    await timed({
      step: "initialized_notice",
      task: () => withCloudEndpointProbeTimeout((signal) => externalFetch(url, {
        method: "POST",
        headers: sessionHeaders,
        body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }),
        signal,
      })),
      httpStatus: (value) => value.status,
      ok: (value) => value.ok,
    });
    const listed = await timed({
      step: "tools_list",
      task: () => mcpJsonRpcPost({
        url,
        headers: sessionHeaders,
        body: { id: 2, jsonrpc: "2.0", method: "tools/list", params: {} },
      }),
      httpStatus: (value) => value.response.status,
      ok: (value) => value.response.ok,
    });
    if (!listed.response.ok) {
      const authFailure = directCloudAuthFailure(listed.response, listed.payload, endpoint ?? "unknown");
      const failureResult = authFailure ?? directCloudToolsFailure({
        retryable: listed.response.status >= 500,
        message: "The OmniRush.ai Cloud MCP endpoint tools/list request failed during direct verification.",
        details: { endpoint, status: listed.response.status, response: listed.payload },
      });
      return { ...directToolsNotChecked(), checked: true, missing: expectedDirectToolNames(), trace: trace(), error: failureResult.details, failure: failureResult };
    }
    const toolNames = toolNamesFromMcpPayload(listed.payload);
    if (!toolNames.names) {
      const failureResult = directCloudToolsFailure({
        retryable: false,
        message: "The OmniRush.ai Cloud MCP endpoint tools/list response could not be parsed.",
        details: { endpoint, error: toolNames.error },
      });
      return { ...directToolsNotChecked(), checked: true, missing: expectedDirectToolNames(), trace: trace(), error: failureResult.details, failure: failureResult };
    }
    return { ...directToolsFromNames(toolNames.names), trace: trace() };
  } catch (error) {
    // Field incident (corporate Windows, TLS interception): a probe transport
    // failure must never be reported as missing tools — the engine's own MCP
    // connection uses a different network stack and is authoritative.
    const failureResult = failure({
      code: "probe_unreachable",
      stage: "tool_registration",
      retryable: true,
      recommendedAction: "Check this machine's network path (proxy/TLS trust) to the Cloud MCP endpoint. The engine's own MCP connection is authoritative.",
      message: "The OmniRush.ai server could not reach the Cloud MCP endpoint for direct verification (transport error before any HTTP response). This does not indicate missing tools.",
      details: { endpoint, error: error instanceof Error ? error.message : String(error), transport: describeTransportError(error) },
    });
    return { ...directToolsNotChecked(), checked: false, missing: [], trace: trace(), error: failureResult.details, failure: failureResult };
  }
}

function successfulDirectCloudToolsProbe(value: DirectCloudToolsSnapshot): boolean {
  return value.checked
    && value.failure === undefined
    && value.missing.length === 0
    && value.trace !== undefined
    && value.trace.steps.length > 0
    && value.trace.steps.every((step) => step.ok);
}

async function readDirectCloudToolsSingleFlight(input: {
  serverConfig: ServerConfig;
  workspace: WorkspaceInfo;
  directory: string | null;
  desiredConfig: Record<string, unknown>;
  desiredRevision: string;
}): Promise<DirectCloudToolsSnapshot> {
  const key = hashString(JSON.stringify({
    configPath: input.serverConfig.configPath,
    serverStartedAt: input.serverConfig.startedAt,
    workspaceId: input.workspace.id,
    directory: input.directory,
    desiredRevision: input.desiredRevision,
  }));
  const active = directCloudToolsProbeFlights.get(key);
  if (active) return active;

  const value = readDirectCloudTools(input.desiredConfig)
    .finally(() => {
      if (directCloudToolsProbeFlights.get(key) === value) directCloudToolsProbeFlights.delete(key);
    });
  directCloudToolsProbeFlights.set(key, value);
  return value;
}

async function readMcpStatus(
  opencode: WorkspaceOpencodeClient,
  directory: string | null,
): Promise<{ data?: Record<string, McpStatus>; failure?: CloudMcpFailure }> {
  try {
    const result = await withEngineProbeTimeout(() => opencode.mcp.status(locationParams(directory)));
    if (result.data) return { data: result.data };
    return { failure: opencodeRequestFailure("engine_delivery", "/mcp", result.response, result.error) };
  } catch (error) {
    return { failure: thrownOpencodeFailure("engine_delivery", "/mcp", error) };
  }
}

async function readToolIds(
  opencode: WorkspaceOpencodeClient,
  directory: string | null,
): Promise<{ data?: ToolIds; failure?: CloudMcpFailure }> {
  try {
    const result = await withEngineProbeTimeout(() => opencode.tool.ids(locationParams(directory)));
    if (result.data) return { data: result.data };
    return { failure: opencodeRequestFailure("tool_registration", "/experimental/tool/ids", result.response, result.error) };
  } catch (error) {
    return { failure: thrownOpencodeFailure("tool_registration", "/experimental/tool/ids", error) };
  }
}

async function readProviderProjection(input: {
  opencode: WorkspaceOpencodeClient;
  directory: string | null;
  providerModel: CloudMcpProviderModelContext;
  /** Kept for call-site compatibility; experimental MCP omissions always fall back. */
  experimentalToolIdsIncludeMcpTools: boolean | null;
}): Promise<ProviderProjectionSnapshot> {
  // experimentalToolIdsIncludeMcpTools is intentionally unused: a global IDs hit
  // must not hard-fail when the per-model experimental list omits MCP tools.
  void input.experimentalToolIdsIncludeMcpTools;
  let experimentalSplit: ToolSnapshot | null = null;
  let experimentalError: unknown;
  try {
    const result = await withEngineProbeTimeout(() => input.opencode.tool.list({
      ...locationParams(input.directory),
      provider: input.providerModel.provider,
      model: input.providerModel.model,
    }));
    if (!result.data) {
      experimentalError = opencodeRequestFailure("provider_projection", "/experimental/tool", result.response, result.error).details;
    } else {
      experimentalSplit = splitPresentMissing(toolListIds(result.data), expectedTools());
      if (experimentalSplit.missing.length === 0) {
        return {
          checked: true,
          provider: input.providerModel.provider,
          model: input.providerModel.model,
          source: "experimental_tool",
          present: experimentalSplit.present,
          missing: experimentalSplit.missing,
        };
      }
    }
  } catch (error) {
    experimentalError = thrownOpencodeFailure("provider_projection", "/experimental/tool", error).details;
  }

  // OpenCode's /experimental/tool enumerates ToolRegistry tools and often omits
  // MCP tools that prompts still attach at runtime. Always fall back to
  // /provider tool-call capability when the per-model experimental list is
  // incomplete — even if global /experimental/tool/ids includes MCP tools.
  return readProviderCapability({
    opencode: input.opencode,
    directory: input.directory,
    providerModel: input.providerModel,
    experimentalSplit,
    experimentalError,
  });
}

async function readProviderCapability(input: {
  opencode: WorkspaceOpencodeClient;
  directory: string | null;
  providerModel: CloudMcpProviderModelContext;
  experimentalSplit: ToolSnapshot | null;
  experimentalError: unknown;
}): Promise<ProviderProjectionSnapshot> {
  try {
    const result = await withEngineProbeTimeout(() => input.opencode.provider.list(locationParams(input.directory)));
    if (!result.data) {
      const projectionFailure = opencodeRequestFailure("provider_projection", "/provider", result.response, result.error);
      return {
        checked: true,
        provider: input.providerModel.provider,
        model: input.providerModel.model,
        source: "provider_capability",
        limitation: "Experimental OmniRush tool projection did not enumerate MCP tools; provider catalog capability could not be read.",
        present: input.experimentalSplit?.present ?? [],
        missing: input.experimentalSplit?.missing ?? expectedTools(),
        error: projectionFailure.details,
        failure: projectionFailure,
      };
    }

    const provider = result.data.all.find((item) => item.id === input.providerModel.provider);
    const model = provider?.models[input.providerModel.model];
    const modelExists = Boolean(model);
    const toolCalling = model ? model.capabilities.toolcall === true : null;
    const limitation = "OmniRush experimental tool APIs do not enumerate MCP tools on this engine; using provider/model tool-call capability from /provider.";
    const projectionFailure = toolCalling
      ? undefined
      : failure({
          code: "provider_tool_projection_missing",
          stage: "provider_projection",
          retryable: false,
          recommendedAction: "Choose a model that can use OmniRush.ai Cloud tools",
          message: modelExists ? "The selected provider/model does not support tool calling." : "The selected provider/model was not found in OmniRush provider catalog.",
          aliases: ["provider_projection_missing"],
          details: {
            provider: input.providerModel.provider,
            model: input.providerModel.model,
            source: "provider_capability",
            modelExists,
            toolCalling,
          },
        });
    return {
      checked: true,
      provider: input.providerModel.provider,
      model: input.providerModel.model,
      source: "provider_capability",
      limitation,
      modelExists,
      toolCalling,
      present: input.experimentalSplit?.present ?? [],
      missing: input.experimentalSplit?.missing ?? expectedTools(),
      ...(input.experimentalError ? { error: input.experimentalError } : {}),
      ...(projectionFailure ? { failure: projectionFailure } : {}),
    };
  } catch (error) {
    const projectionFailure = thrownOpencodeFailure("provider_projection", "/provider", error);
    return {
      checked: true,
      provider: input.providerModel.provider,
      model: input.providerModel.model,
      source: "provider_capability",
      limitation: "Experimental OmniRush tool projection did not enumerate MCP tools; provider catalog capability could not be read.",
      present: input.experimentalSplit?.present ?? [],
      missing: input.experimentalSplit?.missing ?? expectedTools(),
      error: projectionFailure.details,
      failure: projectionFailure,
    };
  }
}

function toolListIds(list: ToolList): string[] {
  return list.map((tool) => tool.id).filter((id) => typeof id === "string");
}

function statusFailure(status: McpStatus | undefined): CloudMcpFailure {
  if (!status) {
    return failure({
      code: "cloud_mcp_missing",
      stage: "engine_delivery",
      retryable: true,
      recommendedAction: "Run reconcile to register omnirush-cloud with OmniRush",
      message: "OmniRush does not report an omnirush-cloud MCP status.",
      aliases: ["cloud_status_missing"],
    });
  }
  if (status.status === "disabled") {
    return failure({
      code: "cloud_mcp_disabled",
      stage: "engine_delivery",
      retryable: false,
      recommendedAction: "Enable the omnirush-cloud MCP entry",
      message: "omnirush-cloud MCP is disabled.",
      aliases: ["cloud_disabled"],
    });
  }
  if (status.status === "needs_auth") {
    return failure({
      code: "cloud_mcp_needs_auth",
      stage: "transport_auth",
      retryable: false,
      recommendedAction: "Reconnect OmniRush.ai Cloud",
      message: "omnirush-cloud MCP needs authentication.",
      aliases: ["omnirush_cloud_auth_required"],
    });
  }
  if (status.status === "needs_client_registration") {
    return failure({
      code: "opencode_mcp_sync_failed",
      stage: "engine_delivery",
      retryable: false,
      recommendedAction: "Reconnect OmniRush.ai Cloud or update OmniRush.ai",
      message: "omnirush-cloud MCP needs OAuth client registration.",
      aliases: ["omnirush_cloud_client_registration_required"],
      details: { error: status.error },
    });
  }
  if (status.status === "failed") {
    return inferFailedStatus(status.error);
  }
  return failure({
    code: "opencode_mcp_sync_failed",
    stage: "engine_delivery",
    retryable: true,
    recommendedAction: "Retry reconcile",
    message: "omnirush-cloud MCP is not connected.",
    aliases: ["cloud_connection_failed"],
  });
}

function inferFailedStatus(error: string): CloudMcpFailure {
  const lower = error.toLowerCase();
  // Engines that preserve transport cause chains produce strings like
  // "fetch failed; caused by: certificate has expired (CERT_HAS_EXPIRED)".
  // Certificate/TLS wording ("expired", "authority", "revoked") must never be
  // classified as a token or session problem — reconnecting cannot repair a
  // broken transport, and richer engine errors must not change the verdict
  // for what is still a connection-level failure.
  const certTransport =
    lower.includes("certificat") ||
    lower.includes("cert_") ||
    lower.includes("tls") ||
    lower.includes("ssl") ||
    lower.includes("self signed") ||
    lower.includes("self-signed");
  if (!certTransport && lower.includes("expired")) {
    return failure({ code: "invalid_mcp_token", stage: "transport_auth", retryable: false, recommendedAction: "Reconnect OmniRush.ai Cloud", message: "omnirush-cloud token is expired.", aliases: ["omnirush_cloud_token_expired"], details: { error } });
  }
  if (!certTransport && (lower.includes("missing_mcp_token") || lower.includes("missing mcp token") || lower.includes("provide a bearer token"))) {
    return failure({ code: "missing_mcp_token", stage: "transport_auth", retryable: false, recommendedAction: "Refresh OmniRush.ai Cloud authentication", message: "omnirush-cloud token is missing.", aliases: ["omnirush_cloud_auth_required"], details: { error } });
  }
  if (!certTransport && (lower.includes("invalid_token") || lower.includes("unauthorized") || lower.includes("401") || lower.includes("auth"))) {
    return failure({ code: "invalid_mcp_token", stage: "transport_auth", retryable: false, recommendedAction: "Reconnect OmniRush.ai Cloud", message: "omnirush-cloud authentication failed.", aliases: ["omnirush_cloud_auth_invalid"], details: { error } });
  }
  if (!certTransport && (lower.includes("invalid_grant") || lower.includes("session") || lower.includes("revoked"))) {
    return failure({ code: "mcp_session_revoked", stage: "transport_auth", retryable: false, recommendedAction: "Reconnect OmniRush.ai Cloud", message: "omnirush-cloud session was revoked.", details: { error } });
  }
  if (lower.includes("membership") || lower.includes("member")) {
    return failure({ code: "mcp_membership_revoked", stage: "transport_auth", retryable: false, recommendedAction: "Ask an organization admin to grant access", message: "OmniRush.ai Cloud membership is required.", aliases: ["omnirush_cloud_membership_required"], details: { error } });
  }
  if (lower.includes("insufficient_scope") || lower.includes("scope")) {
    return failure({ code: "insufficient_mcp_scope", stage: "transport_auth", retryable: false, recommendedAction: "Reconnect OmniRush.ai Cloud with the required scopes", message: "omnirush-cloud token is missing required scopes.", aliases: ["omnirush_cloud_scope_missing"], details: { error } });
  }
  if (lower.includes("forbidden") || lower.includes("403") || lower.includes("policy")) {
    return failure({ code: "wrong_mcp_resource", stage: "transport_auth", retryable: false, recommendedAction: "Check organization policy and resource access", message: "OmniRush.ai Cloud denied access to this resource.", aliases: ["omnirush_cloud_resource_forbidden"], details: { error } });
  }
  if (lower.includes("not found") || lower.includes("404") || lower.includes("resource")) {
    return failure({ code: "wrong_mcp_resource", stage: "transport_auth", retryable: false, recommendedAction: "Reconnect OmniRush.ai Cloud or choose an accessible organization", message: "OmniRush.ai Cloud resource was not found.", aliases: ["omnirush_cloud_resource_not_found"], details: { error } });
  }
  if (lower.includes("client registration")) {
    return failure({ code: "opencode_mcp_sync_failed", stage: "engine_delivery", retryable: false, recommendedAction: "Reconnect OmniRush.ai Cloud or update OmniRush.ai", message: "omnirush-cloud needs client registration.", aliases: ["omnirush_cloud_client_registration_required"], details: { error } });
  }
  return failure({
    code: "opencode_mcp_sync_failed",
    stage: "engine_delivery",
    retryable: true,
    recommendedAction: "Retry reconcile or reconnect OmniRush.ai Cloud",
    message: "omnirush-cloud MCP connection failed.",
    aliases: ["cloud_connection_failed"],
    details: { error },
  });
}

function engineStatusFromMcpStatus(status: McpStatus | undefined): CloudMcpHealth["engine"] {
  if (!status) return { status: "missing" };
  if (status.status === "failed" || status.status === "needs_client_registration") {
    return { status: status.status, error: sanitizeDiagnosticValue(status.error) };
  }
  return { status: status.status };
}

function engineInspectionNotChecked(): CloudMcpEngineInspection {
  return { checked: false };
}

function engineInspectionFromStatuses(statuses: Record<string, McpStatus>): CloudMcpEngineInspection {
  const servers = Object.entries(statuses)
    .map(([name, status]) => ({
      name: sanitizeDiagnosticString(name),
      status: status.status,
      ...(("error" in status) && typeof status.error === "string" ? { error: sanitizeDiagnosticString(status.error) } : {}),
    }))
    .sort((a, b) => a.name.localeCompare(b.name))
    .slice(0, 50);
  return {
    checked: true,
    cloudPresent: Boolean(statuses[OMNIRUSH_CLOUD_MCP_NAME]),
    serverCount: Object.keys(statuses).length,
    servers,
  };
}

function readVersionFromHealthPayload(payload: unknown): string | null {
  if (!isRecord(payload)) return null;
  return typeof payload.version === "string" ? sanitizeDiagnosticString(payload.version) : null;
}

async function readOpencodeVersion(opencode: WorkspaceOpencodeClient): Promise<CloudMcpCompatibilitySnapshot["opencode"]> {
  try {
    const result = await withEngineProbeTimeout(() => opencode.global.health());
    if (result.data) {
      return { expectedVersion: null, actualVersion: readVersionFromHealthPayload(result.data), probe: "ok" };
    }
    return {
      expectedVersion: null,
      actualVersion: null,
      probe: "unavailable",
      error: sanitizeDiagnosticValue({ status: result.response?.status, error: result.error }),
    };
  } catch (error) {
    return {
      expectedVersion: null,
      actualVersion: null,
      probe: "unavailable",
      error: sanitizeDiagnosticValue(error instanceof Error ? error.message : String(error)),
    };
  }
}

async function inspectOmniRushCloud(input: {
  opencode: WorkspaceOpencodeClient;
  config: ServerConfig;
  workspace: WorkspaceInfo;
  directory: string | null;
  desiredConfig: Record<string, unknown>;
  desiredRevision: string;
  directProbeReuse?: DirectProbeReuse;
  providerModel?: CloudMcpProviderModelContext;
  probe: boolean;
  refreshRegistrationFromLiveStatus?: CloudMcpLiveStatusObserver;
}): Promise<Inspection> {
  const failures: CloudMcpFailure[] = [];
  const emptyTools = splitPresentMissing([], expectedTools());
  const emptyDirectTools = directToolsNotChecked();
  const emptyCanaries = splitPresentMissing([], expectedCanaries());
  const uncheckedExperimentalToolIds = experimentalToolIdsNotChecked();
  const uncheckedExperimentalProviderTools = experimentalProviderToolsFromProjection(providerProjectionNotChecked(input.providerModel));
  const opencodeVersion = await readOpencodeVersion(input.opencode);
  const statusResult = await readMcpStatus(input.opencode, input.directory);
  if (statusResult.failure) {
    failures.push(statusResult.failure);
    return {
      engine: { status: statusResult.failure.code === "opencode_engine_unreachable" ? "unreachable" : "unknown", error: statusResult.failure.details },
      engineInspection: engineInspectionNotChecked(),
      tools: emptyTools,
      directTools: emptyDirectTools,
      providerProjection: providerProjectionNotChecked(input.providerModel),
      pluginCanaries: emptyCanaries,
      experimentalToolIds: uncheckedExperimentalToolIds,
      experimentalProviderTools: uncheckedExperimentalProviderTools,
      opencodeVersion,
      failures,
    };
  }

  const engineInspection = engineInspectionFromStatuses(statusResult.data ?? {});
  const cloudStatus = statusResult.data?.[OMNIRUSH_CLOUD_MCP_NAME];
  if (cloudStatus) {
    input.refreshRegistrationFromLiveStatus?.(
      input.config,
      input.workspace,
      OMNIRUSH_CLOUD_MCP_NAME,
      input.desiredConfig,
      cloudStatus.status,
      "error" in cloudStatus && typeof cloudStatus.error === "string" ? cloudStatus.error : null,
    );
  }
  const engine = engineStatusFromMcpStatus(cloudStatus);
  if (cloudStatus?.status !== "connected") {
    failures.push(statusFailure(cloudStatus));
    return {
      engine,
      engineInspection,
      tools: emptyTools,
      directTools: emptyDirectTools,
      providerProjection: providerProjectionNotChecked(input.providerModel),
      pluginCanaries: emptyCanaries,
      experimentalToolIds: uncheckedExperimentalToolIds,
      experimentalProviderTools: uncheckedExperimentalProviderTools,
      opencodeVersion,
      failures,
    };
  }

  const idsResult = await readToolIds(input.opencode, input.directory);
  if (idsResult.failure) {
    failures.push(idsResult.failure);
    return {
      engine,
      engineInspection,
      tools: emptyTools,
      directTools: emptyDirectTools,
      providerProjection: providerProjectionNotChecked(input.providerModel),
      pluginCanaries: emptyCanaries,
      experimentalToolIds: experimentalToolIdsFromFailure(idsResult.failure),
      experimentalProviderTools: uncheckedExperimentalProviderTools,
      opencodeVersion,
      failures,
    };
  }
  const ids = idsResult.data ?? [];
  const experimentalToolIds = experimentalToolIdsFromSplit(splitPresentMissing(ids, expectedTools()));
  const pluginCanaries = splitPresentMissing(ids, expectedCanaries());
  const reusableDirectTools = input.directProbeReuse?.desiredRevision === input.desiredRevision
    && successfulDirectCloudToolsProbe(input.directProbeReuse.value)
    ? input.directProbeReuse.value
    : null;
  const directTools = input.probe
    ? reusableDirectTools ?? await readDirectCloudToolsSingleFlight({
      serverConfig: input.config,
      workspace: input.workspace,
      directory: input.directory,
      desiredConfig: input.desiredConfig,
      desiredRevision: input.desiredRevision,
    })
    : emptyDirectTools;
  if (input.probe) {
    // The engine is authoritative; a probe-only transport failure must stay diagnostic and not veto steering/delivery.
    if (directTools.failure && directTools.failure.code !== "probe_unreachable") {
      failures.push(directTools.failure);
    }
  }
  // OpenCode >=1.17 reports MCP "connected" only after initial tools/list succeeds;
  // the engine is the single source of truth unless an on-demand probe is requested.
  const tools = input.probe ? toolsFromDirectCloudTools(directTools) : toolsFromEngineAttestation();

  const providerProjection = input.providerModel
    ? await readProviderProjection({
        opencode: input.opencode,
        directory: input.directory,
        providerModel: input.providerModel,
        experimentalToolIdsIncludeMcpTools: experimentalToolIds.includesMcpTools,
      })
    : providerProjectionNotChecked(input.providerModel);
  const experimentalProviderTools = experimentalProviderToolsFromProjection(providerProjection);
  if (providerProjection.failure) failures.push(providerProjection.failure);

  if (pluginCanaries.missing.length) {
    failures.push(failure({
      code: "extensions_plugin_missing",
      stage: "plugin_load",
      retryable: true,
      recommendedAction: "Reload the OmniRush engine so OmniRush.ai extensions are loaded",
      message: "OmniRush.ai extension plugin canary tools are missing.",
      details: { missing: pluginCanaries.missing },
    }));
  }

  return { engine, engineInspection, tools, directTools, providerProjection, pluginCanaries, experimentalToolIds, experimentalProviderTools, opencodeVersion, failures };
}

function providerProjectionNotChecked(providerModel?: CloudMcpProviderModelContext): ProviderProjectionSnapshot {
  return {
    checked: false,
    ...(providerModel ? { provider: providerModel.provider, model: providerModel.model } : {}),
    present: [],
    missing: [],
  };
}

function experimentalToolIdsNotChecked(): CloudMcpExperimentalToolIdsSnapshot {
  return {
    checked: false,
    expected: expectedTools(),
    present: [],
    missing: [],
    includesMcpTools: null,
  };
}

function experimentalToolIdsFromSplit(split: ToolSnapshot): CloudMcpExperimentalToolIdsSnapshot {
  const includesMcpTools = split.missing.length === 0;
  return {
    checked: true,
    expected: split.expected,
    present: split.present,
    missing: split.missing,
    includesMcpTools,
    ...(includesMcpTools ? {} : { limitation: "This OmniRush engine's /experimental/tool/ids endpoint does not enumerate MCP tools; direct MCP tools/list is authoritative for Cloud readiness." }),
  };
}

function experimentalToolIdsFromFailure(failureResult: CloudMcpFailure): CloudMcpExperimentalToolIdsSnapshot {
  return {
    checked: true,
    expected: expectedTools(),
    present: [],
    missing: expectedTools(),
    includesMcpTools: null,
    error: failureResult.details,
  };
}

function experimentalProviderToolsFromProjection(projection: ProviderProjectionSnapshot): CloudMcpExperimentalProviderToolsSnapshot {
  if (!projection.checked) {
    return {
      checked: false,
      ...(projection.provider ? { provider: projection.provider } : {}),
      ...(projection.model ? { model: projection.model } : {}),
      expected: expectedTools(),
      present: [],
      missing: [],
      includesMcpTools: null,
    };
  }
  const includesMcpTools = projection.source === "experimental_tool" && projection.missing.length === 0;
  return {
    checked: true,
    ...(projection.provider ? { provider: projection.provider } : {}),
    ...(projection.model ? { model: projection.model } : {}),
    expected: expectedTools(),
    present: projection.present,
    missing: projection.missing,
    includesMcpTools,
    ...(includesMcpTools ? {} : { limitation: projection.limitation ?? "This OmniRush engine's /experimental/tool endpoint does not enumerate MCP tools for the selected provider/model." }),
    ...(projection.error ? { error: projection.error } : {}),
  };
}

function phaseFromFailure(firstFailure: CloudMcpFailure | null): CloudMcpHealthPhase {
  if (!firstFailure) return "ready";
  if (firstFailure.code === "cloud_mcp_missing" && firstFailure.stage === "engine_delivery") return "engine_missing";
  if (firstFailure.code === "cloud_mcp_missing" || firstFailure.code === "cloud_desired_missing") return "missing_desired";
  if (firstFailure.code === "cloud_endpoint_invalid" || firstFailure.code === "cloud_token_org_mismatch") return "missing_desired";
  if (firstFailure.code === "workspace_directory_ambiguous") return "workspace_ambiguous";
  if (firstFailure.code === "opencode_unconfigured") return "engine_unconfigured";
  if (firstFailure.code === "opencode_engine_unreachable" || firstFailure.code === "opencode_unreachable") return "engine_unreachable";
  if (firstFailure.code === "cloud_status_missing") return "engine_missing";
  if (firstFailure.code === "cloud_mcp_disabled" || firstFailure.code === "cloud_disabled") return "engine_disabled";
  if (
    firstFailure.code === "cloud_mcp_needs_auth" ||
    firstFailure.code === "invalid_mcp_token" ||
    firstFailure.code === "mcp_session_revoked" ||
    firstFailure.code === "mcp_membership_revoked" ||
    firstFailure.code === "insufficient_mcp_scope" ||
    firstFailure.code === "wrong_mcp_resource" ||
    firstFailure.code === "omnirush_cloud_auth_required" ||
    firstFailure.code === "omnirush_cloud_auth_invalid" ||
    firstFailure.code === "omnirush_cloud_token_expired"
  ) return "engine_needs_auth";
  if (firstFailure.code === "omnirush_cloud_client_registration_required") return "engine_needs_client_registration";
  if (firstFailure.code === "opencode_mcp_sync_failed" || firstFailure.code === "cloud_registration_failed") return "registration_failed";
  if (firstFailure.code === "cloud_tools_denied") return "denied_by_tools";
  if (firstFailure.code === "opencode_tool_ids_unsupported") return "tool_ids_unsupported";
  if (firstFailure.code === "cloud_tools_missing") return "cloud_tools_missing";
  if (firstFailure.code === "provider_tool_projection_missing" || firstFailure.code === "provider_projection_missing" || firstFailure.code === "provider_projection_unavailable") return "provider_projection_missing";
  if (firstFailure.code === "extensions_plugin_missing") return "extensions_plugin_missing";
  return "engine_failed";
}

function firstFailureFromDenies(denies: McpToolDeny[]): CloudMcpFailure | null {
  if (!denies.length) return null;
  return failure({
    code: "cloud_tools_denied",
    stage: "prerequisites",
    retryable: false,
    recommendedAction: "Remove project/global OmniRush tool denies for omnirush-cloud tools",
    message: "OmniRush configuration denies one or more omnirush-cloud tools.",
    details: { denies },
  });
}

function chooseFirstFailure(failures: CloudMcpFailure[]): CloudMcpFailure | null {
  return failures[0] ?? null;
}

function usableByModel(providerProjection: ProviderProjectionSnapshot, firstFailure: CloudMcpFailure | null): boolean | null {
  if (!providerProjection.checked) return null;
  if (firstFailure?.stage === "provider_projection") return false;
  if (providerProjection.source === "provider_capability") return providerProjection.modelExists === true && providerProjection.toolCalling === true;
  return providerProjection.missing.length === 0;
}

function baseUrlConfigured(config: ServerConfig, workspace: WorkspaceInfo): boolean {
  return Boolean(workspace.baseUrl?.trim() || config.opencodeBaseUrl?.trim());
}

async function pluginFileHashes(): Promise<CloudMcpCompatibilitySnapshot["pluginFileHashes"]> {
  const names = ["omnirush-extensions-preview", "omnirush-capabilities-knowledge"];
  return Promise.all(names.map(async (name) => {
    try {
      return { name, sha256: hashString(await readFile(omnirushPluginPath(name), "utf8")) };
    } catch (error) {
      const lastError = error instanceof Error ? error.message : String(error);
      return { name, sha256: null, error: sanitizeDiagnosticString(lastError) };
    }
  }));
}

async function compatibilitySnapshot(input: {
  serverMetadata?: CloudMcpServerMetadata;
  appMetadata?: Record<string, string | number | boolean | null>;
  directory: string | null;
  inspection: Inspection;
}): Promise<CloudMcpCompatibilitySnapshot> {
  const opencode = {
    ...input.inspection.opencodeVersion,
    expectedVersion: input.serverMetadata?.expectedOpencodeVersion ?? null,
  };
  return {
    omnirush: {
      serverVersion: input.serverMetadata?.serverVersion ?? null,
      app: input.appMetadata ?? null,
    },
    opencode,
    pluginFileHashes: await pluginFileHashes(),
    supportedFeatures: {
      dynamicMcp: true,
      directoryScoping: input.directory !== null,
      toolIds: !input.inspection.failures.some((item) => item.code === "opencode_tool_ids_unsupported" || item.code === "opencode_tool_ids_unavailable"),
      providerToolProjection: input.inspection.providerProjection.checked && !input.inspection.failures.some((item) => item.stage === "provider_projection" && item.code !== "provider_tool_projection_missing"),
      pluginCanaries: input.inspection.pluginCanaries.expected.length > 0,
    },
    experimentalToolIds: input.inspection.experimentalToolIds,
    experimentalProviderTools: input.inspection.experimentalProviderTools,
  };
}

type ReadOmniRushCloudMcpHealthInput = {
  config: ServerConfig;
  workspace: WorkspaceInfo;
  directory: string | null;
  providerModel?: CloudMcpProviderModelContext;
  serverMetadata?: CloudMcpServerMetadata;
  probe?: boolean;
  createWorkspaceOpencodeClient: (config: ServerConfig, workspace: WorkspaceInfo) => WorkspaceOpencodeClient;
  refreshRegistrationFromLiveStatus?: CloudMcpLiveStatusObserver;
};

type DirectProbeReuse = {
  desiredRevision: string;
  value: CloudMcpHealth["tools"]["direct"];
};

async function readOmniRushCloudMcpHealthInternal(
  input: ReadOmniRushCloudMcpHealthInput & { directProbeReuse?: DirectProbeReuse },
): Promise<CloudMcpHealth> {
  const checkedAt = new Date().toISOString();
  const startedAtMs = Date.now();
  const desired = await readDesiredState({ config: input.config, workspace: input.workspace, directory: input.directory });
  let delivery = cloudMcpDeliveryState.snapshot(input.workspace, input.directory, desired.revision);
  const toolDenies = desired.present
    ? await diagnoseMcpToolDenies(input.workspace.path, OMNIRUSH_CLOUD_MCP_NAME, expectedTools())
    : [];
  const failures: CloudMcpFailure[] = [];

  if (!desired.present) {
    failures.push(failure({
      code: "cloud_mcp_missing",
      stage: "desired_config",
      retryable: false,
      recommendedAction: "Connect OmniRush.ai Cloud",
      message: "No global omnirush-cloud MCP desired config is persisted.",
      aliases: ["cloud_desired_missing"],
    }));
  }
  if (desired.validationProblem) {
    failures.push(failureFromValidationProblem(desired.validationProblem));
  }
  if (desired.present && !input.directory) {
    failures.push(failure({
      code: "workspace_directory_ambiguous",
      stage: "prerequisites",
      retryable: false,
      recommendedAction: "Set an explicit OmniRush directory for this remote workspace",
      message: "Remote workspace has no exact OmniRush directory, so Cloud MCP readiness cannot be claimed.",
    }));
  }
  if (desired.present && input.directory && !baseUrlConfigured(input.config, input.workspace)) {
    failures.push(failure({
      code: "opencode_unconfigured",
      stage: "prerequisites",
      retryable: false,
      recommendedAction: "Start or attach an OmniRush engine for this workspace",
      message: "OmniRush base URL is missing for this workspace.",
    }));
  }
  const denyFailure = firstFailureFromDenies(toolDenies);
  if (denyFailure) failures.push(denyFailure);

  let inspection: Inspection = {
    engine: { status: "not_checked" },
    engineInspection: engineInspectionNotChecked(),
    tools: splitPresentMissing([], expectedTools()),
    directTools: directToolsNotChecked(),
    providerProjection: providerProjectionNotChecked(input.providerModel),
    pluginCanaries: splitPresentMissing([], expectedCanaries()),
    experimentalToolIds: experimentalToolIdsNotChecked(),
    experimentalProviderTools: experimentalProviderToolsFromProjection(providerProjectionNotChecked(input.providerModel)),
    opencodeVersion: { expectedVersion: input.serverMetadata?.expectedOpencodeVersion ?? null, actualVersion: null, probe: "not_checked" },
    failures: [],
  };
  if (desired.present && desired.config && desired.revision && !desired.validationProblem && input.directory && baseUrlConfigured(input.config, input.workspace)) {
    inspection = await inspectOmniRushCloud({
      opencode: input.createWorkspaceOpencodeClient(input.config, input.workspace),
      config: input.config,
      workspace: input.workspace,
      directory: input.directory,
      desiredConfig: desired.config,
      desiredRevision: desired.revision,
      directProbeReuse: input.directProbeReuse,
      providerModel: input.providerModel,
      probe: input.probe === true,
      refreshRegistrationFromLiveStatus: input.refreshRegistrationFromLiveStatus,
    });
    failures.push(...inspection.failures);
  }

  if (
    desired.present
    && desired.revision
    && failures.length === 0
    && (delivery.appliedRevision !== desired.revision || delivery.state !== "ready")
  ) {
    cloudMcpDeliveryState.markDesired(input.workspace, input.directory, desired.revision, desired.metadata);
    cloudMcpDeliveryState.markReady(input.workspace, input.directory, desired.revision);
    delivery = cloudMcpDeliveryState.snapshot(input.workspace, input.directory, desired.revision);
  }

  const firstFailure = chooseFirstFailure(failures);
  const compatibility = await compatibilitySnapshot({
    serverMetadata: input.serverMetadata,
    appMetadata: desired.metadata.app,
    directory: input.directory,
    inspection,
  });
  return {
    schemaVersion: 1,
    phase: phaseFromFailure(firstFailure),
    usable: firstFailure === null,
    usableByCurrentModel: usableByModel(inspection.providerProjection, firstFailure),
    connectCatalogEnabled: desired.metadata.connectCatalogEnabled,
    workspace: {
      id: input.workspace.id,
      type: input.workspace.workspaceType,
      directory: input.directory,
      path: input.workspace.path,
    },
    desired: {
      present: desired.present,
      name: OMNIRUSH_CLOUD_MCP_NAME,
      revision: desired.revision,
      config: desired.redactedConfig,
      token: desired.metadata.token,
      ...(desired.metadata.org ? { org: desired.metadata.org } : {}),
      ...(desired.metadata.app ? { app: desired.metadata.app } : {}),
      updatedAt: desired.metadata.updatedAt,
    },
    delivery,
    engine: inspection.engine,
    engineInspection: inspection.engineInspection,
    tools: {
      expected: inspection.tools.expected,
      present: inspection.tools.present,
      missing: inspection.tools.missing,
      direct: {
        checked: inspection.directTools.checked,
        source: inspection.directTools.source,
        expected: inspection.directTools.expected,
        present: inspection.directTools.present,
        missing: inspection.directTools.missing,
        ...(inspection.directTools.trace ? { trace: inspection.directTools.trace } : {}),
        ...(inspection.directTools.error ? { error: inspection.directTools.error } : {}),
        ...(inspection.directTools.failure ? { failure: inspection.directTools.failure } : {}),
      },
      providerProjection: {
        checked: inspection.providerProjection.checked,
        ...(inspection.providerProjection.provider ? { provider: inspection.providerProjection.provider } : {}),
        ...(inspection.providerProjection.model ? { model: inspection.providerProjection.model } : {}),
        ...(inspection.providerProjection.source ? { source: inspection.providerProjection.source } : {}),
        ...(inspection.providerProjection.limitation ? { limitation: inspection.providerProjection.limitation } : {}),
        ...(inspection.providerProjection.modelExists !== undefined ? { modelExists: inspection.providerProjection.modelExists } : {}),
        ...(inspection.providerProjection.toolCalling !== undefined ? { toolCalling: inspection.providerProjection.toolCalling } : {}),
        present: inspection.providerProjection.present,
        missing: inspection.providerProjection.missing,
        ...(inspection.providerProjection.error ? { error: inspection.providerProjection.error } : {}),
      },
    },
    pluginCanaries: inspection.pluginCanaries,
    compatibility,
    toolDenies,
    firstFailure,
    checkedAt,
    durationMs: Date.now() - startedAtMs,
  };
}

export async function readOmniRushCloudMcpHealth(input: ReadOmniRushCloudMcpHealthInput): Promise<CloudMcpHealth> {
  return readOmniRushCloudMcpHealthInternal(input);
}

async function persistDesiredConfig(config: ServerConfig, desiredConfig: Record<string, unknown>): Promise<{ changed: boolean }> {
  const migrated = await migrateOmniRushCloudMcpRuntimeConfig(config);
  const written = await writeGlobalRuntimeOpencodeConfig(config, (current) => ({
    ...current,
    mcp: {
      ...runtimeMcpMap(current),
      [OMNIRUSH_CLOUD_MCP_NAME]: desiredConfig,
    },
  }));
  // Connect is server/account-scoped: keep a host-level copy for catalog + skill injection.
  // Dynamic import avoids a connect-state <-> cloud-mcp-health cycle.
  const { writeConnectCloudMcp } = await import("./connect-state.js");
  await writeConnectCloudMcp(config, desiredConfig);
  return { changed: migrated.changed || written.changed };
}

function registrationFailure(failures: CloudMcpRuntimeRegistrationFailure[]): CloudMcpFailure {
  return failure({
    code: "opencode_mcp_sync_failed",
    stage: "engine_delivery",
    retryable: failures.some((item) => item.status === undefined || item.status >= 500),
    recommendedAction: "Retry reconcile after OmniRush is reachable",
    message: "Failed to dynamically register omnirush-cloud with OmniRush.",
    aliases: ["cloud_registration_failed"],
    details: { failures },
  });
}

async function wait(ms: number): Promise<void> {
  if (ms === 0) return;
  await new Promise((resolve) => setTimeout(resolve, ms));
}

async function pollConnected(input: {
  opencode: WorkspaceOpencodeClient;
  config: ServerConfig;
  workspace: WorkspaceInfo;
  directory: string | null;
  desiredConfig: Record<string, unknown>;
  refreshRegistrationFromLiveStatus?: CloudMcpLiveStatusObserver;
}): Promise<CloudMcpFailure | null> {
  let lastFailure: CloudMcpFailure | null = null;
  for (const delay of POLL_DELAYS_MS) {
    await wait(delay);
    const statusResult = await readMcpStatus(input.opencode, input.directory);
    if (statusResult.failure) {
      lastFailure = statusResult.failure;
      continue;
    }
    const cloudStatus = statusResult.data?.[OMNIRUSH_CLOUD_MCP_NAME];
    if (cloudStatus) {
      input.refreshRegistrationFromLiveStatus?.(
        input.config,
        input.workspace,
        OMNIRUSH_CLOUD_MCP_NAME,
        input.desiredConfig,
        cloudStatus.status,
      );
    }
    if (cloudStatus?.status === "connected") return null;
    lastFailure = statusFailure(cloudStatus);
    if (cloudStatus?.status === "disabled" || cloudStatus?.status === "needs_auth" || cloudStatus?.status === "needs_client_registration" || cloudStatus?.status === "failed") {
      return lastFailure;
    }
  }
  return lastFailure;
}

function healthWithFailure(health: CloudMcpHealth, firstFailure: CloudMcpFailure): CloudMcpHealth {
  return {
    ...health,
    phase: phaseFromFailure(firstFailure),
    usable: false,
    usableByCurrentModel: health.tools.providerProjection.checked ? false : health.usableByCurrentModel,
    firstFailure,
  };
}

function reusableDirectProbeFromHealth(health: CloudMcpHealth): DirectProbeReuse | undefined {
  return health.desired.revision && successfulDirectCloudToolsProbe(health.tools.direct)
    ? { desiredRevision: health.desired.revision, value: health.tools.direct }
    : undefined;
}

export async function reconcileOmniRushCloudMcp(input: {
  config: ServerConfig;
  workspace: WorkspaceInfo;
  directory: string | null;
  body: Record<string, unknown>;
  providerModel?: CloudMcpProviderModelContext;
  serverMetadata?: CloudMcpServerMetadata;
  createWorkspaceOpencodeClient: (config: ServerConfig, workspace: WorkspaceInfo) => WorkspaceOpencodeClient;
  registerRuntimeMcp: CloudMcpRuntimeRegistrar;
  refreshRegistrationFromLiveStatus?: CloudMcpLiveStatusObserver;
  fanoutGlobalDesired?: boolean;
}): Promise<CloudMcpHealth> {
  const readHealth = (directProbeReuse?: DirectProbeReuse) => readOmniRushCloudMcpHealthInternal({
    config: input.config,
    workspace: input.workspace,
    directory: input.directory,
    providerModel: input.providerModel,
    serverMetadata: input.serverMetadata,
    createWorkspaceOpencodeClient: input.createWorkspaceOpencodeClient,
    probe: true,
    directProbeReuse,
    refreshRegistrationFromLiveStatus: input.refreshRegistrationFromLiveStatus,
  });
  const configBody = input.body.config ?? input.body;
  const desiredConfig = canonicalizeCloudMcpConfig(normalizeCloudMcpConfig(configBody));
  const metadata = extractDesiredMetadata(input.body, desiredConfig);
  const validationProblem = strictCloudMcpDesiredConfigProblem(desiredConfig, metadata);
  if (validationProblem) {
    const validationFailure = failureFromValidationProblem(validationProblem);
    return healthWithFailure(await readHealth(), validationFailure);
  }
  const desiredRevision = await calculateCloudMcpDesiredRevision(desiredConfig, metadata);
  const persisted = await persistDesiredConfig(input.config, desiredConfig);
  cloudMcpDeliveryState.markDesired(input.workspace, input.directory, desiredRevision, metadata);

  // Re-deliver to other workspaces only when the global desired config actually
  // changed: an unchanged reconcile must not bounce healthy connections elsewhere.
  if (persisted.changed && input.fanoutGlobalDesired !== false) {
    await Promise.all(input.config.workspaces
      .filter((workspace) => workspace.id !== input.workspace.id)
      .map(async (workspace) => {
        const directory = workspace.workspaceType === "local" ? workspace.path : workspace.directory ?? null;
        if (!directory) return;
        await input.createWorkspaceOpencodeClient(input.config, workspace).mcp.disconnect({
          name: OMNIRUSH_CLOUD_MCP_NAME,
          ...locationParams(directory),
        }).catch(() => undefined);
        await input.registerRuntimeMcp(input.config, workspace, [OMNIRUSH_CLOUD_MCP_NAME], { throwOnFailure: false })
          .catch(() => undefined);
      }));
  }

  if (!input.directory) {
    const directoryFailure = failure({
      code: "workspace_directory_ambiguous",
      stage: "prerequisites",
      retryable: false,
      recommendedAction: "Set an explicit OmniRush directory for this remote workspace",
      message: "Remote workspace has no exact OmniRush directory, so Cloud MCP readiness cannot be claimed.",
    });
    cloudMcpDeliveryState.markFailed(input.workspace, input.directory, desiredRevision, directoryFailure);
    return healthWithFailure(await readHealth(), directoryFailure);
  }

  if (!baseUrlConfigured(input.config, input.workspace)) {
    const unconfiguredFailure = failure({
      code: "opencode_unconfigured",
      stage: "prerequisites",
      retryable: false,
      recommendedAction: "Start or attach an OmniRush engine for this workspace",
      message: "OmniRush base URL is missing for this workspace.",
    });
    cloudMcpDeliveryState.markFailed(input.workspace, input.directory, desiredRevision, unconfiguredFailure);
    return healthWithFailure(await readHealth(), unconfiguredFailure);
  }

  // Provider descriptors are private App-host state. Fetch them only after
  // the normal engine prerequisites pass, then purge stale model-runtime
  // entries before registration. Independent projection filters keep stale
  // rows from ever reaching an engine while prerequisites are unavailable.
  const { reconcileOmniRushConnectMcpServers } = await import("./connect-mcp-server-catalog.js");
  const connectServers = await reconcileOmniRushConnectMcpServers({
    config: input.config,
    workspace: input.workspace,
    cloudMcp: desiredConfig,
    appHostAuthorization: readString(input.body.appHostAuthorization) ?? undefined,
  }).catch(() => ({ status: "unavailable" as const, appHostNames: [], directNames: [], removedNames: [] }));

  const opencode = input.createWorkspaceOpencodeClient(input.config, input.workspace);
  for (const name of connectServers.removedNames) {
    await opencode.mcp.disconnect({ name, ...locationParams(input.directory) }).catch(() => undefined);
  }

  cloudMcpDeliveryState.markRegistering(input.workspace, input.directory, desiredRevision);
  const registration = await input.registerRuntimeMcp(input.config, input.workspace, [OMNIRUSH_CLOUD_MCP_NAME], { throwOnFailure: false });
  if (registration.failures.length > 0) {
    const registrationError = registrationFailure(registration.failures);
    cloudMcpDeliveryState.markFailed(input.workspace, input.directory, desiredRevision, registrationError);
    return healthWithFailure(await readHealth(), registrationError);
  }
  // Directly exposed connections ride the same credential but are separate
  // servers: one unreachable provider must not mark central Cloud MCP unhealthy.
  if (connectServers.directNames.length > 0) {
    await input.registerRuntimeMcp(input.config, input.workspace, connectServers.directNames, { throwOnFailure: false })
      .catch(() => undefined);
  }

  const connectedFailure = await pollConnected({
    opencode,
    config: input.config,
    workspace: input.workspace,
    directory: input.directory,
    desiredConfig,
    refreshRegistrationFromLiveStatus: input.refreshRegistrationFromLiveStatus,
  });
  if (connectedFailure) {
    cloudMcpDeliveryState.markFailed(input.workspace, input.directory, desiredRevision, connectedFailure);
    return healthWithFailure(await readHealth(), connectedFailure);
  }

  const health = await readHealth();
  const directProbeReuse = reusableDirectProbeFromHealth(health);

  if (health.firstFailure) {
    cloudMcpDeliveryState.markFailed(input.workspace, input.directory, desiredRevision, health.firstFailure);
    return healthWithFailure(await readHealth(directProbeReuse), health.firstFailure);
  }

  cloudMcpDeliveryState.markReady(input.workspace, input.directory, desiredRevision);
  return readHealth(directProbeReuse);
}

export async function reconcilePersistedOmniRushCloudMcp(input: {
  config: ServerConfig;
  workspace: WorkspaceInfo;
  directory: string | null;
  providerModel?: CloudMcpProviderModelContext;
  serverMetadata?: CloudMcpServerMetadata;
  createWorkspaceOpencodeClient: (config: ServerConfig, workspace: WorkspaceInfo) => WorkspaceOpencodeClient;
  registerRuntimeMcp: CloudMcpRuntimeRegistrar;
  refreshRegistrationFromLiveStatus?: CloudMcpLiveStatusObserver;
  trigger?: string;
}): Promise<CloudMcpHealth> {
  const migrated = await migrateOmniRushCloudMcpRuntimeConfig(input.config);
  if (input.config.readOnly) return readOmniRushCloudMcpHealth(input);
  const desiredConfig = migrated.config ?? await readPersistedDesiredConfig(input.config, input.workspace.id);
  if (!desiredConfig) {
    return readOmniRushCloudMcpHealth(input);
  }
  return reconcileOmniRushCloudMcp({
    ...input,
    body: {
      config: desiredConfig,
      ...(input.trigger ? { trigger: input.trigger } : {}),
    },
    fanoutGlobalDesired: false,
  });
}

export function markOmniRushCloudMcpStale(workspace: WorkspaceInfo, directory: string | null): void {
  cloudMcpDeliveryState.markWorkspaceStale(workspace, directory);
}

export type CloudMcpEngineRefreshStep = {
  step: "engine_disconnect" | "reapply";
  ok: boolean;
  latencyMs: number;
  detail?: unknown;
};

export type CloudMcpEngineRefresh = {
  performed: boolean;
  reason?: "desired_missing";
  trigger: string;
  startedAt: string;
  finishedAt: string;
  steps: CloudMcpEngineRefreshStep[];
};

export type CloudMcpEngineRefreshResult = {
  refresh: CloudMcpEngineRefresh;
  health: CloudMcpHealth;
};

// OpenCode never retries a failed MCP connection on its own: a remote connect
// failure is stored as {status:"failed"} and the client is dropped until
// something external re-drives it. This refresh closes any wedged client
// first (disconnect), then re-runs the persisted reconcile, which re-POSTs
// /mcp — an unconditional fresh connect attempt on the engine side.
export async function refreshOmniRushCloudMcpEngine(input: {
  config: ServerConfig;
  workspace: WorkspaceInfo;
  directory: string | null;
  providerModel?: CloudMcpProviderModelContext;
  serverMetadata?: CloudMcpServerMetadata;
  createWorkspaceOpencodeClient: (config: ServerConfig, workspace: WorkspaceInfo) => WorkspaceOpencodeClient;
  registerRuntimeMcp: CloudMcpRuntimeRegistrar;
  refreshRegistrationFromLiveStatus?: CloudMcpLiveStatusObserver;
  trigger?: string;
}): Promise<CloudMcpEngineRefreshResult> {
  const trigger = input.trigger?.trim() || "engine-refresh";
  const startedAt = new Date().toISOString();
  const steps: CloudMcpEngineRefreshStep[] = [];
  const finish = (performed: boolean, health: CloudMcpHealth, reason?: "desired_missing"): CloudMcpEngineRefreshResult => ({
    refresh: {
      performed,
      ...(reason ? { reason } : {}),
      trigger,
      startedAt,
      finishedAt: new Date().toISOString(),
      steps,
    },
    health,
  });

  const desiredConfig = await readPersistedDesiredConfig(input.config, input.workspace.id);
  if (!desiredConfig) {
    return finish(false, await readOmniRushCloudMcpHealth({ ...input, probe: true }), "desired_missing");
  }

  const disconnectStarted = Date.now();
  try {
    const opencode = input.createWorkspaceOpencodeClient(input.config, input.workspace);
    const result = await withEngineProbeTimeout(() => opencode.mcp.disconnect({
      name: OMNIRUSH_CLOUD_MCP_NAME,
      ...locationParams(input.directory),
    }));
    steps.push({
      step: "engine_disconnect",
      ok: result.error === undefined,
      latencyMs: Date.now() - disconnectStarted,
      ...(result.error !== undefined
        ? { detail: sanitizeDiagnosticValue({ status: result.response?.status, error: result.error }) }
        : {}),
    });
  } catch (error) {
    // A dynamically-registered entry can be gone after an engine state
    // rebuild, and the engine itself can be down; the reapply below is the
    // authoritative step either way.
    steps.push({
      step: "engine_disconnect",
      ok: false,
      latencyMs: Date.now() - disconnectStarted,
      detail: sanitizeDiagnosticValue(describeTransportError(error)),
    });
  }

  const reapplyStarted = Date.now();
  const health = await reconcilePersistedOmniRushCloudMcp({
    config: input.config,
    workspace: input.workspace,
    directory: input.directory,
    providerModel: input.providerModel,
    serverMetadata: input.serverMetadata,
    createWorkspaceOpencodeClient: input.createWorkspaceOpencodeClient,
    registerRuntimeMcp: input.registerRuntimeMcp,
    refreshRegistrationFromLiveStatus: input.refreshRegistrationFromLiveStatus,
    trigger,
  });
  steps.push({
    step: "reapply",
    ok: health.firstFailure === null,
    latencyMs: Date.now() - reapplyStarted,
    ...(health.firstFailure ? { detail: { code: health.firstFailure.code, stage: health.firstFailure.stage } } : {}),
  });
  return finish(true, health);
}