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

package/dist/services/deploy-upgrade-service.d.ts

@@ -1,20 +1,49 @@
-import type { PollFailureReason } from "@uipath/common";
-import { DeploymentOperationStatus } from "@uipath/solution-sdk";
-export type UpgradeDeploymentFailureReason = "auth_failed"
+import type { CliErrorCode, PollFailureReason, RetryHint } from "@uipath/common";
+import type { PipelineDeploymentStatus } from "@uipath/pipelines-sdk";
+import { type PendingResource } from "./deployment-state";
+export type UpgradeDeploymentFailureReason = 
+/** Neither a deployment key nor a name+package pair was given, or both were. */
+"invalid_target" | "auth_failed"
+/**
+ * No deployment to upgrade: the key form's lookup found none (unknown key,
+ * or a server without the lookup), or the name form's existence check
+ * answered 404 for the name in that feed.
+ */
+ | "deployment_not_found"
+/** The key form's lookup, the name form's existence check, or the version lookup failed for a reason other than "not found". */
+ | "lookup_failed"
+/** The key names an uninstalled deployment; an install would create a new one, not upgrade it. */
+ | "deployment_uninstalled"
+/**
+ * The deployment's newest generation is a Draft: an attempt that never
+ * completed — usually one rejected by validation — which the install route
+ * reuses for the name. It would re-run that draft, with the configuration it
+ * was rejected for, in place of this upgrade, or refuse a different version
+ * (`DraftDeploymentHasDifferentPackageVersion`). `discardDraft` discards it
+ * and upgrades the live generation instead.
+ */
+ | "pending_draft"
+/** `discardDraft` was set and the server did not discard the pending draft. */
+ | "discard_draft_failed"
+/**
+ * The deployment sits in a folder or Personal Workspace feed and the
+ * session is an external app. The server does not apply the feed header
+ * to client-credentials requests, so the install would create a new
+ * tenant-feed deployment instead of upgrading this one.
+ */
+ | "feed_requires_user_session"
 /** Personal Workspace could not be resolved (only when `--personal-workspace`). */
  | "personal_workspace_failed"
-/** No deployment with the given key (or not visible in the chosen scope). */
- | "deployment_not_found"
-/** The deployment is already at the newest version and no `--version` was given. */
- | "no_upgrade_available"
-/** The target package/version could not be resolved to a package-version key. */
+/** The target package version is not published in the feed. */
  | "package_not_found"
-/** Requested a version other than the latest, which the package search can't key. */
- | "unsupported_version"
-/** The upgrade HTTP request failed. */
+/** The Pipelines install request was refused before anything was queued. */
  | "request_failed"
