@uipath/solution-tool 1.203.0-preview.212 → 1.204.0-preview.211

package/dist/{packager-tool-4kdt8mys.js → packager-tool-j30xck4w.js}

@@ -1,37 +1,81 @@
 import {
-  Configuration,
-  PipelinesApi,
-  feedResolutionFailureInstructions,
+  appendDeploymentStateInstructions,
+  deploymentNextSteps,
+  explainRefusal,
+  needsPendingResources,
+  readPendingResourcesAsync
+} from "./packager-tool-ks8spnq8.js";
+import {
+  INCOMPLETE_SWEEP_ADVICE,
+  findDeploymentAcrossFeeds,
+  isNameOrFeedRefusal,
+  reportIncompleteSweepAsync,
+  retryAdvice
+} from "./packager-tool-40vcj4wv.js";
+import {
+  DeploymentSearchNeedsUserSessionError,
+  MAX_LISTED_DEPLOYMENTS,
+  blocksRedeploy,
+  deploymentToTerminalPipelineResult,
+  findDeploymentBestEffort,
+  findDeploymentByName,
+  findDeploymentsByName,
+  findDeploymentsByPackageName,
+  formatExistingDeployments,
+  interpretFailedDeployPoll,
+  isAuthRefusal,
+  isCompletedUninstall,
+  isPipelineDeploymentNotFoundError,
+  mapOperationStatusToPipelineStatus,
+  newestDeploymentRow,
+  resolveInstalledFolder,
+  searchDeploymentsPage
+} from "./packager-tool-482eg22x.js";
+import {
+  Configuration as Configuration2,
+  DeploymentOperation,
+  DeploymentStatus,
+  PipelinesApi
+} from "./packager-tool-qgaqqq41.js";
+import {
+  describeFeedResolutionFailureAsync,
   feedScopeInitOverride,
+  feedSelectorFlag,
   folderKeyInitOverride,
-  listSelectablePublishLocations,
   resolveFeedScope,
   resolvePersonalWorkspace
-} from "./packager-tool-2p5yh1q9.js";
+} from "./packager-tool-qdtjywsk.js";
 import {
-  Configuration as Configuration2,
-  DeploymentOperationStatus,
+  Configuration,
   DeploymentsApi,
   SearchApi,
   SolutionDeploymentAction,
-  deploymentsAutoInstall,
-  searchPackageVersions
-} from "./packager-tool-7qmx64kz.js";
+  WorkflowAction
+} from "./packager-tool-00vh1ktg.js";
+import {
+  classifyFeedSession,
+  feedReadRefusalForApplication,
+  feedSessionRefusal
+} from "./packager-tool-bqre28m1.js";
+import {
+  getSolutionAuthContext
+} from "./packager-tool-f5gq77m5.js";
 import {
-  getSolutionAuthContext,
   resolveFolder
-} from "./packager-tool-2syrt51a.js";
+} from "./packager-tool-3fv6zc86.js";
 import {
   DEFAULT_PAGE_SIZE,
   PollOutcome,
   catchError,
   extractErrorDetails,
-  getFileSystem,
   logger,
   mapPollFailure,
   pollUntil,
   processContext
-} from "./packager-tool-0f0wt9vh.js";
+} from "./packager-tool-5fjp60dk.js";
+import {
+  getFileSystem
+} from "./packager-tool-zf3929se.js";
 import {
   __commonJS,
   __require
@@ -7087,6 +7131,10 @@ function formatDetailedValidationError(error) {
   const prefix = resource ? `${resource}: ` : "";
   return `${formatErrorCode(error.errorCode)}${prefix}${error.errorText}`;
 }
+function formatDetailedConflictError(error) {
+  const actions = error.conflictFixingActions?.length ? ` (fix: ${error.conflictFixingActions.join(", ")})` : "";
+  return `${formatDetailedValidationError(error)}${actions}`;
+}
 function formatDetailedScheduleError(error) {
   return `${formatErrorCode(error.errorCode)}${error.errorText}`;
 }
@@ -7123,13 +7171,24 @@ function formatDeploymentIdentifiers(pipelineDeploymentId, status) {
   return `Operation: ${identifiers.join(", ")}`;
 }
 function formatDeploymentFailureDetails(pipelineDeploymentId, status) {
+  return [
+    ...formatPipelineErrors(status),
+    formatDeploymentIdentifiers(pipelineDeploymentId, status)
+  ].join(`
+`);
+}
+function formatPipelineErrors(status) {
   const errorParts = [];
   const validationErrors = status.validationResult?.validationErrors;
   if (validationErrors?.length) {
     errorParts.push(`Validation: ${validationErrors.map(formatDetailedValidationError).join("; ")}`);
   }
+  const conflictErrors = status.validationResult?.conflictErrors;
+  if (conflictErrors?.length) {
+    errorParts.push(`Conflicts: ${conflictErrors.map(formatDetailedConflictError).join("; ")}`);
+  }
   if (status.conflictFixingErrors?.length) {
-    errorParts.push(`Conflicts: ${status.conflictFixingErrors.map(formatDetailedValidationError).join("; ")}`);
+    errorParts.push(`Conflict fixing: ${status.conflictFixingErrors.map(formatDetailedValidationError).join("; ")}`);
   }
   if (status.deploymentScheduleErrors?.length) {
     errorParts.push(`Schedule: ${status.deploymentScheduleErrors.map(formatDetailedScheduleError).join("; ")}`);
@@ -7142,215 +7201,26 @@ function formatDeploymentFailureDetails(pipelineDeploymentId, status) {
   if (serviceErrors?.length) {
     errorParts.push(`Services: ${serviceErrors.join("; ")}`);
   }
-  errorParts.push(formatDeploymentIdentifiers(pipelineDeploymentId, status));
-  return errorParts.join(`
-`);
-}
-
-// src/services/deployment-search.ts
-async function findDeploymentByName(auth, deploymentName, scope) {
-  const api = new SearchApi(new Configuration2({
-    basePath: auth.basePath,
-    accessToken: auth.accessToken
-  }));
-  const take = 50;
-  for (let skip = 0;; ) {
-    const result = await api.searchSearchDeployments22({
-      deploymentsSearchRequest2: {
-        searchTerm: deploymentName,
-        take,
-        skip,
-        operationStatuses: [],
-        activationStatuses: []
-      }
-    }, scope);
-    const values = result.values ?? [];
-    const match = values.find((deployment) => deployment.name === deploymentName);
-    if (match) {
-      return match;
-    }
-    if (values.length < take) {
-      return;
-    }
-    skip += values.length;
-  }
-}
-async function findDeploymentsByPackageName(auth, packageName, options = {}) {
-  const api = new SearchApi(new Configuration2({
-    basePath: auth.basePath,
-    accessToken: auth.accessToken
-  }));
-  const take = 50;
-  const maxPages = 20;
-  const matches = [];
-  for (let page = 0, skip = 0;page < maxPages; page++) {
-    const result = await api.searchSearchDeployments22({
-      deploymentsSearchRequest2: {
-        searchTerm: packageName,
-        packageName,
-        take,
-        skip,
-        operationStatuses: [],
-        activationStatuses: []
-      }
-    }, options.scope);
-    const values = result.values ?? [];
-    for (const deployment of values) {
-      if (deployment.packageName === packageName && (options.folderPath === undefined || deployment.folderPath === options.folderPath)) {
-        matches.push(deployment);
-      }
-    }
-    if (values.length < take) {
-      break;
-    }
-    skip += values.length;
-  }
-  return matches;
-}
-function blocksRedeploy(deployment) {
-  if (deployment.operationStatus === "InProgress") {
-    return true;
-  }
-  if (deployment.operationStatus === "Successful") {
-    return deployment.operation !== "Uninstall";
-  }
-  if (deployment.operationStatus === "Draft" || deployment.operationStatus === "Failed" || deployment.operationStatus === "FailedRollback") {
-    return deployment.operation !== undefined && deployment.operation !== null && deployment.operation !== "Install";
-  }
-  return false;
+  return errorParts;
 }
-var MAX_LISTED_DEPLOYMENTS = 5;
-function formatExistingDeployments(deployments, folderByKey) {
-  const described = deployments.slice(0, MAX_LISTED_DEPLOYMENTS).map((deployment) => {
-    const resolved = deployment.installedRootFolderKey ? folderByKey?.get(deployment.installedRootFolderKey) : undefined;
-    const folder = resolved ?? deployment.folderPath ?? "an unknown folder";
-    const current = deployment.currentPackageVersion ?? deployment.packageVersion ?? "an unknown version";
-    const target = deployment.targetPackageVersion ?? deployment.newPackageVersionAvailable;
-    const version = target && target !== current ? `${current} → ${target}` : current;
-    const state = [
-      deployment.operation,
-      deployment.operationStatus,
-      deployment.activationStatus
-    ].filter((part) => part !== undefined && part !== null).join("/");
-    return `'${deployment.name}' in ${folder} (version ${version}${state ? `, ${state}` : ""})`;
-  }).join("; ");
-  const remaining = deployments.length - MAX_LISTED_DEPLOYMENTS;
-  return remaining > 0 ? `${described}; and ${remaining} more (see: uip solution deploy list)` : described;
+function hasServerErrorCode(details, code) {
+  return new RegExp(`"errorCode"\\s*:\\s*"${code}"`).test(details);
 }
-async function findDeploymentBestEffort(auth, deploymentName, scope) {
-  const [lookupError, deployment] = await catchError(findDeploymentByName(auth, deploymentName, scope));
-  if (lookupError) {
-    return;
-  }
-  return deployment;
+function isBareResponse(details) {
+  return !/^\s*[{[]/.test(details);
 }
-function appendDraftDeploymentInstructions(instructions, deployment) {
-  if (deployment?.operationStatus !== "Draft") {
-    return instructions;
-  }
-  return `${instructions}
-Deployment '${deployment.name}' exists but is still in Draft state (OperationStatus: ${deployment.operationStatus}, ActivationStatus: ${deployment.activationStatus}). Draft deployments are created by deploy runs that did not complete successfully and cannot be activated. Fix the deploy run validation errors, rerun 'uip solution deploy run', then activate after 'uip solution deploy list' shows the deployment is no longer Draft.`;
+var DRAFT_VERSION_MISMATCH_CODE = "DraftDeploymentHasDifferentPackageVersion";
+function leavesPendingDraft(status) {
+  return status === "ValidationFailed" || status === "ConflictFixingError" || status === "DeploymentScheduleError";
 }
-async function isPipelineDeploymentNotFoundError(error) {
-  if (!error || typeof error !== "object") {
-    return false;
-  }
-  const response = error.response;
-  if (!response || typeof response !== "object") {
-    return false;
-  }
-  const status = response.status;
-  if (status !== 404) {
-    return false;
-  }
-  const [bodyError, body] = await catchError(response.clone().text());
-  if (bodyError || !body) {
-    return false;
-  }
-  return body.includes("PipelineDeploymentNotFound");
+function installLandedDespiteStatus(status) {
+  const record = status.deploymentResult?.status;
+  return status.status !== "DeploymentSucceeded" && (record === "SuccessfulInstall" || record === "SuccessfulActivate");
 }
-function interpretFailedDeployPoll(deployment) {
-  if (!deployment) {
-    return;
-  }
-  if (deployment.operationStatus === "Failed" || deployment.operationStatus === "FailedRollback") {
-    return {
-      kind: "DeployFailed",
-      operationStatus: deployment.operationStatus
-    };
-  }
-  if (deployment.operationStatus !== "Successful") {
-    return;
-  }
-  switch (deployment.activationStatus) {
-    case "Active":
-      return { kind: "Active", instanceId: deployment.instanceId };
-    case "NeedsSetupToActivate":
-      return { kind: "NeedsSetupToActivate" };
-    case "ReadyToActivate":
-    case "Inactive":
-      return { kind: "ReadyToActivate" };
-    case "ActivationFailed":
-      return { kind: "ActivationFailed" };
-    default:
-      return;
-  }
-}
-function isSettledDeployOperationStatus(operationStatus) {
-  return operationStatus === "Successful" || operationStatus === "Failed" || operationStatus === "FailedRollback";
-}
-function mapOperationStatusToPipelineStatus(operationStatus) {
-  switch (operationStatus) {
-    case "Successful":
-      return "DeploymentSucceeded";
-    case "Failed":
-    case "FailedRollback":
-    case "Draft":
-      return "DeploymentFailed";
-    default:
-      return;
-  }
-}
-function deploymentToTerminalPipelineResult(deployment) {
-  const status = mapOperationStatusToPipelineStatus(deployment.operationStatus);
-  if (!status) {
-    return;
-  }
-  return {
-    status,
-    validationResult: { validationErrors: [], conflictErrors: [] },
-    deploymentKey: deployment.installDeploymentKey ?? deployment.key,
-    configurationKey: deployment.configurationKey,
-    instanceId: deployment.instanceId
-  };
-}
-async function resolveInstalledFolder(deployment, requested, resolveFolderByKey) {
-  const fallback = {
-    folderName: requested.folderName,
-    folderPath: requested.folderPath,
-    requestedMatched: true
-  };
-  const pathFor = (name, path) => path ?? (requested.parentFolderPath ? `${requested.parentFolderPath}/${name}` : name);
-  const folderKey = deployment?.installedRootFolderKey;
-  if (folderKey && resolveFolderByKey) {
-    const [lookupError, folder] = await catchError(resolveFolderByKey(folderKey));
-    if (!lookupError && folder?.name) {
-      return {
-        folderName: folder.name,
-        folderPath: pathFor(folder.name, folder.path ?? deployment?.folderPath ?? undefined),
-        requestedMatched: folder.name === requested.folderName
-      };
-    }
-  }
-  const resolvedName = deployment?.installedRootFolderName;
-  if (resolvedName) {
-    return {
-      folderName: resolvedName,
-      folderPath: pathFor(resolvedName, deployment?.folderPath ?? undefined),
-      requestedMatched: resolvedName === requested.folderName
-    };
-  }
-  return fallback;
+function explainPipelineStatusAfterInstall(status) {
+  const lines = formatPipelineErrors(status);
+  const errors = lines.length > 0 ? ` ${lines.join(" ")}` : "";
+  return `The deploy pipeline ended at ${status.status} although the install landed (the deployment record reports ${status.deploymentResult?.status}): the errors it attached come from the activation validation the pipeline runs after the install, not from the install.${errors}`;
 }
 
 // src/services/activation.ts
@@ -7359,19 +7229,22 @@ var TERMINAL_STATUSES = new Set([
   "FailedActivate"
 ]);
 async function activateDeployment(auth, deploymentName, options) {
-  const api = new PipelinesApi(new Configuration({
+  const api = new PipelinesApi(new Configuration2({
     basePath: auth.basePath,
     accessToken: auth.accessToken
   }));
   const [stepsError, steps] = await catchError(api.pipelinesGetPreActivateSteps({ deploymentName }, options.scope));
   if (stepsError) {
-    const { message, details } = await extractErrorDetails(stepsError);
+    const { message, details, errorCode, retry, context } = await extractErrorDetails(stepsError);
     const deployment = await findDeploymentBestEffort(auth, deploymentName, options.scope);
     return {
       kind: "RequestFailed",
       phase: "preActivateSteps",
       message,
       details,
+      errorCode,
+      retry,
+      httpStatus: context?.httpStatus,
       deployment
     };
   }
@@ -7383,13 +7256,16 @@ async function activateDeployment(auth, deploymentName, options) {
   }
   const [activateError, activateResult] = await catchError(api.pipelinesActivate({ deploymentName }, options.scope));
   if (activateError) {
-    const { message, details } = await extractErrorDetails(activateError);
+    const { message, details, errorCode, retry, context } = await extractErrorDetails(activateError);
     const deployment = await findDeploymentBestEffort(auth, deploymentName, options.scope);
     return {
       kind: "RequestFailed",
       phase: "activate",
       message,
       details,
+      errorCode,
+      retry,
+      httpStatus: context?.httpStatus,
       deployment
     };
   }
@@ -7427,44 +7303,6 @@ async function activateDeployment(auth, deploymentName, options) {
   };
 }
 
-// src/services/deployment-feed-locator.ts
-async function nonTenantFeedKeysAsync(options) {
-  const [listError, locations] = await catchError(listSelectablePublishLocations({
-    tenant: options.tenant,
-    loginValidity: options.loginValidity,
-    envFilePath: options.envFilePath
-  }));
-  if (!listError) {
-    const rank = (location) => location.type === "PersonalWorkspace" ? 0 : 1;
-    return [...locations].filter((location) => location.type !== "Tenant" && location.key).sort((a, b) => rank(a) - rank(b)).map((location) => location.key);
-  }
-  const [, personalWorkspace] = await catchError(resolvePersonalWorkspace({
-    tenant: options.tenant,
-    loginValidity: options.loginValidity,
-    envFilePath: options.envFilePath
-  }));
-  return personalWorkspace?.key ? [personalWorkspace.key] : [];
-}
-async function findDeploymentAcrossFeeds(auth, deploymentName, options) {
-  const tenantMatch = await findDeploymentByName(auth, deploymentName);
-  if (tenantMatch) {
-    return { deployment: tenantMatch };
-  }
-  const feedKeys = await nonTenantFeedKeysAsync(options);
-  for (const folderKey of feedKeys) {
-    const scope = folderKeyInitOverride(folderKey);
-    const [, deployment] = await catchError(findDeploymentByName(auth, deploymentName, scope));
-    if (deployment) {
-      return { deployment, scope };
-    }
-  }
-  return;
-}
-async function findDeploymentAcrossFeedsBestEffort(auth, deploymentName, options) {
-  const [, location] = await catchError(findDeploymentAcrossFeeds(auth, deploymentName, options));
-  return location ?? undefined;
-}
-
 // src/services/deploy-activate-service.ts
 var fail = (reason, message, instructions, exitCode = 1) => ({
   ok: false,
@@ -7474,6 +7312,22 @@ var fail = (reason, message, instructions, exitCode = 1) => ({
   exitCode
 });
 var AUTH_INSTRUCTIONS = "Run 'uip login' to refresh credentials, then retry activation. If the deployment is in a different tenant, switch with 'uip login tenant set <tenant>'.";
+async function incompleteSweepRefusalAsync(deploymentName, skipped, result) {
+  const details = `Details: ${result.details}`;
+  if (!isNameOrFeedRefusal(result.errorCode, result.httpStatus)) {
+    return {
+      ...fail("request_failed", result.message, `The activation request failed. ${retryAdvice(result.errorCode, result.retry, "Orchestrator")} ${details}`),
+      errorCode: result.errorCode,
+      retry: result.retry
+    };
+  }
+  const report = await reportIncompleteSweepAsync(deploymentName, skipped);
+  return {
+    ...fail("request_failed", report.message, `${INCOMPLETE_SWEEP_ADVICE} Without its feed the activation went to the tenant feed, which refused it. ${report.nextStep} ${details} (feed search: ${report.details})`),
+    errorCode: report.errorCode,
+    retry: report.retry
+  };
+}
 async function activateDeploymentAsync(deploymentName, options = {}) {
   const [authError, auth] = await catchError(getSolutionAuthContext({
     tenant: options.tenant,
@@ -7483,11 +7337,12 @@ async function activateDeploymentAsync(deploymentName, options = {}) {
   if (authError) {
     return fail("auth_failed", authError.message, AUTH_INSTRUCTIONS);
   }
-  const location = await findDeploymentAcrossFeedsBestEffort(auth, deploymentName, {
+  const sweep = await findDeploymentAcrossFeeds(auth, deploymentName, {
     tenant: options.tenant,
     loginValidity: options.loginValidity,
     envFilePath: options.envFilePath
   });
+  const location = sweep.location;
   const result = await activateDeployment(auth, deploymentName, {
     timeoutSeconds: options.timeout ?? 360,
     pollIntervalMs: options.pollInterval ?? 5000,
@@ -7495,8 +7350,20 @@ async function activateDeploymentAsync(deploymentName, options = {}) {
     scope: location?.scope
   });
   if (result.kind === "RequestFailed") {
-    const fallback = result.phase === "preActivateSteps" ? `Check deployment name. Deploy first with: uip solution deploy run. Details: ${result.details}` : `Check deployment name matches an existing deployment. Details: ${result.details}`;
-    return fail("request_failed", result.message, appendDraftDeploymentInstructions(fallback, result.deployment));
+    const details = `Details: ${result.details}`;
+    const known = result.deployment ?? location?.deployment;
+    if (!known && !sweep.complete) {
+      return incompleteSweepRefusalAsync(deploymentName, sweep.skipped, result);
+    }
+    const pendingResources = known && needsPendingResources(known) ? await readPendingResourcesAsync(new DeploymentsApi(new Configuration({
+      basePath: auth.basePath,
+      accessToken: auth.accessToken
+    })), known.key, location?.scope) : undefined;
+    const feedSelector = feedSelectorFlag(location?.feed);
+    const explanation = known ? explainRefusal(known, pendingResources, feedSelector) : undefined;
+    const instructions = explanation ? [...explanation, details].join(`
+`) : known ? `Deployment '${known.name}' exists (Operation: ${known.operation}, OperationStatus: ${known.operationStatus}, ActivationStatus: ${known.activationStatus}) but the service refused to activate it. Check it with: uip solution deploy status ${known.key}${feedSelector}. ${details}` : result.phase === "preActivateSteps" ? `Check deployment name. Deploy first with: uip solution deploy run. ${details}` : `Check deployment name matches an existing deployment. ${details}`;
+    return fail("request_failed", result.message, instructions);
   }
   if (result.kind === "NoInstance") {
     return {
@@ -7570,13 +7437,51 @@ async function resolveFolderInfo(options) {
   return { key: resolved.key, path: resolved.path };
 }
 
+// src/services/search-failure.ts
+async function describeSearchFailureAsync(error, what, session, { userSessionsOnly }) {
+  const details = await extractErrorDetails(error);
+  if (userSessionsOnly && details.context?.httpStatus === 401 && classifyFeedSession(session) === "application") {
+    return {
+      message: `Failed to list ${what}: Solution Search accepts user sessions only, and this session is an external app.`,
+      instructions: `Run it with a user session ('uip login'). A client-credentials login cannot list solution ${what}.`,
+      errorCode: "permission_denied",
+      retry: "RetryWillNotFix",
+      context: details.context
+    };
+  }
+  return {
+    message: `Failed to list ${what}: ${details.message}`,
+    instructions: searchFailureInstructions(details.errorCode, details.retry),
+    errorCode: details.errorCode,
+    retry: details.retry,
+    context: details.context
+  };
+}
+function searchFailureInstructions(errorCode, retry) {
+  if (errorCode === "authentication_required") {
+    return "Run 'uip login' to refresh the session, then run the command again.";
+  }
+  if (errorCode === "permission_denied") {
+    return "Use an account that can read Automation Solutions in this tenant.";
+  }
+  if (retry === "RetryLater") {
+    return "Wait a moment, then run the command again.";
+  }
+  return "Check the options and the session ('uip login status --detailed'), then run the command again.";
+}
+
 // src/services/deploy-list-service.ts
-var fail2 = (reason, message, instructions, exitCode = 1) => ({
+var fail2 = (reason, message, instructions, extras = {}) => ({
   ok: false,
   reason,
   message,
   instructions,
-  exitCode
+  exitCode: 1,
+  ...extras
+});
+var refuseFeedRead = (refusal) => fail2("feed_requires_user_session", refusal.message, refusal.instructions, {
+  errorCode: "permission_denied",
+  retry: "RetryWillNotFix"
 });
 async function listDeploymentsAsync(options = {}) {
   const limit = options.limit ?? DEFAULT_PAGE_SIZE;
@@ -7589,6 +7494,12 @@ async function listDeploymentsAsync(options = {}) {
   if (authError) {
     return fail2("auth_failed", authError.message, authError.message);
   }
+  if (options.personalWorkspace) {
+    const refusal = feedReadRefusalForApplication(auth, "Listing the Personal Workspace's deployments");
+    if (refusal) {
+      return refuseFeedRead(refusal);
+    }
+  }
   const [folderError, folderPathFilter] = await catchError(resolveParentFolder({
     folderPath: options.folderPath,
     folderKey: options.folderKey,
@@ -7607,30 +7518,34 @@ async function listDeploymentsAsync(options = {}) {
     envFilePath: options.envFilePath
   }));
   if (scopeError) {
-    return fail2("feed_resolution_failed", scopeError.message, feedResolutionFailureInstructions(options));
-  }
-  const api = new SearchApi(new Configuration2({
-    basePath: auth.basePath,
-    accessToken: auth.accessToken
-  }));
-  const [listError, result] = await catchError(api.searchSearchDeployments22({
-    deploymentsSearchRequest2: {
-      take: limit,
-      skip: offset,
-      orderByColumn: options.sortBy ?? "startTime",
-      orderByDirection: options.sortOrder ?? "Descending",
-      operationStatuses: options.operationStatuses ?? [],
-      activationStatuses: options.activationStatuses ?? []
-    }
+    const { message, instructions, ...extras } = await describeFeedResolutionFailureAsync(scopeError, options, auth);
+    return fail2("feed_resolution_failed", message, instructions, extras);
+  }
+  if (scope.kind !== "tenant") {
+    const refusal = feedReadRefusalForApplication(auth, `Listing the deployments of the feed '${scope.name ?? scope.folderKey}'`);
+    if (refusal) {
+      return refuseFeedRead(refusal);
+    }
+  }
+  const [listError, result] = await catchError(searchDeploymentsPage(auth, {
+    take: limit,
+    skip: offset,
+    orderByColumn: options.sortBy ?? "startTime",
+    orderByDirection: options.sortOrder ?? "Descending",
+    operationStatuses: options.operationStatuses ?? [],
+    activationStatuses: options.activationStatuses ?? [],
+    ...folderPathFilter ? { targetFolderName: folderPathFilter } : {}
   }, feedScopeInitOverride(scope)));
-  if (listError) {
-    const { message, details } = await extractErrorDetails(listError);
-    return fail2("list_request_failed", message, `Failed to list deployments. Details: ${details}`);
+  if (listError instanceof DeploymentSearchNeedsUserSessionError) {
+    return fail2("list_request_failed", `Failed to list deployments: ${listError.message}`, "Run it with a user session ('uip login'). A client-credentials login cannot list deployments on this server.", { errorCode: "permission_denied", retry: "RetryWillNotFix" });
   }
-  let values = result.values ?? [];
-  if (folderPathFilter) {
-    values = values.filter((d) => d.folderPath === folderPathFilter || d.folderPath?.startsWith(`${folderPathFilter}/`));
+  if (listError) {
+    const { message, instructions, ...extras } = await describeSearchFailureAsync(listError, "deployments", auth, {
+      userSessionsOnly: false
+    });
+    return fail2("list_request_failed", message, instructions, extras);
   }
+  const values = result.values ?? [];
   const deployments = values.map((d) => ({
     key: d.key,
     installDeploymentKey: d.installDeploymentKey,
@@ -7720,7 +7635,7 @@ async function describeValidationFailureAsync(deploymentsApi, deploymentKey, dep
   return messages.length > 0 ? messages.join("; ") : NO_SERVER_REASON;
 }
 async function describeDeploymentFailureAsync(auth, deployment, deploymentAction, scope, signal) {
-  const deploymentsApi = new DeploymentsApi(new Configuration2({
+  const deploymentsApi = new DeploymentsApi(new Configuration({
     basePath: auth.basePath,
     accessToken: auth.accessToken
   }));
@@ -7734,79 +7649,96 @@ async function describeDeploymentFailureAsync(auth, deployment, deploymentAction
   return NO_SERVER_REASON;
 }
 
-// src/services/personal-workspace-deploy.ts
-async function deployToFeed(auth, target, params) {
-  const config = new Configuration2({
-    basePath: auth.basePath,
-    accessToken: auth.accessToken
-  });
-  const searchApi = new SearchApi(config);
-  const feedScope = folderKeyInitOverride(target.feedFolderKey);
-  const take = 50;
-  let pkg;
-  for (let skip = 0;; ) {
-    const packages = await searchApi.searchSearchPackages({ searchFilter: { searchTerm: params.packageName, take, skip } }, feedScope);
-    const values = packages.values ?? [];
-    pkg = values.find((p) => p.name === params.packageName);
-    if (pkg || values.length < take) {
-      break;
-    }
-    skip += values.length;
-  }
-  if (!pkg) {
-    throw new Error(`Package '${params.packageName}' was not found in the target feed. Publish it there first with: uip solution publish <package> --feed <name-or-key>.`);
-  }
-  let packageVersionKey = pkg.packageVersionKey;
-  if (params.packageVersion && params.packageVersion !== pkg.latestVersion) {
-    packageVersionKey = await resolvePackageVersionKey(auth, pkg, params.packageVersion, target.feedFolderKey);
-  }
-  await deploymentsAutoInstall({ basePath: auth.basePath, accessToken: auth.accessToken }, {
-    deploymentName: params.deploymentName,
-    packageVersionKey,
-    newDeploymentKey: crypto.randomUUID(),
-    forceActivate: !params.skipActivate,
-    installationFolderKey: target.locationFolderKey,
-    pathFullyQualifiedName: target.locationFQN,
-    packageAndDeploy: false,
-    solutionRootFolderName: params.solutionRootFolderName,
-    pauseBeforeRun: false,
-    runtimeSetup: { requireServerlessTemplate: true }
-  }, target.feedFolderKey);
+// src/services/pipeline-deploy-poll.ts
+var PIPELINE_TERMINAL_STATUSES = new Set([
+  "DeploymentSucceeded",
+  "DeploymentFailed",
+  "ValidationFailed",
+  "ConflictFixingError",
+  "DeploymentScheduleError"
+]);
+var NO_ERRORS = {
+  validationResult: { validationErrors: [], conflictErrors: [] },
+  conflictFixingErrors: [],
+  deploymentScheduleErrors: []
+};
+function stillInFlight(deploymentKey) {
   return {
-    deploymentName: params.deploymentName,
-    packageName: params.packageName,
-    packageVersion: params.packageVersion || pkg.latestVersion,
-    folderFQN: target.locationFQN
+    status: "DeploymentInProgress",
+    deploymentKey: deploymentKey ?? "",
+    configurationKey: "",
+    ...NO_ERRORS
   };
 }
-async function resolvePackageVersionKey(auth, pkg, version, feedFolderKey) {
-  const take = 50;
-  for (let skip = 0;; ) {
-    const page = await searchPackageVersions({ basePath: auth.basePath, accessToken: auth.accessToken }, pkg.key, {
-      searchTerm: version,
-      take,
-      skip,
-      excludeInvalidPackages: true
-    }, feedFolderKey);
-    const match = page.values.find((v) => v.version === version);
-    if (match) {
-      return match.key;
-    }
-    if (page.values.length < take) {
-      throw new Error(`Version '${version}' of package '${pkg.name}' was not found in the target feed (latest is '${pkg.latestVersion}'). List versions with: uip solution packages list, or publish that version to the feed first.`);
-    }
-    skip += page.values.length;
+async function readOutcomeByKeyAsync(api, deploymentKey) {
+  const [error, info] = await catchError(() => api.pipelinesGetDeploymentByKey({ key: deploymentKey }));
+  if (error || !info) {
+    return;
+  }
+  if (info.deploymentKey !== deploymentKey) {
+    return;
+  }
+  if (info.operation === "Uninstall" || info.operationStatus === "Draft") {
+    return stillInFlight(deploymentKey);
   }
+  const status = mapOperationStatusToPipelineStatus(info.operationStatus);
+  if (!status) {
+    return stillInFlight(deploymentKey);
+  }
+  return {
+    status,
+    deploymentKey: info.deploymentKey,
+    configurationKey: "",
+    ...NO_ERRORS,
+    synthesizedOperation: info.operation
+  };
+}
+async function pollPipelineDeploymentAsync(api, auth, options) {
+  let observedDeploymentKey;
+  return pollUntil({
+    fn: async () => {
+      try {
+        const status = await api.pipelinesGetPipelineDeploymentStatus({ pipelineDeploymentId: options.pipelineDeploymentId }, options.scope);
+        if (status.deploymentKey) {
+          observedDeploymentKey = status.deploymentKey;
+        }
+        return status;
+      } catch (err) {
+        if (!await isPipelineDeploymentNotFoundError(err)) {
+          throw err;
+        }
+        if (!observedDeploymentKey) {
+          return stillInFlight(undefined);
+        }
+        const byKey = await readOutcomeByKeyAsync(api, observedDeploymentKey);
+        if (byKey) {
+          return byKey;
+        }
+        const deployment = await findDeploymentBestEffort(auth, options.deploymentName, options.scope, { deploymentKey: observedDeploymentKey });
+        if (!deployment || deployment.operationStatus === "Draft") {
+          return stillInFlight(observedDeploymentKey);
+        }
+        const synthesized = deploymentToTerminalPipelineResult(deployment);
+        if (!synthesized) {
+          return stillInFlight(observedDeploymentKey);
+        }
+        return {
+          ...synthesized,
+          synthesizedOperation: deployment.operation
+        };
+      }
+    },
+    until: (result) => PIPELINE_TERMINAL_STATUSES.has(result.status),
+    getStatus: (result) => result.status,
+    label: `deployment ${options.pipelineDeploymentId}`,
+    logPrefix: options.logPrefix,
+    timeoutMs: options.timeoutMs,
+    intervalMs: options.intervalMs,
+    signal: options.signal
+  });
 }
 
 // src/services/deploy-run-service.ts
-var TERMINAL_STATUSES2 = new Set([
-  "DeploymentSucceeded",
-  "DeploymentFailed",
-  "ValidationFailed",
-  "ConflictFixingError",
-  "DeploymentScheduleError"
-]);
 var PROCESS_RESOURCE_MAPPING_ERROR = /(?:AgentProcessResource|FlowProcessResource)\s*->\s*ReleaseDto/;
 var PROCESS_KEY_MAPPING_ERROR = /Destination Member:\s*ProcessKey|Invalid argument 'Key'/;
 function buildDeploymentFailureInstructions(instructions, pipelineDeploymentId) {
@@ -7865,7 +7797,13 @@ async function deployRunAsync(options) {
   }
   let feedScope = { kind: "tenant" };
   if (options.personalWorkspace || options.feed !== undefined) {
-    const [scopeError, scope] = await catchError(resolveFeedScope({
+    if (options.personalWorkspace) {
+      const refusal = refuseFeedForSession(auth, "Deploying into a Personal Workspace");
+      if (refusal) {
+        return refusal;
+      }
+    }
+    const [scopeError, scope2] = await catchError(resolveFeedScope({
       personalWorkspace: options.personalWorkspace,
       feed: options.feed,
       tenant: options.tenant,
@@ -7875,27 +7813,47 @@ async function deployRunAsync(options) {
     if (scopeError) {
       return fail3(options.feed !== undefined ? "feed_resolution_failed" : "personal_workspace_deploy_failed", scopeError.message, "List the feeds you can deploy from with: uip solution feeds list.");
     }
-    feedScope = scope;
+    feedScope = scope2;
+    if (feedScope.kind !== "tenant") {
+      const refusal = refuseFeedForSession(auth, `Deploying into the feed '${feedScope.name ?? feedScope.folderKey}'`);
+      if (refusal) {
+        return refusal;
+      }
+    }
   }
-  const blocked = await guardExistingDeployment(auth, options, feedScope);
+  const blocked = adviseForApplication(auth, await guardExistingDeployment(auth, options, feedScope)) ?? adviseForApplication(auth, await guardPendingDraft(auth, options, feedScope));
   if (blocked) {
     return blocked;
   }
+  let parentFolderPath;
   if (feedScope.kind !== "tenant") {
-    return deployRunViaFeedAsync(auth, feedScope, options);
-  }
-  const [folderError, parentFolderPath] = await catchError(resolveParentFolder({
-    folderPath: options.parentFolderPath,
-    folderKey: options.parentFolderKey,
-    personalWorkspace: options.personalWorkspace,
-    tenant: options.tenant,
-    loginValidity: options.loginValidity,
-    envFilePath: options.envFilePath
-  }));
-  if (folderError) {
-    return fail3("folder_resolution_failed", folderError.message, "Provide a valid --parent-folder-path, --parent-folder-key, or --personal-workspace.");
+    const [locationError, location] = await catchError(resolveFeedDeployLocation(feedScope, options));
+    if (locationError) {
+      return fail3("location_outside_feed", locationError.message, "Pass a --parent-folder-path / --parent-folder-key inside the feed folder, or omit it to deploy into the feed folder itself.");
+    }
+    parentFolderPath = location.folderFQN || undefined;
+  } else {
+    const [folderError, resolved] = await catchError(resolveParentFolder({
+      folderPath: options.parentFolderPath,
+      folderKey: options.parentFolderKey,
+      personalWorkspace: options.personalWorkspace,
+      tenant: options.tenant,
+      loginValidity: options.loginValidity,
+      envFilePath: options.envFilePath
+    }));
+    if (folderError) {
+      return fail3("folder_resolution_failed", folderError.message, "Provide a valid --parent-folder-path, --parent-folder-key, or --personal-workspace.");
+    }
+    parentFolderPath = resolved;
   }
-  const configuration = new Configuration({
+  const scope = feedScopeInitOverride(feedScope);
+  const feedFields = feedScope.kind === "tenant" ? { feedKind: feedScope.kind } : {
+    feedKind: feedScope.kind,
+    deploymentName: options.deploymentName,
+    packageName: options.packageName,
+    packageVersion: options.packageVersion
+  };
+  const configuration = new Configuration2({
     basePath: auth.basePath,
     accessToken: auth.accessToken
   });
@@ -7924,43 +7882,33 @@ async function deployRunAsync(options) {
     solutionRootFolderName: options.folderName,
     folderFullyQualifiedName: parentFolderPath,
     body: configBody
-  }));
-  if (installError) {
-    const { message, details } = await extractErrorDetails(installError);
-    return fail3("install_request_failed", message, `Check package name/version with: uip solution packages list. Details: ${details}`);
+  }, scope));
+  if (installError || !installResult?.pipelineDeploymentId) {
+    if (!installError) {
+      return fail3(installFailureReason(feedScope), "The install request returned no pipeline deployment.", installFailureHint(feedScope, options));
+    }
+    const detail = await extractErrorDetails(installError);
+    if (hasServerErrorCode(detail.details, DRAFT_VERSION_MISMATCH_CODE)) {
+      return fail3("pending_draft", detail.message, `${pendingDraftHint(feedScope, options)} Details: ${detail.details}`, { errorCode: detail.errorCode, retry: detail.retry });
+    }
+    return fail3(installFailureReason(feedScope), detail.message, `${installFailureHint(feedScope, options)} Details: ${detail.details}`, { errorCode: detail.errorCode, retry: detail.retry });
   }
   const pipelineDeploymentId = installResult.pipelineDeploymentId;
-  const pollResult = await pollUntil({
-    fn: async () => {
-      try {
-        return await api.pipelinesGetPipelineDeploymentStatus({
-          pipelineDeploymentId
-        });
-      } catch (err) {
-        if (!await isPipelineDeploymentNotFoundError(err)) {
-          throw err;
-        }
-        const deployment = await findDeploymentBestEffort(auth, options.deploymentName);
-        const synthesized = deployment ? deploymentToTerminalPipelineResult(deployment) : undefined;
-        if (!synthesized) {
-          throw err;
-        }
-        return synthesized;
-      }
-    },
-    until: (result) => TERMINAL_STATUSES2.has(result.status),
-    getStatus: (result) => result.status,
-    label: `deployment ${pipelineDeploymentId}`,
-    logPrefix: "deploy",
+  const pollResult = await pollPipelineDeploymentAsync(api, auth, {
+    pipelineDeploymentId,
+    deploymentName: options.deploymentName,
+    scope,
     timeoutMs: (options.timeout ?? 360) * 1000,
     intervalMs: options.pollInterval ?? 5000,
-    signal: options.signal
+    signal: options.signal,
+    logPrefix: "deploy"
   });
   const folderPath = parentFolderPath ? `${parentFolderPath}/${options.folderName}` : options.folderName;
   if (pollResult.outcome !== PollOutcome.Completed || !pollResult.data) {
-    const recoveryDeployment = await findDeploymentBestEffort(auth, options.deploymentName);
+    const recoveryKey = pollResult.data?.deploymentKey || undefined;
+    const recoveryDeployment = recoveryKey ? await findDeploymentBestEffort(auth, options.deploymentName, scope, { deploymentKey: recoveryKey }) : undefined;
     const recovery = interpretFailedDeployPoll(recoveryDeployment);
-    if (recovery?.kind === "Active") {
+    const recoveredSuccess = async () => {
       const resolvedFolder2 = await resolveInstalledFolder(recoveryDeployment, {
         folderName: options.folderName,
         folderPath,
@@ -7968,45 +7916,64 @@ async function deployRunAsync(options) {
       }, makeFolderKeyResolver(options));
       return {
         ok: true,
+        ...feedFields,
         status: "DeploymentSucceeded",
-        deploymentKey: recoveryDeployment?.installDeploymentKey ?? recoveryDeployment?.key,
+        deploymentKey: recoveryDeployment?.key,
         pipelineDeploymentId,
-        instanceId: recovery.instanceId == null ? undefined : recovery.instanceId,
+        instanceId: recoveryDeployment?.instanceId == null ? undefined : recoveryDeployment.instanceId,
         folderName: resolvedFolder2.folderName,
         folderPath: resolvedFolder2.folderPath,
-        ...resolvedFolder2.requestedMatched ? {} : { requestedFolderName: options.folderName },
+        ...resolvedFolder2.requestedMatched ? {} : { requestedFolderName: options.folderName }
+      };
+    };
+    if (recovery?.kind === "Active") {
+      return {
+        ...await recoveredSuccess(),
         activationStatus: "SuccessfulActivate"
       };
     }
-    if (recovery?.kind === "NeedsSetupToActivate") {
-      return fail3("needs_setup_to_activate", `Deployment '${options.deploymentName}' completed, but activation requires manual configuration.`, `One or more deployed resources need to be configured before activation (commonly Integration Service connections, credentials, or other tenant-specific setup). Open the deployment in Orchestrator, configure the resources flagged "Needs Setup", then activate with: uip solution deploy activate ${options.deploymentName}.`, { pipelineDeploymentId });
-    }
-    if (recovery?.kind === "ReadyToActivate") {
-      return fail3("ready_to_activate", `Deployment '${options.deploymentName}' completed and is ready to activate.`, `Activation did not complete automatically. Activate now with: uip solution deploy activate ${options.deploymentName}.`, { pipelineDeploymentId });
+    if (recoveryDeployment && (recovery?.kind === "NeedsSetupToActivate" || recovery?.kind === "ReadyToActivate")) {
+      return {
+        ...await recoveredSuccess(),
+        ...await describeInstalledNotLiveAsync(auth, recoveryDeployment, scope, feedScope)
+      };
     }
     if (recovery?.kind === "ActivationFailed") {
       return fail3("activation_failed_post_deploy", `Deployment '${options.deploymentName}' completed but activation failed.`, `Inspect activation details in Orchestrator, then retry with: uip solution deploy activate ${options.deploymentName}.`, { pipelineDeploymentId });
     }
     if (recovery?.kind === "DeployFailed") {
-      return fail3("deploy_failed", `Deployment '${options.deploymentName}' failed (OperationStatus: ${recovery.operationStatus}).`, `Inspect failure details with: uip solution deploy status ${pipelineDeploymentId}. Fix the underlying issue and retry: uip solution deploy run.`, { pipelineDeploymentId });
+      const reason2 = recoveryDeployment ? await describeDeploymentFailureAsync(auth, recoveryDeployment, SolutionDeploymentAction.Install, scope, options.signal) : NO_SERVER_REASON;
+      return fail3("deploy_failed", `Deployment '${options.deploymentName}' failed (OperationStatus: ${recovery.operationStatus}): ${reason2}`, `${inspectHint(pipelineDeploymentId, feedScope)} Fix the underlying issue and retry: uip solution deploy run.`, { pipelineDeploymentId });
     }
     const { reason, message, exitCode, errorCode, retry } = mapPollFailure(pollResult, "Deployment");
-    return fail3(reason, message, `Deployment may still be in progress. Check status with: uip solution deploy status ${pipelineDeploymentId}.`, { exitCode, pipelineDeploymentId, errorCode, retry });
+    return fail3(reason, message, `Deployment may still be in progress. ${followHint(pipelineDeploymentId, feedScope)}`, { exitCode, pipelineDeploymentId, errorCode, retry });
   }
   const finalStatus = pollResult.data;
   if (!finalStatus) {
-    return fail3("no_final_status", "Deployment did not return a final status.", `Check status with: uip solution deploy status ${pipelineDeploymentId}.`, { pipelineDeploymentId });
-  }
-  if (finalStatus.status !== "DeploymentSucceeded") {
-    return fail3("deploy_failed", `Deployment failed with status: ${finalStatus.status}`, buildDeploymentFailureInstructions(formatDeploymentFailureDetails(pipelineDeploymentId, finalStatus), pipelineDeploymentId), { pipelineDeploymentId });
-  }
-  const resolvedFolder = await resolveInstalledFolder(await findDeploymentBestEffort(auth, options.deploymentName), {
+    return fail3("no_final_status", "Deployment did not return a final status.", followHint(pipelineDeploymentId, feedScope), { pipelineDeploymentId });
+  }
+  const landedDespiteStatus = installLandedDespiteStatus(finalStatus);
+  if (finalStatus.status !== "DeploymentSucceeded" && !landedDespiteStatus) {
+    const classification = finalStatus.status === "ValidationFailed" || finalStatus.status === "ConflictFixingError" ? {
+      errorCode: "invalid_argument",
+      retry: "RetryWillNotFix"
+    } : {};
+    const fromPipeline = formatDeploymentFailureDetails(pipelineDeploymentId, finalStatus);
+    const details = finalStatus.synthesizedOperation !== undefined && finalStatus.deploymentKey ? await describeSynthesizedFailureAsync(auth, finalStatus.deploymentKey, scope, options.signal, fromPipeline) : fromPipeline;
+    const draftNote = leavesPendingDraft(finalStatus.status) ? `
+Nothing was installed. The rejected attempt is kept as a pending draft${finalStatus.deploymentKey ? ` (${finalStatus.deploymentKey})` : ""}: fix the configuration and re-run this command, and the server re-validates that draft with the new file (settings and resource links the file does not name keep the values the draft was rejected with).${finalStatus.deploymentKey ? ` When this was an update of an existing deployment, you can discard the draft and upgrade the live version instead: uip solution deploy upgrade ${finalStatus.deploymentKey} --discard-draft --version ${options.packageVersion}` : ""}` : "";
+    return fail3("deploy_failed", `Deployment failed with status: ${finalStatus.status}`, `${buildDeploymentFailureInstructions(details, pipelineDeploymentId)}${draftNote}`, { pipelineDeploymentId, ...classification });
+  }
+  const resolvedFolder = await resolveInstalledFolder(await findDeploymentBestEffort(auth, options.deploymentName, scope, {
+    deploymentKey: finalStatus.deploymentKey || undefined
+  }), {
     folderName: options.folderName,
     folderPath,
     parentFolderPath
   }, makeFolderKeyResolver(options));
   const baseSuccess = {
     ok: true,
+    ...feedFields,
     status: finalStatus.status,
     deploymentKey: finalStatus.deploymentKey,
     pipelineDeploymentId,
@@ -8015,21 +7982,44 @@ async function deployRunAsync(options) {
     folderPath: resolvedFolder.folderPath,
     ...resolvedFolder.requestedMatched ? {} : { requestedFolderName: options.folderName }
   };
+  if (landedDespiteStatus) {
+    const described = await describeInstalledRunAsync(auth, options.deploymentName, finalStatus, scope, feedScope);
+    return {
+      ...baseSuccess,
+      ...described,
+      nextSteps: [
+        explainPipelineStatusAfterInstall(finalStatus),
+        ...described.nextSteps ?? []
+      ]
+    };
+  }
   if (options.skipActivate) {
     return { ...baseSuccess, activationStatus: "Skipped" };
   }
   const activationResult = await activateDeployment(auth, options.deploymentName, {
     timeoutSeconds: options.timeout ?? 360,
     pollIntervalMs: options.pollInterval ?? 5000,
-    signal: options.signal
+    signal: options.signal,
+    scope
   });
   if (activationResult.kind === "RequestFailed") {
+    const refused = activationResult.deployment;
+    if (refused && refused.key === finalStatus.deploymentKey && refused.operationStatus === "Successful" && refused.activationStatus === "NeedsSetupToActivate") {
+      return {
+        ...baseSuccess,
+        ...await describeInstalledNotLiveAsync(auth, refused, scope, feedScope)
+      };
+    }
     const fallback = activationResult.phase === "preActivateSteps" ? `Deployment '${options.deploymentName}' was deployed successfully but pre-activate steps lookup failed. Retry activation with: uip solution deploy activate ${options.deploymentName}. Details: ${activationResult.details}` : `Deployment '${options.deploymentName}' was deployed successfully but activation failed. Retry activation with: uip solution deploy activate ${options.deploymentName}. Details: ${activationResult.details}`;
-    return fail3("activation_request_failed", activationResult.message, appendDraftDeploymentInstructions(fallback, activationResult.deployment), { pipelineDeploymentId });
+    const pendingResources = refused && needsPendingResources(refused) ? await readPendingResourcesAsync(new DeploymentsApi(new Configuration({
+      basePath: auth.basePath,
+      accessToken: auth.accessToken
+    })), refused.key, scope) : undefined;
+    return fail3("activation_request_failed", activationResult.message, appendDeploymentStateInstructions(fallback, refused, pendingResources, feedSelectorFlag(feedScope)), { pipelineDeploymentId });
   }
   if (activationResult.kind === "PollFailed") {
     const { message, exitCode, errorCode, retry } = mapPollFailure(activationResult.poll, "Activation");
-    return fail3("activation_poll_failed", message, `Deployment '${options.deploymentName}' was deployed successfully but activation polling did not complete. Activation may still be in progress; check with: uip solution deploy list.`, { exitCode, pipelineDeploymentId, errorCode, retry });
+    return fail3("activation_poll_failed", message, `Deployment '${options.deploymentName}' was deployed successfully but activation polling did not complete. Activation may still be in progress; check with: ${listCommand(feedScope)}.`, { exitCode, pipelineDeploymentId, errorCode, retry });
   }
   if (activationResult.kind === "ActivationFailed") {
     return fail3("activation_failed", `Activation failed with status: ${activationResult.status}`, activationResult.errorMessage, { pipelineDeploymentId });
@@ -8039,22 +8029,115 @@ async function deployRunAsync(options) {
   const finalInstanceId = activationInstanceId == null ? baseSuccess.instanceId : activationInstanceId;
   return { ...baseSuccess, activationStatus, instanceId: finalInstanceId };
 }
-var EXISTING_DEPLOYMENT_MARKER = "Deployment exists in a failed or running state";
-function isExistingDeploymentConflict(httpStatus, message, details, parsedErrors) {
-  if (httpStatus !== 400) {
-    return false;
+async function describeInstalledRunAsync(auth, deploymentName, finalStatus, scope, feedScope) {
+  const key = finalStatus.deploymentKey || undefined;
+  const row = key ? await findDeploymentBestEffort(auth, deploymentName, scope, {
+    deploymentKey: key
+  }) : undefined;
+  if (row) {
+    return describeInstalledNotLiveAsync(auth, row, scope, feedScope);
+  }
+  const record = finalStatus.deploymentResult;
+  if (record?.status === "SuccessfulActivate") {
+    return { activationStatus: "SuccessfulActivate" };
+  }
+  const actions = record?.actions ?? [];
+  const activationStatus = actions.includes("SetupActivation") ? "NeedsSetupToActivate" : actions.includes("Activate") ? "ReadyToActivate" : "Inactive";
+  return describeInstalledNotLiveAsync(auth, {
+    name: deploymentName,
+    key,
+    operation: record?.operation ?? finalStatus.synthesizedOperation,
+    operationStatus: "Successful",
+    activationStatus,
+    packageVersion: record?.packageVersion,
+    currentPackageVersion: record?.packageVersion
+  }, scope, feedScope);
+}
+async function describeInstalledNotLiveAsync(auth, deployment, scope, feedScope) {
+  const pendingResources = needsPendingResources(deployment) && deployment.key ? await readPendingResourcesAsync(new DeploymentsApi(new Configuration({
+    basePath: auth.basePath,
+    accessToken: auth.accessToken
+  })), deployment.key, scope) : undefined;
+  const nextSteps = deploymentNextSteps(deployment, pendingResources, feedSelectorFlag(feedScope));
+  return {
+    activationStatus: deployment.activationStatus ?? "Inactive",
+    ...pendingResources ? { pendingResources } : {},
+    ...nextSteps && nextSteps.length > 0 ? { nextSteps } : {}
+  };
+}
+function inspectHint(pipelineDeploymentId, scope) {
+  if (scope.kind === "tenant") {
+    return `Inspect failure details with: uip solution deploy status ${pipelineDeploymentId}.`;
   }
-  if (message.includes(EXISTING_DEPLOYMENT_MARKER) || details.includes(EXISTING_DEPLOYMENT_MARKER)) {
-    return true;
+  return `Inspect it with: ${listCommand(scope)}.`;
+}
+function followHint(pipelineDeploymentId, scope) {
+  if (scope.kind === "tenant") {
+    return `Check status with: uip solution deploy status ${pipelineDeploymentId}.`;
   }
-  if (parsedErrors) {
-    for (const fieldMessages of Object.values(parsedErrors)) {
-      if (fieldMessages.some((m) => m.includes(EXISTING_DEPLOYMENT_MARKER))) {
-        return true;
-      }
-    }
+  return `Check it with: ${listCommand(scope)}.`;
+}
+function listCommand(scope) {
+  if (scope.kind === "personal") {
+    return "uip solution deploy list --personal-workspace";
   }
-  return false;
+  if (scope.kind === "folder") {
+    return `uip solution deploy list --feed ${scope.folderKey ?? "<name-or-key>"}`;
+  }
+  return "uip solution deploy list";
+}
+function adviseForApplication(auth, failure) {
+  if (!failure || classifyFeedSession(auth) !== "application") {
+    return failure;
+  }
+  logger.warn(`${failure.message} Deploying anyway: under an external app (client-credentials) login this check only warns, so a pipeline keeps the outcome it had before the check could run. ${failure.instructions}`);
+  return;
+}
+function refuseFeedForSession(session, action) {
+  const verdict = classifyFeedSession(session);
+  if (verdict === "user") {
+    return;
+  }
+  const { message, instructions } = feedSessionRefusal(verdict, action, "deploy the package to the tenant feed");
+  return fail3("feed_requires_user_session", message, instructions, {
+    errorCode: "permission_denied",
+    retry: "RetryWillNotFix"
+  });
+}
+async function describeSynthesizedFailureAsync(auth, deploymentKey, scope, signal, fromPipeline) {
+  const deploymentsApi = new DeploymentsApi(new Configuration({
+    basePath: auth.basePath,
+    accessToken: auth.accessToken
+  }));
+  const reason = await describeValidationFailureAsync(deploymentsApi, deploymentKey, SolutionDeploymentAction.Install, scope, signal);
+  return reason === NO_SERVER_REASON ? fromPipeline : `Validation: ${reason}
+${fromPipeline}`;
+}
+function pendingDraftHint(scope, options) {
+  const cause = `'${options.deploymentName}' has a pending draft for another version: an earlier attempt that never completed, usually one rejected by validation. To retry that draft with a corrected configuration, re-run this command with the draft's --package-version (the message names it).`;
+  if (scope.kind === "folder") {
+    return `${cause} To discard it and upgrade the live deployment to ${options.packageVersion} instead: uip solution deploy upgrade <deployment-key> --discard-draft --version ${options.packageVersion} (Key from ${listCommand(scope)}).`;
+  }
+  const workspace = scope.kind === "personal" ? " --personal-workspace" : "";
+  return `${cause} To discard it and upgrade the live deployment to ${options.packageVersion} instead: uip solution deploy upgrade --name ${options.deploymentName} --package-name ${options.packageName}${workspace} --discard-draft --version ${options.packageVersion} (under an external app, pass the deployment's key in place of --name and --package-name).`;
+}
+function installFailureReason(scope) {
+  if (scope.kind === "personal") {
+    return "personal_workspace_deploy_failed";
+  }
+  if (scope.kind === "folder") {
+    return "feed_deploy_failed";
+  }
+  return "install_request_failed";
+}
+function installFailureHint(scope, options) {
+  if (scope.kind === "personal") {
+    return "Ensure the package was published to your Personal Workspace first: uip solution publish <package> --personal-workspace.";
+  }
+  if (scope.kind === "folder") {
+    return `Ensure the package was published to the feed first: uip solution publish <package> --feed ${options.feed ?? "<name-or-key>"}.`;
+  }
+  return "Check package name/version with: uip solution packages list.";
 }
 function scopeLabel(scope) {
   if (scope.kind === "personal") {
@@ -8084,7 +8167,7 @@ function buildDeploymentExistsInstructions(options) {
     }
   }
   parts.push("To see every deployment and its state, run: uip solution deploy list.");
-  parts.push(scope.kind === "tenant" ? "To create a second, separate deployment anyway, re-run this command with --yes." : "To create a second, separate deployment anyway, re-run with --yes — Orchestrator may still refuse it while the existing deployment is running or in a failed state.");
+  parts.push(scope.kind === "tenant" ? "To create a second, separate deployment anyway, re-run this command with --yes and a different --name: re-using an existing deployment's name updates that deployment in place instead." : "To create a second, separate deployment anyway, re-run with --yes and a different --name (re-using an existing deployment's name updates that deployment in place) — Orchestrator may still refuse it while the existing deployment is running or in a failed state.");
   if (existing.length === 0) {
     parts.unshift(`A deployment of '${packageName}' already exists in ${scopeLabel(scope)}.`);
   } else if (options.includeInventory) {
@@ -8107,6 +8190,31 @@ async function resolveDeploymentFolders(deployments, options) {
   }));
   return resolved;
 }
+async function guardPendingDraft(auth, options, scope) {
+  const [lookupError, rows] = await catchError(findDeploymentsByName(auth, options.deploymentName, feedScopeInitOverride(scope)));
+  if (lookupError instanceof DeploymentSearchNeedsUserSessionError || lookupError && classifyFeedSession(auth) === "application" && isAuthRefusal(lookupError)) {
+    return;
+  }
+  if (lookupError) {
+    logger.warn(`Skipped the pending-draft check for '${options.deploymentName}': the deployment lookup failed (${lookupError.message}). Deploying anyway — if this deployment has a pending draft for another version, the server may install that draft's version instead of ${options.packageVersion}. Check it with 'uip solution deploy list'.`);
+    return;
+  }
+  const draft = newestDeploymentRow(rows);
+  if (draft?.operationStatus !== "Draft") {
+    return;
+  }
+  const draftVersion = draft.targetPackageVersion ?? draft.packageVersion;
+  if (draft.operation === "ActivationSetup") {
+    return fail3("pending_draft", `Deployment '${options.deploymentName}' has an unfinished Setup activation (${draft.key}): the Orchestrator "Setup activation" wizard was started on version ${draftVersion ?? "<version>"} and not completed.`, `While that draft exists the server would run it in place of this deploy, or refuse a different version. Finish the setup in Orchestrator (Solutions, the deployment, Setup activation); or discard it — in Orchestrator (Delete draft), or with uip solution deploy upgrade ${draft.key} --discard-draft${draft.currentPackageVersion ? ` --version ${draft.currentPackageVersion}` : ""} — then re-run this command.`, { errorCode: "invalid_argument", retry: "RetryWillNotFix" });
+  }
+  if (!draftVersion || draftVersion.toLowerCase() === options.packageVersion.toLowerCase()) {
+    return;
+  }
+  const liveVersion = draft.currentPackageVersion;
+  const discard = draft.operation === "Install" || !liveVersion ? "delete it in Orchestrator (Delete draft)" : `discard it — in Orchestrator (Delete draft), or with uip solution deploy upgrade ${draft.key} --discard-draft --version ${liveVersion}, which also re-applies the live version unchanged —`;
+  return fail3("pending_draft", `Deployment '${options.deploymentName}' has a pending draft (${draft.key}) for version ${draftVersion}: an earlier attempt that never completed, usually one rejected by validation, or one still running.`, `The server reuses that draft for the name, so this request would not deploy ${options.packageVersion}: asking for the live version installs the draft's ${draftVersion} instead, and any other version is refused. To retry the draft with a corrected configuration, re-run with --package-version ${draftVersion}.
+To deploy ${options.packageVersion} instead, ${discard} then re-run this command.`, { errorCode: "invalid_argument", retry: "RetryWillNotFix" });
+}
 async function guardExistingDeployment(auth, options, scope) {
   if (options.yes) {
     return;
@@ -8114,8 +8222,12 @@ async function guardExistingDeployment(auth, options, scope) {
   const [lookupError, deployments] = await catchError(findDeploymentsByPackageName(auth, options.packageName, {
     scope: feedScopeInitOverride(scope)
   }));
+  if (lookupError instanceof DeploymentSearchNeedsUserSessionError) {
+    logger.warn(`Skipped the already-deployed check for '${options.packageName}': this server's deployment search reads user sessions only, and this is an application (client-credentials) login. Deploying anyway — if a deployment already exists this creates a second one in its own folder. Check what is already deployed in the Orchestrator Solutions UI, or sign in with 'uip login' and re-run.`);
+    return;
+  }
   if (lookupError) {
-    logger.warn(`Skipped the already-deployed check for '${options.packageName}': the deployment lookup failed (${lookupError.message}). Deploying anyway — if a deployment already exists this creates a second one in its own folder. The lookup needs a user session; an application (client-credentials) login cannot read it, and 'uip solution deploy list' reads the same service so it fails the same way. Check what is already deployed in the Orchestrator Solutions UI, or sign in with 'uip login' and re-run.`);
+    logger.warn(`Skipped the already-deployed check for '${options.packageName}': the deployment lookup failed (${lookupError.message}). Deploying anyway — if a deployment already exists this creates a second one in its own folder. 'uip solution deploy list' reads the same search, so it may fail the same way. Check what is already deployed in the Orchestrator Solutions UI, or re-run once the lookup answers.`);
     return;
   }
   const existing = deployments.filter(blocksRedeploy);
@@ -8129,85 +8241,6 @@ async function guardExistingDeployment(auth, options, scope) {
     requestedDeploymentName: options.deploymentName
   }));
 }
-async function deployRunViaFeedAsync(auth, scope, options) {
-  const [locationError, location] = await catchError(resolveFeedDeployLocation(scope, options));
-  if (locationError) {
-    return fail3("location_outside_feed", locationError.message, "Pass a --parent-folder-path / --parent-folder-key inside the feed folder, or omit it to deploy into the feed folder itself.");
-  }
-  const isPersonal = scope.kind === "personal";
-  const [deployError, result] = await catchError(deployToFeed(auth, {
-    feedFolderKey: scope.folderKey,
-    locationFolderKey: location.folderKey,
-    locationFQN: location.folderFQN
-  }, {
-    packageName: options.packageName,
-    packageVersion: options.packageVersion,
-    deploymentName: options.deploymentName,
-    solutionRootFolderName: options.folderName,
-    skipActivate: options.skipActivate
-  }));
-  if (deployError) {
-    const { message, details, context, parsedErrors } = await extractErrorDetails(deployError);
-    if (isExistingDeploymentConflict(context?.httpStatus, message, details, parsedErrors)) {
-      const [, blockers] = await catchError(findDeploymentsByPackageName(auth, options.packageName, {
-        scope: feedScopeInitOverride(scope)
-      }));
-      return fail3("deployment_exists", message, buildDeploymentExistsInstructions({
-        packageName: options.packageName,
-        scope,
-        existing: blockers ?? [],
-        requestedDeploymentName: options.deploymentName,
-        includeInventory: true
-      }));
-    }
-    const publishHint = isPersonal ? "uip solution publish <package> --personal-workspace" : `uip solution publish <package> --feed ${options.feed ?? "<name-or-key>"}`;
-    return fail3(isPersonal ? "personal_workspace_deploy_failed" : "feed_deploy_failed", message, `Ensure the package was published to the target feed first: ${publishHint}. Details: ${details}`);
-  }
-  const target = isPersonal ? "your Personal Workspace" : `feed '${scope.name ?? location.folderFQN}'`;
-  const started = {
-    ok: true,
-    status: "DeploymentStarted",
-    folderName: options.folderName,
-    folderPath: `${result.folderFQN}/${options.folderName}`,
-    activationStatus: options.skipActivate ? "Skipped" : "Auto",
-    deploymentName: result.deploymentName,
-    packageName: result.packageName,
-    packageVersion: result.packageVersion,
-    feedKind: scope.kind,
-    nextSteps: options.skipActivate ? `Deployment created in ${target}. Activate it with: uip solution deploy activate ${result.deploymentName}. Check status with: uip solution deploy list.` : `Deployment created in ${target} and will auto-activate. Check status with: uip solution deploy list.`
-  };
-  if (!options.wait) {
-    return started;
-  }
-  return awaitFeedDeployAsync(auth, scope, options, started, result.deploymentName);
-}
-async function awaitFeedDeployAsync(auth, scope, options, started, deploymentName) {
-  const scopeOverride = feedScopeInitOverride(scope);
-  const pollResult = await pollUntil({
-    fn: () => findDeploymentByName(auth, deploymentName, scopeOverride),
-    until: (deployment2) => isSettledDeployOperationStatus(deployment2?.operationStatus),
-    getStatus: (deployment2) => deployment2?.operationStatus ?? "Unknown",
-    label: `deployment '${deploymentName}'`,
-    logPrefix: "deploy",
-    timeoutMs: (options.timeout ?? 360) * 1000,
-    intervalMs: options.pollInterval ?? 5000,
-    signal: options.signal
-  });
-  if (pollResult.outcome !== PollOutcome.Completed || !pollResult.data) {
-    const { reason, message, exitCode, errorCode, retry } = mapPollFailure(pollResult, "Deployment");
-    return fail3(reason, message, appendDraftDeploymentInstructions(`Deployment '${deploymentName}' may still be in progress. Check it with: uip solution deploy list.`, pollResult.data), { exitCode, errorCode, retry });
-  }
-  const deployment = pollResult.data;
-  if (deployment.operationStatus !== "Successful") {
-    const reason = await describeDeploymentFailureAsync(auth, deployment, SolutionDeploymentAction.Install, scopeOverride, options.signal);
-    return fail3("deploy_failed", `Deployment '${deploymentName}' failed (OperationStatus: ${deployment.operationStatus}): ${reason}`, `Inspect the deployment with: uip solution deploy list, fix the underlying issue, then deploy again.`);
-  }
-  return {
-    ...started,
-    status: "DeploymentSucceeded",
-    nextSteps: options.skipActivate ? started.nextSteps : undefined
-  };
-}
 async function resolveFeedDeployLocation(scope, options) {
   const feedFolder = {
     folderKey: scope.folderKey,
@@ -8234,7 +8267,7 @@ async function resolveFeedDeployLocation(scope, options) {
 }
 
 // src/services/deploy-uninstall-service.ts
-var TERMINAL_STATUSES3 = new Set([
+var TERMINAL_STATUSES2 = new Set([
   "SuccessfulUninstall",
   "FailedUninstall"
 ]);
@@ -8274,10 +8307,11 @@ function buildDeploymentStateInstructions(deployment, details) {
   if (deployment.actions?.includes("Uninstall")) {
     return `Deployment '${deployment.name}' lists uninstall as available but Orchestrator rejected the request ${status}. Run 'uip solution deploy list' to recheck its state, then retry. If it stays stuck, uninstall it from the Orchestrator Solutions UI. Details: ${details}`;
   }
+  const removalAdvice = deployment.actions?.includes(WorkflowAction.Delete) ? `Delete it with: uip solution deploy delete '${deployment.name}' --yes.` : "Remove it from the Orchestrator Solutions UI.";
   if (deployment.activationStatus === "Inactive") {
-    return `Deployment '${deployment.name}' cannot be uninstalled in its current state ${status}. Available actions: ${availableActions}. Superseded or inactive deployments cannot be uninstalled from the CLI — remove them from the Orchestrator Solutions UI. Run 'uip solution deploy list' to see the current deployments. Details: ${details}`;
+    return `Deployment '${deployment.name}' cannot be uninstalled in its current state ${status}. Available actions: ${availableActions}. Superseded or inactive deployments are never uninstallable. ${removalAdvice} Details: ${details}`;
   }
-  return `Deployment '${deployment.name}' cannot be uninstalled in its current state ${status}. Available actions: ${availableActions}. Run 'uip solution deploy list' to recheck its state, or remove it from the Orchestrator Solutions UI. Details: ${details}`;
+  return `Deployment '${deployment.name}' cannot be uninstalled in its current state ${status}. Available actions: ${availableActions}. Run 'uip solution deploy list' to recheck its state. ${removalAdvice} Details: ${details}`;
 }
 async function waitForOperationToFinishAsync(auth, deploymentName, opts) {
   let last;
@@ -8297,9 +8331,10 @@ async function waitForOperationToFinishAsync(auth, deploymentName, opts) {
   return { outcome: poll.outcome, state: last, error: poll.error };
 }
 async function requestUninstallAsync(api, auth, deploymentName, ctx) {
-  const { options, location, intervalMs, remainingMs } = ctx;
+  const { options, sweep, intervalMs, remainingMs } = ctx;
+  const { location } = sweep;
+  const sweepIncomplete = !location && !sweep.complete;
   let state = location?.deployment;
-  let stateUnknown = ctx.lookupError !== undefined;
   let waited = false;
   let rechecked = false;
   for (;; ) {
@@ -8307,8 +8342,11 @@ async function requestUninstallAsync(api, auth, deploymentName, ctx) {
     if (!uninstallError) {
       return { ok: true, result };
     }
-    const { message, details, errorCode, retry } = await extractErrorDetails(uninstallError);
+    const { message, details, errorCode, retry, context } = await extractErrorDetails(uninstallError);
     if (errorCode !== "invalid_argument") {
+      if (errorCode === "not_found" && sweepIncomplete) {
+        return incompleteSweepFailureAsync(deploymentName, sweep, details);
+      }
       return fail4("uninstall_request_failed", message, requestErrorInstructions(deploymentName, errorCode, details), { errorCode, retry });
     }
     if (!rechecked && !waited && state?.operationStatus !== "InProgress") {
@@ -8316,7 +8354,6 @@ async function requestUninstallAsync(api, auth, deploymentName, ctx) {
       const [readError, fresh] = await catchError(findDeploymentByName(auth, deploymentName, location?.scope));
       if (!readError) {
         state = fresh;
-        stateUnknown = false;
       }
     }
     if (!waited && state?.operationStatus === "InProgress") {
@@ -8341,23 +8378,25 @@ async function requestUninstallAsync(api, auth, deploymentName, ctx) {
         return fail4(reason, pollMessage, `The deployment may still be installing. Check it with: uip solution deploy list, then retry the uninstall.`, { exitCode, errorCode: pollErrorCode, retry: pollRetry });
       }
       state = wait.state;
-      stateUnknown = false;
       continue;
     }
-    let instructions;
-    if (stateUnknown) {
-      instructions = `Check the deployment name matches an existing deployment (run 'uip solution deploy list'). Details: ${details}`;
-    } else if (state) {
-      instructions = buildDeploymentStateInstructions(state, details);
-    } else {
-      instructions = `No deployment named '${deploymentName}' was found in any feed you can reach (tenant, Personal Workspace, or a folder feed). Check the name with 'uip solution deploy list'. Details: ${details}`;
+    if (sweepIncomplete && (!state || isCompletedUninstall(state))) {
+      if (isNameOrFeedRefusal(errorCode, context?.httpStatus)) {
+        return incompleteSweepFailureAsync(deploymentName, sweep, details);
+      }
+      return fail4("uninstall_request_failed", message, requestErrorInstructions(deploymentName, errorCode, details), { errorCode, retry });
     }
+    const instructions = state ? buildDeploymentStateInstructions(state, details) : `No deployment named '${deploymentName}' was found in any feed you can reach (tenant, Personal Workspace, or a folder feed). Check the name with 'uip solution deploy list'. Details: ${details}`;
     return fail4("uninstall_request_failed", message, instructions, {
       errorCode,
       retry
     });
   }
 }
+async function incompleteSweepFailureAsync(deploymentName, sweep, refusalDetails) {
+  const report = await reportIncompleteSweepAsync(deploymentName, sweep.skipped);
+  return fail4("uninstall_request_failed", report.message, `${INCOMPLETE_SWEEP_ADVICE} Without its feed the uninstall request went to the tenant feed, which refused it. ${report.nextStep} Details: ${refusalDetails} (feed search: ${report.details})`, { errorCode: report.errorCode, retry: report.retry });
+}
 async function uninstallDeploymentAsync(deploymentName, options = {}) {
   const [authError, auth] = await catchError(getSolutionAuthContext({
     tenant: options.tenant,
@@ -8367,18 +8406,18 @@ async function uninstallDeploymentAsync(deploymentName, options = {}) {
   if (authError) {
     return fail4("auth_failed", authError.message, authError.message);
   }
-  const api = new PipelinesApi(new Configuration({
+  const api = new PipelinesApi(new Configuration2({
     basePath: auth.basePath,
     accessToken: auth.accessToken
   }));
   const deadline = Date.now() + (options.timeout ?? 360) * 1000;
   const intervalMs = options.pollInterval ?? 5000;
   const remainingMs = () => Math.max(deadline - Date.now(), 1);
-  const [lookupError, location] = await catchError(findDeploymentAcrossFeeds(auth, deploymentName, options));
+  const sweep = await findDeploymentAcrossFeeds(auth, deploymentName, options);
+  const location = sweep.location;
   const [requestError, requested] = await catchError(requestUninstallAsync(api, auth, deploymentName, {
     options,
-    location,
-    lookupError,
+    sweep,
     intervalMs,
     remainingMs
   }));
@@ -8407,7 +8446,7 @@ async function uninstallDeploymentAsync(deploymentName, options = {}) {
   }
   const pollResult = await pollUntil({
     fn: () => api.pipelinesGetDeploymentInstanceStatus({ instanceId }, location?.scope),
-    until: (result) => TERMINAL_STATUSES3.has(result.status),
+    until: (result) => TERMINAL_STATUSES2.has(result.status),
     getStatus: (result) => result.status,
     label: `uninstall ${deploymentName}`,
     logPrefix: "uninstall",
@@ -8426,7 +8465,7 @@ async function uninstallDeploymentAsync(deploymentName, options = {}) {
   const finalStatus = pollResult.data;
   if (finalStatus.status !== "SuccessfulUninstall") {
     const errors2 = coerceWorkflowErrorMessages(finalStatus.errorMessage).map((e) => e.errorMessage).join(", ");
-    return fail4("uninstall_failed", `Uninstall failed with status: ${finalStatus.status}`, errors2 || "Orchestrator ended the uninstall in a FailedUninstall state without an error detail. Run 'uip solution deploy list' to recheck the deployment's state and retry. If it stays in a failed state, remove it from the Orchestrator Solutions UI.");
+    return fail4("uninstall_failed", `Uninstall failed with status: ${finalStatus.status}`, errors2 || `Orchestrator ended the uninstall in a FailedUninstall state without an error detail. Run 'uip solution deploy list' to recheck the deployment's state and retry. If it stays in a failed state and that listing shows Delete among its actions, remove the record with: uip solution deploy delete '${deploymentName}' --yes. Remove it from the Orchestrator Solutions UI when it does not.`);
   }
   return {
     ok: true,
@@ -8437,17 +8476,34 @@ async function uninstallDeploymentAsync(deploymentName, options = {}) {
 }
 
 // src/services/deploy-upgrade-service.ts
-var fail5 = (reason, message, instructions, exitCode = 1) => ({
+var fail5 = (reason, message, instructions, extras = {}) => ({
   ok: false,
   reason,
   message,
   instructions,
-  exitCode
+  exitCode: extras.exitCode ?? 1,
+  errorCode: extras.errorCode,
+  retry: extras.retry
 });
 var DEFAULT_TIMEOUT_SECONDS = 300;
 var DEFAULT_POLL_INTERVAL_MS = 5000;
 var AUTH_INSTRUCTIONS2 = "Run 'uip login' to refresh credentials, then retry. If the deployment is in a different tenant, switch with 'uip login tenant set <tenant>'.";
-async function upgradeDeploymentAsync(deploymentKey, options = {}) {
+var PACKAGE_INSTRUCTIONS = "Confirm the version is published to the tenant (or Personal Workspace) feed: uip solution packages list.";
+var TARGET_INSTRUCTIONS = "Address the deployment either by key — uip solution deploy upgrade <deployment-key> — or by name with its package: uip solution deploy upgrade --name <deployment-name> --package-name <package>. 'uip solution deploy list' reports all three.";
+var DEPLOYMENT_NOT_FOUND_INSTRUCTIONS = "Check the key with 'uip solution deploy list'. A server without the Pipelines deployment lookup answers 404 to every key for an external app; on one of those, address the deployment with --name and --package-name instead.";
+var LOOKUP_FAILED_INSTRUCTIONS = "The deployment lookup failed before any upgrade was requested. Retry, or address the deployment with --name and --package-name.";
+var INVALID_TARGET = {
+  errorCode: "invalid_argument",
+  retry: "RetryWillNotFix"
+};
+var GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UPGRADE_REFUSED_INSTRUCTIONS = "The server refused to start the upgrade. The deployment name may not exist, or may belong to a different package — check both with 'uip solution deploy list'. Another operation may still be running on it (wait, then retry), or it may be in a state the platform does not offer upgrades for.";
+async function upgradeDeploymentAsync(first, second) {
+  const options = typeof first === "string" ? { ...second, deploymentKey: first } : first;
+  const targetError = validateTarget(options);
+  if (targetError) {
+    return targetError;
+  }
   const [authError, auth] = await catchError(getSolutionAuthContext({
     tenant: options.tenant,
     loginValidity: options.loginValidity,
@@ -8456,140 +8512,442 @@ async function upgradeDeploymentAsync(deploymentKey, options = {}) {
   if (authError) {
     return fail5("auth_failed", authError.message, AUTH_INSTRUCTIONS2);
   }
-  const config = new Configuration2({
+  const pipelinesApi = new PipelinesApi(new Configuration2({
     basePath: auth.basePath,
     accessToken: auth.accessToken
-  });
-  const deploymentsApi = new DeploymentsApi(config);
-  const searchApi = new SearchApi(config);
-  let feedScope;
-  if (options.personalWorkspace) {
-    const [pwError, pw] = await catchError(resolvePersonalWorkspace({
-      tenant: options.tenant,
-      loginValidity: options.loginValidity
-    }));
-    if (pwError || !pw) {
-      return fail5("personal_workspace_failed", pwError?.message ?? "Personal Workspace could not be resolved.", "Ensure your user has a Personal Workspace, then retry.");
+  }));
+  const target = options.deploymentKey ? await resolveTargetByKeyAsync(pipelinesApi, auth, options, options.deploymentKey) : await resolveTargetByNameAsync(pipelinesApi, auth, options);
+  if (!target.ok) {
+    return target;
+  }
+  const { deploymentName, packageName, scope } = target;
+  let targetVersion = options.version;
+  if (targetVersion === undefined) {
+    const [versionError, latest] = await catchError(pipelinesApi.pipelinesGetPackageVersion({ packageName, packageVersion: null }, scope));
+    if (versionError || !latest) {
+      const detail = versionError && await extractErrorDetails(versionError);
+      if (!detail || detail.context?.httpStatus === 404) {
+        return fail5("package_not_found", detail?.details ? `Package '${packageName}' was not found in the feed: ${detail.details}` : `Package '${packageName}' was not found in the feed.`, PACKAGE_INSTRUCTIONS, { errorCode: "not_found", retry: "RetryWillNotFix" });
+      }
+      return fail5("lookup_failed", detail.details ? `${detail.message}: ${detail.details}` : detail.message, `The version lookup for '${packageName}' failed before any upgrade was requested. Retry, or pass --version explicitly to skip the lookup.`, { errorCode: detail.errorCode, retry: detail.retry });
     }
-    feedScope = folderKeyInitOverride(pw.key);
-  }
-  const [getError, deployment] = await catchError(deploymentsApi.deploymentsGetByKey({ deploymentKey }, feedScope));
-  if (getError || !deployment) {
-    const detail = getError && await extractErrorDetails(getError);
-    return fail5("deployment_not_found", detail ? detail.details ? `${detail.message}: ${detail.details}` : detail.message : `Deployment '${deploymentKey}' was not found.`, "Run 'uip solution deploy list' to find the deployment key. Add '--personal-workspace' if it lives in your Personal Workspace.");
-  }
-  const upgradeScope = feedScope;
-  const take = 50;
-  let pkg;
-  for (let skip = 0;; ) {
-    const [searchError, packages] = await catchError(searchApi.searchSearchPackages({
-      searchFilter: {
-        searchTerm: deployment.packageName,
-        take,
-        skip
-      }
-    }, feedScope));
-    if (searchError) {
-      const { message, details } = await extractErrorDetails(searchError);
-      return fail5("package_not_found", details ? `${message}: ${details}` : message, "Confirm the package is published to the tenant (or Personal Workspace) feed.");
-    }
-    const values = packages.values ?? [];
-    pkg = values.find((p) => p.name === deployment.packageName);
-    if (pkg || values.length < take) {
-      break;
-    }
-    skip += values.length;
-  }
-  if (!pkg) {
-    return fail5("package_not_found", `Package '${deployment.packageName}' was not found in the feed.`, "Confirm the package is published to the tenant (or Personal Workspace) feed.");
-  }
-  if (options.version && options.version !== pkg.latestVersion) {
-    return fail5("unsupported_version", `Upgrade supports only the latest published version ('${pkg.latestVersion}'); requested '${options.version}'.`, "Publish the desired version as the latest, or omit '--version' to upgrade to the newest.");
-  }
-  const currentVersion = deployment.currentPackageVersion ?? deployment.packageVersion;
-  if (currentVersion === pkg.latestVersion) {
-    return fail5("no_upgrade_available", `Deployment '${deployment.name}' is already at the latest published version (${pkg.latestVersion}).`, "Publish a newer version of the package, then retry.");
-  }
-  const [upgradeError, draft] = await catchError(deploymentsApi.deploymentsUpgrade({
-    deploymentKey,
-    packageVersionKey: pkg.packageVersionKey,
-    deploymentUpgradeRequest: {
-      packageVersionKey: pkg.packageVersionKey
-    }
-  }, upgradeScope));
-  if (upgradeError || !draft) {
-    let message = "The upgrade request returned no deployment.";
-    if (upgradeError) {
-      const detail = await extractErrorDetails(upgradeError);
+    targetVersion = latest.packageVersion;
+  }
+  const [installError, installResult] = await catchError(pipelinesApi.pipelinesInstall({
+    deploymentName,
+    packageName,
+    packageVersion: targetVersion,
+    solutionRootFolderName: deploymentName
+  }, scope));
+  if (installError || !installResult?.pipelineDeploymentId) {
+    let message = "The upgrade request returned no pipeline deployment.";
+    let classification = {};
+    let instructions = UPGRADE_REFUSED_INSTRUCTIONS;
+    if (installError) {
+      const detail = await extractErrorDetails(installError);
       message = detail.details ? `${detail.message}: ${detail.details}` : detail.message;
+      classification = {
+        errorCode: detail.errorCode,
+        retry: detail.retry
+      };
+      if (detail.context?.httpStatus === 404) {
+        instructions = `The server knows no such version of '${packageName}' in this feed. ${PACKAGE_INSTRUCTIONS} 'uip solution deploy list' shows the deployment's package and current version.`;
+      }
+      if (hasServerErrorCode(detail.details, DRAFT_VERSION_MISMATCH_CODE)) {
+        return fail5("pending_draft", message, `'${deploymentName}' has a pending draft for another version: an earlier attempt that never completed, usually one rejected by validation, and the server will not upgrade past it. Discard it and upgrade the live version: ${discardRetryCommand(options, target)}${options.deploymentKey ? "" : `
+Under an external app the name form cannot find the draft; pass the deployment's key instead (InstallDeploymentKey from the original deploy, or Key from 'uip solution deploy list').`}`, INVALID_TARGET);
+      }
     }
-    return fail5("request_failed", message, "The upgrade could not be started. Check the deployment key and that a newer version is published.");
-  }
-  const [runError] = await catchError(deploymentsApi.deploymentsRun({ deploymentKey: draft.key }, upgradeScope));
-  if (runError) {
-    const { message, details } = await extractErrorDetails(runError);
-    return fail5("install_failed", details ? `${message}: ${details}` : message, `The upgrade was queued as deployment '${draft.key}' but installing it failed. Run 'uip solution deploy list' to inspect its state.`);
+    return fail5("request_failed", message, instructions, classification);
   }
+  const pipelineDeploymentId = installResult.pipelineDeploymentId;
   const base = {
-    deploymentName: deployment.name,
-    fromVersion: currentVersion,
-    toVersion: pkg.latestVersion,
-    versionChangeKey: draft.key
+    deploymentName,
+    toVersion: targetVersion,
+    pipelineDeploymentId,
+    ...target.fromVersion !== undefined && {
+      fromVersion: target.fromVersion
+    },
+    ...target.installDeploymentKey !== undefined && {
+      installDeploymentKey: target.installDeploymentKey
+    },
+    ...target.discardedDraftKey !== undefined && {
+      discardedDraftKey: target.discardedDraftKey
+    }
   };
   if (options.noWait) {
-    return { ok: true, ...base, status: draft.operationStatus };
+    return { ok: true, ...base, status: "Accepted" };
   }
   const timeoutSeconds = Number.isFinite(options.timeout) ? options.timeout : DEFAULT_TIMEOUT_SECONDS;
-  const poll = await pollInstallAsync(deploymentsApi, draft.key, upgradeScope, {
+  const poll = await pollPipelineDeploymentAsync(pipelinesApi, auth, {
+    pipelineDeploymentId,
+    deploymentName,
+    scope,
     timeoutMs: timeoutSeconds * 1000,
-    intervalMs: Number.isFinite(options.pollInterval) ? options.pollInterval : DEFAULT_POLL_INTERVAL_MS
+    intervalMs: Number.isFinite(options.pollInterval) ? options.pollInterval : DEFAULT_POLL_INTERVAL_MS,
+    signal: options.signal,
+    logPrefix: "deploy upgrade"
   });
-  if (!poll.ok) {
+  if (poll.outcome !== PollOutcome.Completed) {
+    const failure = mapPollFailure(poll, `Upgrade ${pipelineDeploymentId}`);
     const isTimeout = poll.outcome === PollOutcome.Timeout;
-    return fail5(isTimeout ? "install_timeout" : poll.failure.reason, isTimeout ? `The upgrade of '${deployment.name}' to ${pkg.latestVersion} did not finish within ${timeoutSeconds}s.` : `${poll.failure.message} while upgrading '${deployment.name}' to ${pkg.latestVersion} (last status: ${poll.lastStatus}).`, isTimeout ? `It may still be running. Track deployment '${draft.key}' with 'uip solution deploy list', or pass a longer --timeout.` : `The upgrade may still be running. Track deployment '${draft.key}' with 'uip solution deploy list', then retry if it did not land.`, poll.failure.exitCode);
+    const lastStatus = poll.data?.status ?? "unknown";
+    return fail5(isTimeout ? "install_timeout" : failure.reason, isTimeout ? `The upgrade of '${deploymentName}' to ${targetVersion} did not finish within ${timeoutSeconds}s (last status: ${lastStatus}).` : `${failure.message} while upgrading '${deploymentName}' to ${targetVersion} (last status: ${lastStatus}).`, isTimeout ? `It may still be running. ${trackingHint(pipelineDeploymentId, target.listFlag)} Or pass a longer --timeout.` : `The upgrade may still be running. ${trackingHint(pipelineDeploymentId, target.listFlag)}`, {
+      exitCode: failure.exitCode,
+      errorCode: failure.errorCode,
+      retry: failure.retry
+    });
   }
-  const status = poll.status;
-  if (FAILURE_STATUSES.has(status)) {
-    return fail5("install_failed", `The upgrade of '${deployment.name}' to ${pkg.latestVersion} ended in ${status}: ${await describeValidationFailureAsync(deploymentsApi, draft.key, SolutionDeploymentAction.Upgrade, upgradeScope)}`, "Fix the reported problem, then retry the upgrade.");
+  const finalStatus = poll.data;
+  if (!finalStatus) {
+    return fail5("deploy_failed", `The upgrade of '${deploymentName}' returned no final status.`, trackingHint(pipelineDeploymentId, target.listFlag));
+  }
+  const landedDespiteStatus = installLandedDespiteStatus(finalStatus);
+  if (finalStatus.status !== "DeploymentSucceeded" && !landedDespiteStatus) {
+    return fail5("deploy_failed", `The upgrade of '${deploymentName}' to ${targetVersion} ended in ${finalStatus.status}.`, `${await describeUpgradeFailureAsync(auth.basePath, auth.accessToken, pipelineDeploymentId, finalStatus, scope, options.signal)}
+${leavesPendingDraft(finalStatus.status) ? `Nothing was installed; the deployment stays on the version it was already running. The rejected attempt is kept as a pending draft${finalStatus.deploymentKey ? ` (${finalStatus.deploymentKey})` : ""}, which a plain retry would run into, so once the cause is fixed discard it and retry: ${discardRetryCommand(options, target, finalStatus.deploymentKey || undefined)}` : "Fix the reported problem, then retry the upgrade. The deployment stays on the version it was already running."}`, classifyTerminalFailure(finalStatus.status));
   }
-  return { ok: true, ...base, status };
+  const described = await describeUpgradedDeploymentAsync(auth, deploymentName, finalStatus, scope, target.listFlag);
+  return {
+    ok: true,
+    ...base,
+    deploymentKey: finalStatus.deploymentKey,
+    operation: finalStatus.deploymentResult?.operation ?? finalStatus.synthesizedOperation,
+    status: finalStatus.status,
+    ...finalStatus.deploymentResult?.status && {
+      deploymentStatus: finalStatus.deploymentResult.status,
+      actions: finalStatus.deploymentResult.actions ?? []
+    },
+    ...described,
+    ...landedDespiteStatus && {
+      nextSteps: [
+        explainPipelineStatusAfterInstall(finalStatus),
+        ...described.nextSteps ?? []
+      ]
+    }
+  };
 }
-var IN_FLIGHT_STATUSES = new Set([
-  DeploymentOperationStatus.Draft,
-  DeploymentOperationStatus.InProgress
-]);
-var FAILURE_STATUSES = new Set([
-  DeploymentOperationStatus.Failed,
-  DeploymentOperationStatus.FailedRollback
-]);
-async function pollInstallAsync(deploymentsApi, versionChangeKey, scope, timing) {
-  const result = await pollUntil({
-    fn: () => deploymentsApi.deploymentsGetByKey({ deploymentKey: versionChangeKey }, scope),
-    until: (deployment) => !IN_FLIGHT_STATUSES.has(deployment.operationStatus),
-    getStatus: (deployment) => deployment.operationStatus,
-    label: `upgrade ${versionChangeKey}`,
-    logPrefix: "deploy upgrade",
-    timeoutMs: timing.timeoutMs,
-    intervalMs: timing.intervalMs
-  });
-  if (result.outcome === PollOutcome.Completed && result.data) {
-    return { ok: true, status: result.data.operationStatus };
+async function describeUpgradedDeploymentAsync(auth, deploymentName, finalStatus, scope, listFlag) {
+  const record = finalStatus.deploymentResult;
+  const actions = record?.actions ?? [];
+  if (record?.status === "SuccessfulActivate") {
+    return { activationStatus: "Active" };
+  }
+  const [, rows] = await catchError(findDeploymentsByName(auth, deploymentName, scope));
+  const row = rows?.find((candidate) => candidate.key === finalStatus.deploymentKey);
+  const activationStatus = row?.activationStatus ?? (actions.includes("SetupActivation") ? "NeedsSetupToActivate" : actions.includes("Activate") ? "ReadyToActivate" : undefined);
+  if (!activationStatus) {
+    return {};
+  }
+  const state = {
+    name: deploymentName,
+    operation: row?.operation ?? record?.operation ?? finalStatus.synthesizedOperation,
+    operationStatus: row?.operationStatus ?? "Successful",
+    activationStatus,
+    packageVersion: row?.packageVersion ?? record?.packageVersion,
+    currentPackageVersion: row?.currentPackageVersion ?? record?.packageVersion
+  };
+  const pendingResources = needsPendingResources(state) && finalStatus.deploymentKey ? await readPendingResourcesAsync(new DeploymentsApi(new Configuration({
+    basePath: auth.basePath,
+    accessToken: auth.accessToken
+  })), finalStatus.deploymentKey, scope) : undefined;
+  const nextSteps = deploymentNextSteps(state, pendingResources, listFlag ? ` ${listFlag}` : "");
+  return {
+    activationStatus,
+    ...pendingResources ? { pendingResources } : {},
+    ...nextSteps && nextSteps.length > 0 ? { nextSteps } : {}
+  };
+}
+function trackingHint(pipelineDeploymentId, listFlag) {
+  return listFlag ? `Track it with: uip solution deploy list ${listFlag} (deploy status reads the tenant feed and cannot see this run).` : `Track it with: uip solution deploy status ${pipelineDeploymentId}, or uip solution deploy list.`;
+}
+function discardRetryCommand(options, target, draftKey) {
+  const version = options.version ? ` --version ${options.version}` : "";
+  const key = draftKey ?? options.deploymentKey;
+  if (key) {
+    return `uip solution deploy upgrade ${key} --discard-draft${version}`;
+  }
+  const workspace = options.personalWorkspace ? " --personal-workspace" : "";
+  return `uip solution deploy upgrade --name ${target.deploymentName} --package-name ${target.packageName}${workspace} --discard-draft${version}`;
+}
+function validateTarget(options) {
+  const byKey = options.deploymentKey !== undefined;
+  const byName = options.deploymentName !== undefined || options.packageName !== undefined;
+  if (options.version !== undefined && options.version.trim() === "") {
+    return fail5("invalid_target", "--version was given but is empty.", "Pass the version to upgrade to (uip solution packages list shows the published ones), or omit --version to upgrade to the newest.", INVALID_TARGET);
+  }
+  if (byKey && byName) {
+    return fail5("invalid_target", "Pass either a deployment key or --name with --package-name, not both.", TARGET_INSTRUCTIONS, INVALID_TARGET);
+  }
+  if (byKey) {
+    return GUID_PATTERN.test(options.deploymentKey) ? undefined : fail5("invalid_target", `'${options.deploymentKey}' is not a deployment key.`, `A deployment key is a GUID, reported as Key by 'uip solution deploy list'. To address the deployment by name instead: ${TARGET_INSTRUCTIONS}`, INVALID_TARGET);
+  }
+  if (!options.deploymentName || !options.packageName) {
+    return fail5("invalid_target", "--name and --package-name go together: the Pipelines install route needs both.", TARGET_INSTRUCTIONS, INVALID_TARGET);
+  }
+  return;
+}
+async function resolveTargetByNameAsync(pipelinesApi, auth, options) {
+  const deploymentName = options.deploymentName;
+  let scope;
+  if (options.personalWorkspace) {
+    const verdict = classifyFeedSession(auth);
+    if (verdict !== "user") {
+      const { message, instructions } = feedSessionRefusal(verdict, `Upgrading the Personal Workspace deployment '${deploymentName}'`, "address the deployment by key");
+      return fail5("feed_requires_user_session", message, instructions, {
+        errorCode: "permission_denied",
+        retry: "RetryWillNotFix"
+      });
+    }
+    const [pwError, pw] = await catchError(resolvePersonalWorkspace({
+      tenant: options.tenant,
+      loginValidity: options.loginValidity,
+      envFilePath: options.envFilePath
+    }));
+    if (pwError || !pw) {
+      return fail5("personal_workspace_failed", pwError?.message ?? "Personal Workspace could not be resolved.", "Ensure your user has a Personal Workspace, then retry.");
+    }
+    scope = folderKeyInitOverride(pw.key);
+  }
+  const [existsError] = await catchError(pipelinesApi.pipelinesGetPreActivateSteps({ deploymentName }, scope));
+  if (existsError) {
+    const detail = await extractErrorDetails(existsError);
+    const where = scope ? "your Personal Workspace feed" : `the tenant feed of '${auth.tenantName}'`;
+    if (isDeploymentNotFound(detail)) {
+      return fail5("deployment_not_found", `Deployment '${deploymentName}' was not found in ${where}. 'deploy upgrade' never creates a deployment.`, `Check the name with 'uip solution deploy list'${scope ? "" : " (add --personal-workspace for a Personal Workspace deployment)"}. For a first deployment use 'uip solution deploy run'.`, { errorCode: "not_found", retry: "RetryWillNotFix" });
+    }
+    return fail5("lookup_failed", detail.details ? `${detail.message}: ${detail.details}` : detail.message, `The existence check for '${deploymentName}' failed before any upgrade was requested. Retry, or address the deployment by key: uip solution deploy upgrade <deployment-key>.`, { errorCode: detail.errorCode, retry: detail.retry });
+  }
+  const [rowsError, rows] = await catchError(findDeploymentsByName(auth, deploymentName, scope));
+  if (rowsError) {
+    const unreadable = rowsError instanceof DeploymentSearchNeedsUserSessionError || classifyFeedSession(auth) === "application" && isAuthRefusal(rowsError);
+    if (!unreadable) {
+      const detail = await extractErrorDetails(rowsError);
+      return fail5("lookup_failed", `The status check for '${deploymentName}' failed: ${detail.message}`, "The deployment exists, but whether it is still installed could not be confirmed, and upgrading an uninstalled name would deploy the package afresh under it. Retry, or address the deployment by key: uip solution deploy upgrade <deployment-key>.", { errorCode: detail.errorCode, retry: detail.retry });
+    }
+  }
+  if (isCompletedUninstall(rows ? newestDeploymentRow(rows) : undefined)) {
+    return fail5("deployment_uninstalled", `Deployment '${deploymentName}' has been uninstalled, so there is nothing to upgrade.`, "The install route would create a new deployment under that name rather than upgrade this one. Deploy the package afresh with 'uip solution deploy run', or pick a live deployment from 'uip solution deploy list'.", INVALID_TARGET);
+  }
+  const resolved = {
+    deploymentName,
+    packageName: options.packageName,
+    listFlag: scope ? "--personal-workspace" : undefined
+  };
+  let discardedDraftKey;
+  const newest = rows ? newestDeploymentRow(rows) : undefined;
+  if (newest?.operationStatus === "Draft") {
+    const draft = {
+      key: newest.key,
+      firstInstall: newest.operation === "Install",
+      activationSetup: newest.operation === "ActivationSetup",
+      targetVersion: newest.targetPackageVersion ?? newest.packageVersion,
+      liveVersion: newest.currentPackageVersion
+    };
+    const refusal = refusePendingDraft(options, resolved, draft);
+    if (refusal) {
+      return refusal;
+    }
+    const discarded = await discardDraftAsync(pipelinesApi, deploymentName, draft.key, scope);
+    if (discarded) {
+      return discarded;
+    }
+    discardedDraftKey = draft.key;
   }
   return {
-    ok: false,
-    outcome: result.outcome,
-    lastStatus: result.data?.operationStatus ?? DeploymentOperationStatus.Draft,
-    failure: mapPollFailure(result, `Upgrade ${versionChangeKey}`)
+    ok: true,
+    ...resolved,
+    scope,
+    discardedDraftKey
   };
 }
+function isDeploymentNotFound(detail) {
+  const status = detail.context?.httpStatus;
+  if (status === 404) {
+    return true;
+  }
+  return status === 400 && (/"errorCode"\s*:\s*"4004"/.test(detail.details) || (detail.parsedErrors?.deploymentName ?? []).some((message) => /not found/i.test(message)));
+}
+async function resolveTargetByKeyAsync(pipelinesApi, auth, options, deploymentKey) {
+  const [lookupError, info] = await catchError(pipelinesApi.pipelinesGetDeploymentByKey({ key: deploymentKey }));
+  if (lookupError || !info) {
+    const detail = lookupError ? await extractErrorDetails(lookupError) : undefined;
+    if (detail?.context?.httpStatus === 404 && classifyFeedSession(auth) === "user") {
+      return resolveTargetByKeyViaSolutionsAsync(pipelinesApi, auth, options, deploymentKey);
+    }
+    if (!detail || detail.context?.httpStatus === 404) {
+      return fail5("deployment_not_found", `Deployment '${deploymentKey}' was not found in tenant '${auth.tenantName}'.`, DEPLOYMENT_NOT_FOUND_INSTRUCTIONS, { errorCode: "not_found", retry: "RetryWillNotFix" });
+    }
+    return fail5("lookup_failed", detail.details ? `${detail.message}: ${detail.details}` : detail.message, LOOKUP_FAILED_INSTRUCTIONS, { errorCode: detail.errorCode, retry: detail.retry });
+  }
+  if (info.status === DeploymentStatus.SuccessfulUninstall) {
+    return fail5("deployment_uninstalled", `Deployment '${info.deploymentName}' (${deploymentKey}) has been uninstalled, so there is nothing to upgrade.`, "The install route would create a new deployment under that name rather than upgrade this one. Deploy the package afresh with 'uip solution deploy run', or pick a live deployment from 'uip solution deploy list'.", INVALID_TARGET);
+  }
+  let scope;
+  if (info.locationKey) {
+    const verdict = classifyFeedSession(auth);
+    if (verdict !== "user") {
+      const { message, instructions } = feedSessionRefusal(verdict, `Upgrading deployment '${info.deploymentName}', which is in a Personal Workspace or folder feed (folder key ${info.locationKey}),`, "run the upgrade from the Orchestrator UI");
+      return fail5("feed_requires_user_session", message, instructions, {
+        errorCode: "permission_denied",
+        retry: "RetryWillNotFix"
+      });
+    }
+    scope = folderKeyInitOverride(info.locationKey);
+  } else if (options.personalWorkspace) {
+    return fail5("invalid_target", `Deployment '${info.deploymentName}' (${deploymentKey}) is on the tenant feed, not in a Personal Workspace.`, "Drop --personal-workspace: with a deployment key the feed is read from the deployment itself.", INVALID_TARGET);
+  }
+  const listFlag = info.locationKey ? `--feed ${info.locationKey}` : undefined;
+  let live = info;
+  let discardedDraftKey;
+  if (info.status === DeploymentStatus.Draft) {
+    const draft = {
+      key: info.deploymentKey,
+      firstInstall: info.operation === DeploymentOperation.Install,
+      activationSetup: info.operation === DeploymentOperation.ActivationSetup,
+      targetVersion: info.targetPackageVersion ?? info.packageVersion,
+      liveVersion: info.packageVersion
+    };
+    const refusal = refusePendingDraft(options, {
+      deploymentName: info.deploymentName,
+      packageName: info.packageName,
+      listFlag
+    }, draft);
+    if (refusal) {
+      return refusal;
+    }
+    const discarded = await discardDraftAsync(pipelinesApi, info.deploymentName, draft.key, scope);
+    if (discarded) {
+      return discarded;
+    }
+    const [relookupError, current] = await catchError(pipelinesApi.pipelinesGetDeploymentByKey({
+      key: info.installDeploymentKey
+    }));
+    if (relookupError || !current) {
+      const detail = relookupError ? await extractErrorDetails(relookupError) : undefined;
+      return fail5("lookup_failed", `The pending draft ${draft.key} of '${info.deploymentName}' was discarded, but the live deployment could not be looked up again${detail ? `: ${detail.message}` : "."}`, `Nothing was upgraded. Retry the upgrade: uip solution deploy upgrade ${info.installDeploymentKey}${options.version ? ` --version ${options.version}` : ""}`, detail ? { errorCode: detail.errorCode, retry: detail.retry } : {});
+    }
+    if (current.status === DeploymentStatus.Draft || current.status === DeploymentStatus.SuccessfulUninstall) {
+      return fail5("pending_draft", `The pending draft ${draft.key} of '${info.deploymentName}' was discarded, but the deployment's newest generation is now ${current.status === DeploymentStatus.Draft ? `another draft (${current.deploymentKey})` : "an uninstall"}.`, "Nothing was upgraded. Another operation on this deployment ran in between; check it with 'uip solution deploy list', then retry.", INVALID_TARGET);
+    }
+    live = current;
+    discardedDraftKey = draft.key;
+  }
+  return {
+    ok: true,
+    deploymentName: live.deploymentName,
+    packageName: live.packageName,
+    scope,
+    listFlag,
+    fromVersion: live.packageVersion ?? undefined,
+    installDeploymentKey: live.installDeploymentKey,
+    discardedDraftKey
+  };
+}
+async function resolveTargetByKeyViaSolutionsAsync(pipelinesApi, auth, options, deploymentKey) {
+  let scope;
+  if (options.personalWorkspace) {
+    const [pwError, pw] = await catchError(resolvePersonalWorkspace({
+      tenant: options.tenant,
+      loginValidity: options.loginValidity,
+      envFilePath: options.envFilePath
+    }));
+    if (pwError || !pw) {
+      return fail5("personal_workspace_failed", pwError?.message ?? "Personal Workspace could not be resolved.", "Ensure your user has a Personal Workspace, then retry.");
+    }
+    scope = folderKeyInitOverride(pw.key);
+  }
+  const deploymentsApi = new DeploymentsApi(new Configuration({
+    basePath: auth.basePath,
+    accessToken: auth.accessToken
+  }));
+  const [readError, row] = await catchError(deploymentsApi.deploymentsGetByKey({ deploymentKey }, scope));
+  if (readError || !row) {
+    const detail = readError ? await extractErrorDetails(readError) : undefined;
+    if (!detail || detail.context?.httpStatus === 404) {
+      return fail5("deployment_not_found", `Deployment '${deploymentKey}' was not found in ${scope ? "your Personal Workspace feed" : `the tenant feed of '${auth.tenantName}'`}.`, `Check the key with 'uip solution deploy list'. Neither the Pipelines deployment lookup nor the Solutions read found it; the latter reads a key on the tenant feed, or with --personal-workspace in your workspace, so address a folder-feed deployment with --name and --package-name instead.`, { errorCode: "not_found", retry: "RetryWillNotFix" });
+    }
+    return fail5("lookup_failed", detail.details ? `${detail.message}: ${detail.details}` : detail.message, LOOKUP_FAILED_INSTRUCTIONS, { errorCode: detail.errorCode, retry: detail.retry });
+  }
+  if (row.status === "SuccessfulUninstall") {
+    return fail5("deployment_uninstalled", `Deployment '${row.name}' (${deploymentKey}) has been uninstalled, so there is nothing to upgrade.`, "The install route would create a new deployment under that name rather than upgrade this one. Deploy the package afresh with 'uip solution deploy run', or pick a live deployment from 'uip solution deploy list'.", INVALID_TARGET);
+  }
+  const target = await resolveTargetByNameAsync(pipelinesApi, auth, {
+    ...options,
+    deploymentName: row.name,
+    packageName: row.packageName
+  });
+  if (!target.ok) {
+    return target;
+  }
+  return { ...target, installDeploymentKey: row.installDeploymentKey };
+}
+function refusePendingDraft(options, target, draft) {
+  const targetVersion = draft.targetVersion ?? "<version>";
+  const feed = target.listFlag ? ` ${target.listFlag}` : "";
+  const retryDraft = `uip solution deploy run --name ${target.deploymentName} --package-name ${target.packageName} --package-version ${targetVersion} --config-file <fixed-config>${feed} --yes`;
+  if (draft.firstInstall) {
+    return fail5("pending_draft", `Deployment '${target.deploymentName}' was never installed: its first install (${draft.key}) is still a pending draft, so there is nothing to upgrade.`, `The draft is an attempt that never completed, usually one rejected by validation, or one still running. To retry it with a corrected configuration: ${retryDraft} (the server re-validates the draft with the new file). To abandon it, delete it in Orchestrator.`, INVALID_TARGET);
+  }
+  if (options.discardDraft) {
+    return;
+  }
+  if (draft.activationSetup) {
+    return fail5("pending_draft", `Deployment '${target.deploymentName}' has an unfinished Setup activation (${draft.key}): the Orchestrator "Setup activation" wizard was started on version ${targetVersion} and not completed.`, `While that draft exists the server would run it in place of this upgrade, or refuse a different version. Finish the setup in Orchestrator (Solutions, the deployment, Setup activation), then retry; or discard it and upgrade the live version: ${discardRetryCommand(options, target, draft.key)}`, INVALID_TARGET);
+  }
+  const live = draft.liveVersion ? ` ${draft.liveVersion}` : "";
+  return fail5("pending_draft", `Deployment '${target.deploymentName}' has a pending draft (${draft.key}) for version ${targetVersion}: an earlier attempt that never completed, usually one rejected by validation, or one still running.`, `The server would run that draft, with the configuration it was built with, in place of this upgrade, or refuse a different version. To discard it and upgrade the live version${live}: ${discardRetryCommand(options, target, draft.key)}
+To retry the draft itself with a corrected configuration instead: ${retryDraft}`, INVALID_TARGET);
+}
+async function discardDraftAsync(pipelinesApi, deploymentName, draftKey, scope) {
+  const [error] = await catchError(pipelinesApi.pipelinesDeleteDeploymentByKey({ deploymentKey: draftKey }, scope));
+  if (!error) {
+    return;
+  }
+  const detail = await extractErrorDetails(error);
+  const status = detail.context?.httpStatus;
+  const hasBody = !isBareResponse(detail.details);
+  if (hasServerErrorCode(detail.details, "DeploymentNotFound") || status === 404 && hasBody) {
+    return;
+  }
+  const message = `The pending draft ${draftKey} of '${deploymentName}' could not be discarded: ${hasBody ? `${detail.message}: ${detail.details}` : detail.message}`;
+  if (status === 405 || status === 404 && !hasBody) {
+    return fail5("discard_draft_failed", message, "This server cannot discard drafts through the Pipelines API yet. Nothing was upgraded. Delete the draft in Orchestrator, then retry the upgrade.", {
+      errorCode: status === 405 ? "method_not_allowed" : "not_found",
+      retry: "RetryWillNotFix"
+    });
+  }
+  if (hasServerErrorCode(detail.details, "DeploymentAlreadyInProgress")) {
+    return fail5("discard_draft_failed", message, "The draft is still being validated. Nothing was upgraded. Wait for its run to finish (uip solution deploy list shows it), then retry.", { errorCode: "invalid_argument", retry: "RetryLater" });
+  }
+  if (hasServerErrorCode(detail.details, "DeploymentInvalidState")) {
+    return fail5("discard_draft_failed", message, "The draft is no longer one that can be discarded: it moved on (it was promoted, or it is a rollback). Nothing was upgraded. Check the deployment with 'uip solution deploy list', then retry.", INVALID_TARGET);
+  }
+  return fail5("discard_draft_failed", message, "Nothing was upgraded. Retry, or delete the draft in Orchestrator and then retry the upgrade.", { errorCode: detail.errorCode, retry: detail.retry });
+}
+function classifyTerminalFailure(status) {
+  return status === "ValidationFailed" || status === "ConflictFixingError" ? { errorCode: "invalid_argument", retry: "RetryWillNotFix" } : {};
+}
+async function describeUpgradeFailureAsync(basePath, accessToken, pipelineDeploymentId, finalStatus, scope, signal) {
+  const fromPipeline = formatDeploymentFailureDetails(pipelineDeploymentId, finalStatus);
+  const explained = finalStatus.validationResult?.validationErrors?.length || finalStatus.validationResult?.conflictErrors?.length || finalStatus.conflictFixingErrors?.length || finalStatus.deploymentScheduleErrors?.length || finalStatus.deploymentResult?.errorMessage;
+  if (explained || !finalStatus.deploymentKey) {
+    return fromPipeline;
+  }
+  const deploymentsApi = new DeploymentsApi(new Configuration({ basePath, accessToken }));
+  const reason = await describeValidationFailureAsync(deploymentsApi, finalStatus.deploymentKey, SolutionDeploymentAction.Upgrade, scope, signal);
+  return reason === NO_SERVER_REASON ? fromPipeline : `Validation: ${reason}
+${fromPipeline}`;
+}
 
 // src/services/packages-list-service.ts
-var fail6 = (reason, message, instructions, exitCode = 1) => ({
+var fail6 = (reason, message, instructions, extras = {}) => ({
   ok: false,
   reason,
   message,
   instructions,
-  exitCode
+  exitCode: 1,
+  ...extras
 });
 async function listPackagesAsync(options = {}) {
   const limit = options.limit ?? DEFAULT_PAGE_SIZE;
@@ -8610,9 +8968,10 @@ async function listPackagesAsync(options = {}) {
     envFilePath: options.envFilePath
   }));
   if (scopeError) {
-    return fail6("feed_resolution_failed", scopeError.message, feedResolutionFailureInstructions(options));
+    const { message, instructions, ...extras } = await describeFeedResolutionFailureAsync(scopeError, options, auth);
+    return fail6("feed_resolution_failed", message, instructions, extras);
   }
-  const searchApi = new SearchApi(new Configuration2({
+  const searchApi = new SearchApi(new Configuration({
     basePath: auth.basePath,
     accessToken: auth.accessToken
   }));
@@ -8626,8 +8985,10 @@ async function listPackagesAsync(options = {}) {
     }
   }, feedScopeInitOverride(scope)));
   if (listError) {
-    const { message, details } = await extractErrorDetails(listError);
-    return fail6("list_request_failed", message, `Failed to list packages. Details: ${details}`);
+    const { message, instructions, ...extras } = await describeSearchFailureAsync(listError, "packages", auth, {
+      userSessionsOnly: true
+    });
+    return fail6("list_request_failed", message, instructions, extras);
   }
   const packages = result.values ?? [];
   return {
@@ -8641,4 +9002,4 @@ async function listPackagesAsync(options = {}) {
 
 export { extractDeploymentErrors, formatDeploymentErrorsAsText, activateDeploymentAsync, listDeploymentsAsync, deployRunAsync, uninstallDeploymentAsync, upgradeDeploymentAsync, listPackagesAsync };
 
-//# debugId=C7F5318965ACD96664756E2164756E21
+//# debugId=3F2F38B7889B837064756E2164756E21