-/** The upgrade was queued but installing the resulting draft failed. */
- | "install_failed"
+/**
+ * The pipeline reached a terminal state other than `DeploymentSucceeded`:
+ * validation, conflict fixing, scheduling or the install itself failed.
+ * The live deployment stays on its previous version.
+ */
+ | "deploy_failed"
 /** The install was accepted but did not reach a terminal state in time. */
  | "install_timeout"
 /**
@@ -24,6 +53,31 @@ export type UpgradeDeploymentFailureReason = "auth_failed"
  */
  | PollFailureReason;
 export interface UpgradeDeploymentOptions {
+    /**
+     * Key of the deployment to upgrade, as `deploy list` reports it. Resolved
+     * through the Pipelines lookup, which spans every feed in the tenant and
+     * answers with the deployment's name, package, current version and feed —
+     * so this form needs neither `packageName` nor a feed flag. Either this or
+     * `deploymentName` + `packageName`, not both.
+     */
+    deploymentKey?: string;
+    /**
+     * Name of the deployment to upgrade — the name it was deployed under, which
+     * is how the Pipelines install route addresses it. Goes with `packageName`.
+     */
+    deploymentName?: string;
+    /**
+     * The deployment's package, for the name form. Required there because it is
+     * a path segment of the install route and the key the version lookup
+     * resolves against, and no name-keyed Pipelines route reports it.
+     */
+    packageName?: string;
+    /**
+     * Version to upgrade to. Any published version of the same package is
+     * accepted, including an older one. Omitted, the newest published version
+     * is resolved and used.
+     */
+    version?: string;
     /**
      * Override the active tenant for auth resolution. The CLI's deprecated
      * `--tenant` flag flows through here; library callers usually omit it.
@@ -32,43 +86,112 @@ export interface UpgradeDeploymentOptions {
     /** Pin auth to this exact `.uipath/.auth` path. */
     envFilePath?: string;
     /**
-     * Version to upgrade to. Defaults to the deployment's newest available
-     * version. Only the latest published version is resolvable today (same
-     * limitation as Personal Workspace deploy).
+     * Name form: scope the version lookup, the install and its status poll to
+     * the caller's Personal Workspace feed. Key form: redundant — the feed is
+     * read from the deployment itself — and accepted for compatibility with
+     * the original `deploy upgrade <key> --personal-workspace`; it is rejected
+     * only when the deployment turns out to be on the tenant feed.
      */
-    version?: string;
+    personalWorkspace?: boolean;
     /**
-     * Scope the deployment lookup and the upgrade to the caller's Personal
-     * Workspace feed. A tenant deployment is upgraded in its own root folder.
+     * When the deployment's newest generation is a pending Draft — an earlier
+     * attempt that never completed, usually one rejected by validation — delete
+     * that draft first (`DELETE /pipelines/deployments/{key}`) and upgrade
+     * the live generation with its own configuration. Without it such a
+     * deployment is refused with `pending_draft`, because the install route
+     * would re-run the draft, with the configuration it was rejected for, in
+     * place of this upgrade. The name form can find the draft only with a user
+     * session (it reads the Solutions search); under an external app, address
+     * the deployment by key.
      */
-    personalWorkspace?: boolean;
+    discardDraft?: boolean;
     /** Minimum minutes before token expiration to trigger a refresh. Default 10. */
     loginValidity?: number;
     /**
      * Return as soon as the install is accepted, without polling for the
-     * terminal state. The version still moves; the caller just does not wait.
+     * terminal state. Validation is already queued server-side; the caller
+     * just does not wait for it.
      */
     noWait?: boolean;
     /** Seconds to wait for the install to reach a terminal state. Default 300. */
     timeout?: number;
     /** Milliseconds between status polls. Default 5000. */
     pollInterval?: number;
+    /**
+     * Host-side cancellation for the status poll (the CLI's Ctrl-C, VS Code's
+     * cancel button). `pollUntil` has no default signal, so without this a
+     * cancelled upgrade keeps polling until `--timeout`.
+     */
+    signal?: AbortSignal;
 }
 export interface UpgradeDeploymentSuccess {
     ok: true;
     deploymentName: string;
-    /** Version the deployment ran before the upgrade (null when the API omits it). */
-    fromVersion?: string | null;
-    /** Version the upgrade targets. */
+    /**
+     * Version deployed before this run. Known only for the key form, whose
+     * lookup reports it; the name form makes no read that would.
+     */
+    fromVersion?: string;
+    /** Version the upgrade targeted. */
     toVersion: string;
     /**
-     * Key of the VersionChange deployment the upgrade created. This is NOT the
-     * key that was passed in — the server makes a new record — and it is the
-     * one `deploy status`-style follow-ups must address.
+     * Key of the original install, stable across every upgrade — the one a
+     * pipeline should store. Key form only, from the lookup.
+     */
+    installDeploymentKey?: string;
+    /**
+     * Id of the Pipelines run performing the upgrade. This is what
+     * `uip solution deploy status <id>` reads.
+     */
+    pipelineDeploymentId: string;
+    /**
+     * Key of the upgraded deployment record, from the pipeline's terminal
+     * status. Undefined with `noWait`.
+     */
+    deploymentKey?: string;
+    /**
+     * What the server actually did, from the run's own record:
+     * `VersionChange` for a version move, `ConfigurationChange` when the
+     * requested version was already the deployed one. Undefined with `noWait`,
+     * and when the run reports no deployment record.
+     */
+    operation?: string;
+    /** Terminal pipeline status, or `"Accepted"` when `noWait` returned before polling. */
+    status: PipelineDeploymentStatus | "Accepted";
+    /**
+     * The upgraded deployment's own status, from the run's `deploymentResult`
+     * — the difference `status` cannot show between a new version that runs
+     * (`SuccessfulActivate`) and one that installed but waits for activation
+     * setup (`SuccessfulInstall`, with the previous version still running).
+     * Undefined with `noWait`, and when the run reports no deployment record
+     * (a recycled run record the poll settled from elsewhere).
+     */
+    deploymentStatus?: string;
+    /** What can be done with the deployment next, from the same record (e.g. `SetupActivation`, `Uninstall`, `Upgrade`). Undefined when `deploymentStatus` is. */
+    actions?: string[];
+    /**
+     * Key of the pending draft `discardDraft` deleted before this upgrade.
+     * Undefined when there was none to discard.
      */
-    versionChangeKey: string;
-    /** Terminal status reached, or `Draft`/`InProgress` when `noWait`. */
-    status: DeploymentOperationStatus;
+    discardedDraftKey?: string;
+    /**
+     * Whether the new version runs, in the deployment record's own words:
+     * `Active`, `NeedsSetupToActivate` (installed; "Setup activation" in
+     * Orchestrator is still due and the previous version keeps running),
+     * `ReadyToActivate`, … From the search row when a user session can read
+     * it, otherwise derived from `deploymentStatus` and `actions`
+     * (`SuccessfulActivate` → `Active`, `SetupActivation` offered →
+     * `NeedsSetupToActivate`, `Activate` offered → `ReadyToActivate`). Absent
+     * when neither says, and with `noWait` (STUD-81555).
+     */
+    activationStatus?: string;
+    /**
+     * The resources that still need configuration before activation, when the
+     * deployment waits for setup and the read succeeded.
+     */
+    pendingResources?: PendingResource[];
+    /** What is left before the new version runs; absent when it does. */
+    nextSteps?: string[];
 }
 export interface UpgradeDeploymentFailure {
     ok: false;
@@ -76,19 +199,55 @@ export interface UpgradeDeploymentFailure {
     message: string;
     instructions: string;
     exitCode: number;
+    /**
+     * Set whenever the failure mode is known, so the CLI does not fall back to
+     * `OutputFormatter`'s guess. That guess is wrong for a poll that timed
+     * out: the message carries no HTTP status, so it reports `unknown_error` /
+     * `RetryWillNotFix` while the instructions beside it say the upgrade may
+     * still be running.
+     */
+    errorCode?: CliErrorCode;
+    retry?: RetryHint;
 }
 export type UpgradeDeploymentResult = UpgradeDeploymentSuccess | UpgradeDeploymentFailure;
 /**
  * Programmatic core of `uip solution deploy upgrade`. Moves an existing
- * deployment to a newer package version in place — the CLI equivalent of the
- * Orchestrator UI "Upgrade" button, so a blocked redeploy (UV-15356) can be
- * resolved without the UI.
+ * deployment to another published version of its package in place — the CLI
+ * equivalent of the Orchestrator UI "Upgrade" button — so a blocked redeploy
+ * (UV-15356) can be resolved without the UI. Values already set on the
+ * deployment are kept: the server carries each unchanged resource's
+ * configuration forward and takes only changed specs from the package.
+ *
+ * Goes through the Pipelines install endpoint, which is a unified
+ * install / configuration-change / upgrade: a deployment named
+ * `deploymentName` that exists with the same package and a *different*
+ * version is upgraded in its own folder. The pipeline validates the package
+ * against the target **before** it schedules the install — a failed validation
+ * ends the run at `ValidationFailed` with the errors attached, and the live
+ * deployment never enters `ValidateError` (SOL-7799).
+ *
+ * Addressed either by **name + package** or by **deployment key**, and both
+ * forms stay on external-app (client-credentials) capable Pipelines endpoints,
+ * which is what a CI/CD pipeline needs (SOL-7805). The name form makes no
+ * version lookup when `--version` is given, but it does check the name exists
+ * first (`pre-activate-steps`): the route takes a name and creates a fresh
+ * deployment for one it cannot find, so a typo must fail rather than deploy.
+ * `packageName` is required because nothing name-keyed in Pipelines reports
+ * it. The key form resolves
+ * the key through `GET /pipelines/deployments/by-key/{key}` — S2S-capable,
+ * spanning every feed in the tenant, and answering a superseded key with the
+ * deployment's current generation — and takes name, package, feed and the
+ * version being upgraded from off that answer. The Automation Solutions
+ * `GET /api/deployments/{key}` is user-token only and is never called.
  *
- * Two server calls, because one is not enough:
- * `POST /api/deployments/{key}/upgrade` only queues the move as a second
- * deployment record (`VersionChange`, status `Draft`) and leaves the live
- * version alone, then `POST /api/deployments/{draftKey}/run` installs it.
- * Waits for the install to reach a terminal state unless `noWait` is set.
  * Does not touch `OutputFormatter`/`processContext`.
  */
-export declare function upgradeDeploymentAsync(deploymentKey: string, options?: UpgradeDeploymentOptions): Promise<UpgradeDeploymentResult>;
+export declare function upgradeDeploymentAsync(options: UpgradeDeploymentOptions): Promise<UpgradeDeploymentResult>;
+/**
+ * The 1.202 signature, kept so library callers keep compiling:
+ * `upgradeDeploymentAsync(deploymentKey, { version, personalWorkspace, … })`.
+ * Same as passing `{ deploymentKey, …options }`.
+ *
+ * @deprecated Pass a single options object with `deploymentKey`.
+ */
+export declare function upgradeDeploymentAsync(deploymentKey: string, options?: Omit<UpgradeDeploymentOptions, "deploymentKey" | "deploymentName" | "packageName">): Promise<UpgradeDeploymentResult>;

package/dist/services/deployment-feed-locator.d.ts

@@ -1,15 +1,51 @@
-import type { DeploymentSearchItemDto2, InitOverrideFunction, SolutionAuthContext } from "@uipath/solution-sdk";
+import type { DeploymentSearchItemDto2, InitOverrideFunction } from "@uipath/solution-sdk";
+import type { SolutionAuthContext } from "@uipath/solution-sdk/auth";
+import { type FeedKind } from "./feed-resolver";
+import type { SkippedFeed } from "./incomplete-feed-sweep";
 /** A deployment and the feed header every call about it needs. */
 export interface DeploymentLocation {
     deployment: DeploymentSearchItemDto2;
     /** `X-UIPATH-FolderKey` override; undefined for the tenant feed. */
     scope?: InitOverrideFunction;
+    /**
+     * The non-tenant feed the deployment was found in; undefined for the
+     * tenant feed. What a generated follow-up command needs in order to name
+     * its flag (`feedSelectorFlag`) — the override alone cannot be printed.
+     */
+    feed?: {
+        kind: Exclude<FeedKind, "tenant">;
+        folderKey: string;
+    };
+}
+/**
+ * What a sweep across the feeds found, and whether it could ask every feed.
+ *
+ * A missing `location` means "no such deployment" only when `complete` is
+ * true. Otherwise it means "not in the feeds that answered", and a caller
+ * that reports it as not found tells an agent never to retry a name that may
+ * be fine (#4390).
+ */
+export interface DeploymentSweep {
+    /** The first exact-name match, tenant first; undefined when none was found. */
+    location?: DeploymentLocation;
+    /** The feeds that could not be searched, in sweep order. */
+    skipped: SkippedFeed[];
+    /** True when no feed was skipped. */
+    complete: boolean;
 }
 /** Auth-resolution knobs the feed sweep forwards to its lookups. */
 export interface DeploymentLocationOptions {
     tenant?: string;
     loginValidity?: number;
     envFilePath?: string;
+    /**
+     * Also accept a name whose newest row records a completed uninstall.
+     * `deploy delete` exists to remove exactly those records (UV-16671).
+     * `activate` and `uninstall` act on a live deployment and leave it off, so
+     * a name uninstalled on the tenant and redeployed into a feed resolves to
+     * the feed rather than to the tenant's history row.
+     */
+    includeUninstalled?: boolean;
 }
 /**
  * Locate a deployment and the feed it lives in.
@@ -21,16 +57,18 @@ export interface DeploymentLocationOptions {
  * to the tenant-scoped search, so an unscoped call is answered "not found".
  *
  * Tenant first — that is the default feed and the one most deployments live in,
- * so the common case costs one request. A tenant-search transport error
- * propagates (callers treat it as a lookup failure). Only on a tenant miss does
- * the sweep run, and it is best-effort throughout: a feed whose search fails is
- * skipped rather than allowed to end the sweep, since the next feed may hold
- * the record. A tenant that exposes many folder feeds therefore pays one search
+ * so the common case costs one request. Only on a tenant miss does the sweep
+ * run, and it is best-effort throughout: a feed whose search fails is skipped
+ * rather than allowed to end the sweep, since the next feed may hold the
+ * record. Skipped is not silent: every skipped feed is in the answer's
+ * `skipped`, so a caller can tell a clean miss from one where a feed did not
+ * answer. A tenant that exposes many folder feeds therefore pays one search
  * per feed, but only on a path that was already going to fail.
+ *
+ * Never throws. A tenant search that fails comes back as a sweep that skipped
+ * the tenant feed, and the sweep stops there: a match in a later feed could
+ * be another deployment under the same name, and `delete` would remove it.
+ * So a tenant search that answers 404 is "could not search", never
+ * "not found", on every verb.
  */
-export declare function findDeploymentAcrossFeeds(auth: SolutionAuthContext, deploymentName: string, options: DeploymentLocationOptions): Promise<DeploymentLocation | undefined>;
-/**
- * {@link findDeploymentAcrossFeeds} that never throws — for callers that want
- * the feed scope when it can be had but must not fail when it cannot.
- */
-export declare function findDeploymentAcrossFeedsBestEffort(auth: SolutionAuthContext, deploymentName: string, options: DeploymentLocationOptions): Promise<DeploymentLocation | undefined>;
+export declare function findDeploymentAcrossFeeds(auth: SolutionAuthContext, deploymentName: string, options: DeploymentLocationOptions): Promise<DeploymentSweep>;

package/dist/services/deployment-search-client.d.ts

@@ -0,0 +1,55 @@
+import { type DeploymentActivationStatus, type DeploymentOperationStatus, type DeploymentSearchItemDto2, type InitOverrideFunction } from "@uipath/solution-sdk";
+import type { SolutionAuthContext } from "@uipath/solution-sdk/auth";
+export type DeploymentSearchSource = "pipelines" | "legacy-v3";
+/** One page of the deployment search, in the terms both routes understand. */
+export interface DeploymentSearchQuery {
+    take: number;
+    skip: number;
+    /**
+     * Exact name. Filtered by the server on the Pipelines route; a substring
+     * term on the legacy one, so callers keep their exact match.
+     */
+    deploymentName?: string;
+    packageName?: string;
+    /** The row's parent folder by full path: exact, case-insensitive, subfolders excluded. */
+    targetFolderName?: string;
+    searchTerm?: string;
+    orderByColumn?: string;
+    orderByDirection?: "Ascending" | "Descending";
+    operationStatuses?: DeploymentOperationStatus[];
+    activationStatuses?: DeploymentActivationStatus[];
+}
+export interface DeploymentSearchPage {
+    /** The filtered total; `undefined` when the server omits it. */
+    count?: number;
+    values: DeploymentSearchItemDto2[];
+    /** Which route answered — for logs and tests, never for output. */
+    source: DeploymentSearchSource;
+}
+/**
+ * The server has only the legacy search, and that one reads user tokens only.
+ * Thrown instead of making a request that can only answer 403, so a caller can
+ * tell "cannot be read with this login" from an outage — the distinction the
+ * application-session gates were written for.
+ */
+export declare class DeploymentSearchNeedsUserSessionError extends Error {
+    constructor();
+}
+/**
+ * Whether an error from the Pipelines search means the server has no such
+ * route (and the legacy search should answer), as opposed to a failure of
+ * the route itself. Measured on a server without it: the POST falls onto
+ * `GET deployments/{deploymentKey}` and answers **405** with no body; a path
+ * matching nothing answers 404 with no body. A 404 with *any* body — an
+ * `errorCode`, or a plain ProblemDetails — is the route answering, and must
+ * reach the caller.
+ */
+export declare function isMissingPipelinesSearchRoute(error: unknown): Promise<boolean>;
+/**
+ * The one deployment search every command goes through: the Pipelines route
+ * (SOL-7807), which reads application sessions too and filters an exact name
+ * on the server; the deprecated `/api/v3/search/deployments` only on a server
+ * without it. Rows come back as the solution-sdk's DTO either way — the
+ * Pipelines row is a superset of it, so its extra fields are dropped.
+ */
+export declare function searchDeploymentsPage(auth: SolutionAuthContext, query: DeploymentSearchQuery, scope?: InitOverrideFunction): Promise<DeploymentSearchPage>;

package/dist/services/deployment-search.d.ts

@@ -1,26 +1,45 @@
 import type { PipelineDeploymentResult, PipelineDeploymentStatus } from "@uipath/pipelines-sdk";
-import type { DeploymentOperationStatus, DeploymentSearchItemDto2, InitOverrideFunction, SolutionAuthContext } from "@uipath/solution-sdk";
+import type { DeploymentOperationStatus, DeploymentSearchItemDto2, InitOverrideFunction } from "@uipath/solution-sdk";
+import type { SolutionAuthContext } from "@uipath/solution-sdk/auth";
+export { httpStatusOf } from "./http-status";
 /**
  * Look up a deployment by name in the persistent search/list service.
- * Returns the matching record, or undefined when no deployment with that
- * exact name exists.
+ * Returns the deployment's **current generation** — every upgrade and
+ * configuration change writes a new row under the same name, and the first
+ * row the search happens to return can be an older one — or undefined when
+ * no deployment with that exact name exists.
  *
  * Throws on transport / server errors. Use {@link findDeploymentBestEffort}
  * when you want a best-effort lookup that swallows failures.
  */
 export declare function findDeploymentByName(auth: SolutionAuthContext, deploymentName: string, scope?: InitOverrideFunction): Promise<DeploymentSearchItemDto2 | undefined>;
+/**
+ * The deployment a name currently denotes **if it is still installed** —
+ * undefined when the name's newest row records a *completed* uninstall, since
+ * the older generations under it belong to a deployment that is gone. A
+ * failed or in-flight uninstall leaves the deployment present (see
+ * `blocksRedeploy`), so those rows are live. This is the
+ * selector for *locating* a deployment to act on (activate, uninstall): a
+ * tenant name whose deployment was uninstalled and redeployed into a Personal
+ * Workspace must resolve to the workspace, not stop the sweep at the tenant's
+ * history row. `findDeploymentByName` keeps the uninstall row for callers
+ * that wait on the current operation, whatever it is.
+ */
+export declare function findLiveDeploymentByName(auth: SolutionAuthContext, deploymentName: string, scope?: InitOverrideFunction): Promise<DeploymentSearchItemDto2 | undefined>;
+/** A row recording an uninstall that finished: the deployment is gone. */
+export declare function isCompletedUninstall(row: Pick<DeploymentSearchItemDto2, "operation" | "operationStatus"> | undefined): boolean;
 /**
  * Every deployment whose `packageName` matches exactly.
  *
- * Pages `searchSearchDeployments22` to exhaustion instead of stopping at the
- * first hit, because the redeploy gate has to report *all* the deployments
- * that already exist, not just one.
+ * Pages the deployment search to exhaustion instead of stopping at the first
+ * hit, because the redeploy gate has to report *all* the deployments that
+ * already exist, not just one.
  *
- * Sends two filters on purpose. `packageName` is the request's own server-side
- * filter, which keeps the result set small; `searchTerm` is the substring
- * filter the other call sites here already rely on, so the lookup still works
- * if the server ignores `packageName`. The client-side `===` check is what
- * makes the answer exact either way.
+ * `packageName` is the server-side filter, which keeps the result set small;
+ * on the deprecated V3 route it also travels as the substring `searchTerm`
+ * (see `toLegacyV3Request`), so the lookup still works if that server ignores
+ * `packageName`. The client-side `===` check is what makes the answer exact
+ * either way.
  *
  * Statuses are deliberately unfiltered — callers decide which states matter
  * (the gate uses {@link blocksRedeploy}; the redeploy-conflict path needs the
@@ -32,6 +51,29 @@ export declare function findDeploymentsByPackageName(auth: SolutionAuthContext,
     folderPath?: string;
     scope?: InitOverrideFunction;
 }): Promise<DeploymentSearchItemDto2[]>;
+/**
+ * The record that stands for a deployment *now*.
+ *
+ * Every operation adds a record: `deploy run` creates the Install record,
+ * `deploy upgrade` a VersionChange one, the UI's setup an ActivationSetup one.
+ * `deploy list` shows only the newest of each chain, but a key handed out
+ * earlier keeps answering `deploymentsGetByKey` as if it were current — the
+ * old version, `Active`, `Upgrade` offered, and nothing on it saying it was
+ * superseded. Acting on it is what the service refuses with `4005` and what
+ * left an agent unable to tell which upgrade had landed (STUD-81555).
+ *
+ * The chain shares one `installDeploymentKey`, so the current record is the
+ * `deploy list` row that carries it. `undefined` means the search answered
+ * and no row carries the key; a search that fails **throws**, because "could
+ * not look" and "nothing newer" must not read the same — a caller that took
+ * a failed search for an empty one would present the stale record as current,
+ * which is the very report this lookup exists to prevent.
+ */
+export declare function findCurrentDeploymentAsync(auth: SolutionAuthContext, deployment: {
+    key: string;
+    installDeploymentKey?: string | null;
+    packageName: string;
+}, scope?: InitOverrideFunction): Promise<DeploymentSearchItemDto2 | undefined>;
 /**
  * Does this record represent a deployment that is really there, so a fresh
  * `deploy run` of the same package would create a second copy of it?
@@ -48,7 +90,7 @@ export declare function findDeploymentsByPackageName(auth: SolutionAuthContext,
  * - **`Draft` / `Failed` / `FailedRollback` on an `Install`** — does not block.
  *   The deploy the user is retrying is the one that produced the record, and
  *   our own guidance for a Draft is to fix the errors and rerun `deploy run`
- *   (see {@link appendDraftDeploymentInstructions}). Blocking would leave the
+ *   (see {@link appendDeploymentStateInstructions}). Blocking would leave the
  *   user with nothing they are allowed to do.
  * - **`Draft` / `Failed` / `FailedRollback` on any other operation** — blocks.
  *   An uninstall or an upgrade that failed ran *against* a deployment that is
@@ -88,13 +130,40 @@ export declare function formatExistingDeployments(deployments: DeploymentSearchI
  * masking a prior error (error paths) or blocking an otherwise-successful
  * result (success paths, e.g. reading back the resolved install folder).
  */
-export declare function findDeploymentBestEffort(auth: SolutionAuthContext, deploymentName: string, scope?: InitOverrideFunction): Promise<DeploymentSearchItemDto2 | undefined>;
 /**
- * Append a hint to error instructions when the deployment in question is
- * stuck in `Draft` state — that condition has a specific remediation that
- * generic instructions don't cover.
+ * Every search row whose name matches exactly. A name is shared by every
+ * generation of a deployment — the original install and each upgrade or
+ * configuration change writes a new row under it — so callers that need
+ * *this run's* row must pick among these rather than take the first.
  */
-export declare function appendDraftDeploymentInstructions(instructions: string, deployment?: DeploymentSearchItemDto2): string;
+export declare function findDeploymentsByName(auth: SolutionAuthContext, deploymentName: string, scope?: InitOverrideFunction): Promise<DeploymentSearchItemDto2[]>;
+/** Which of a name's rows a caller is looking for. */
+export interface DeploymentRowPreference {
+    /**
+     * The deployment key the pipelines status endpoint reported for this run.
+     * The run record carries its deployment row from creation, so any status
+     * read before the record is recycled names the exact row; with it set,
+     * only that row is returned, never another generation.
+     */
+    deploymentKey?: string;
+}
+/**
+ * The search row for `deploymentName` a caller is after — or undefined when
+ * there is none, or the lookup itself failed (swallowed on purpose: every
+ * caller has a better error to report than a transport failure of a
+ * best-effort read).
+ *
+ * With `prefer.deploymentKey`, exactly that row or nothing (and nothing when
+ * that row now records an uninstall): this is the form anything that
+ * *settles or recovers a run* must use, because a name is not a run. Without a key, the newest row that is not an uninstall — good enough
+ * for enrichment (a failure message's context, the folder a deployment
+ * landed in), never for vouching that a run finished: a name outlives its
+ * generations, the first row the search returns can be the pre-upgrade one,
+ * and an `Uninstall` row is the record of a deployment that is gone.
+ */
+export declare function findDeploymentBestEffort(auth: SolutionAuthContext, deploymentName: string, scope?: InitOverrideFunction, prefer?: DeploymentRowPreference): Promise<DeploymentSearchItemDto2 | undefined>;
+/** The most recently created of a name's rows, uninstall rows included. */
+export declare function newestDeploymentRow(rows: DeploymentSearchItemDto2[]): DeploymentSearchItemDto2 | undefined;
 /**
  * The pipelines service `pipelinesGetPipelineDeploymentStatus` endpoint
  * returns 404 with errorCode `PipelineDeploymentNotFound` once a deployment
@@ -129,28 +198,12 @@ export type DeployPollRecovery = {
     operationStatus: DeploymentOperationStatus;
 };
 export declare function interpretFailedDeployPoll(deployment: DeploymentSearchItemDto2 | undefined): DeployPollRecovery | undefined;
-/**
- * Has a freshly created deployment finished moving? Answers the question
- * `deploy run --wait` asks on every poll.
- *
- * `Draft` is deliberately *not* settled here, even though
- * {@link mapOperationStatusToPipelineStatus} maps it to `DeploymentFailed`.
- * The two are asked about different moments. That mapper answers for a
- * deployment whose install was already observed running, so a Draft record
- * there means the install never completed. The `--wait` poll starts before the
- * install does, and the pipeline parks a new deployment in `Draft` until it
- * promotes it to `InProgress` — so reading Draft as a verdict reported a
- * healthy Personal Workspace deploy as failed seconds after starting it. Same
- * reasoning as the `Draft` note in {@link interpretFailedDeployPoll}: a Draft
- * that never moves is caught by the poll timeout instead.
- */
-export declare function isSettledDeployOperationStatus(operationStatus: DeploymentOperationStatus | undefined | null): boolean;
 /**
  * Map a search-service `DeploymentOperationStatus` onto the corresponding
  * terminal `PipelineDeploymentStatus`. Returns undefined for non-terminal
  * states (caller should keep polling).
  */
-export declare function mapOperationStatusToPipelineStatus(operationStatus: DeploymentOperationStatus | undefined | null): PipelineDeploymentStatus | undefined;
+export declare function mapOperationStatusToPipelineStatus(operationStatus: DeploymentOperationStatus | string | undefined | null): PipelineDeploymentStatus | undefined;
 /**
  * Build a synthesized terminal `PipelineDeploymentResult` from a deployment
  * record fetched via the search API. Used as a fallback when the pipelines