@go-to-k/cdkd 0.284.38 → 0.284.40

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { $ as startInterruptWatch, $t as buildAssetRedirectMap, A as renderStatefulReason, An as resolveStateBucketWithDefaultAndSource, At as redactSecretsForState, B as exportAliasCollisionScrubWarning, Bn as PARTITION_TABLE, Bt as DiffCalculator, C as isFinalSnapshotError, Cn as getDefaultStateBucketName, Cr as isRetryableTransientError, Ct as TEMPLATE_SOURCED_RULES, D as extractDeploymentEventError, Dn as resolveCaptureObservedState, Dt as isSingleDynamicReferenceToken, E as makeCanonicalizePropertiesFn, En as resolveAutoAssetStorage, Et as errorCauseChain, F as green, Fn as CFN_TEMPLATE_URL_LIMIT, Ft as s3BucketDomainName, G as collectInlinePolicyNamesManagedBySiblings, Gt as TemplateParser, H as secretBearingStateKeyWarning, Hn as derivePartitionAndUrlSuffix, Ht as describeTypeWithThrottleRetry, I as red, In as MIGRATE_TMP_PREFIX, It as s3BucketDualStackDomainName, J as findActionableSilentDrops, Jn as getAwsClients, Jt as rebuildClientForBucketRegion, K as clearOnUpdateRemoval, Kn as resolveBucketRegion, Kt as LockManager, L as yellow, Ln as findLargeInlineResources, Lt as s3BucketRegionalDomainName, M as bold, Mn as stateBucketExistenceConfirmed, Mt as classifyReplaySecretRegion, N as cyan, Nn as warnDeprecatedNoPrefixCliFlag, Nt as producerRegionsFromState, O as MULTI_REGION_RECREATE_BLOCKED_TYPES, On as resolveSkipPrefix, Ot as maskSecretsInError, P as gray, Pn as CFN_TEMPLATE_BODY_LIMIT, Pt as s3BucketArn, Q as isInterruptedWaitError, Qn as CdkdError, Qt as WorkGraph, R as collectDeclaredOutputNames, Rn as uploadCfnTemplate, Rt as s3BucketWebsiteUrl, S as createPreDeleteFinalSnapshot, Sn as synthesisStatusMessage, Sr as isMarkedNonRetryable, St as STATE_SOURCED_READBACK_RULES, T as unsupportedFinalSnapshotError, Tn as resolveApp, Tr as markNonRetryable, Tt as dynamicReferenceTokens, U as stateKeySecretExposure, Un as AssemblyReader, Ut as withRetry, V as isExportAliasCollision, Vn as canonicalizeRegion, Vt as INTRINSIC_KEYS, W as IAMRoleProvider, Wn as processStackMessages, Wt as DagBuilder, X as beginCommandInterruptScope, Xn as setAwsClients, Xt as AssetPublisher, Y as findSilentDropProperties, Yn as resetAwsClients, Yt as shouldRetainResource, Z as endCommandInterruptScope, Zt as stringifyValue, _ as computeImplicitDeleteEdges, _n as runDockerForeground, _t as replayWarn, a as DeploymentEventsStore, an as AssetModeResolver, ar as LocalMigrateError, at as carriesDynamicReference, b as buildFinalSnapshotIdentifier, bn as getDockerImageBySourceHash, br as normalizeAwsError, bt as requireConfigString, c as replayFailedOperations, cn as getBootstrapMarkerKey, cr as MissingCdkCliError, ct as refStateLookupFromResource, d as updatePartialReason, dn as validateAssetBucketName, dr as ProvisioningError, dt as resolveExplicitPhysicalId, en as createAssetRedirectResolver, er as CrossAccountSecretRefusalError, et as CloudControlProvider, f as UNSPECIFIED_SKIP_REASON, fn as validateContainerRepoName, fr as ResourceTimeoutError, ft as assertRegionMatch, g as IMPLICIT_DELETE_DEPENDENCIES, gn as getDockerCmd, gt as readConfigString, h as maskingRetryLogger, hn as formatDockerLoginError, hr as StackTerminationProtectionError, ht as configStringRefusal, i as DeploymentEventsReader, in as stripControlChars, ir as LocalInvokeBuildError$1, it as IntrinsicFunctionResolver, j as formatResourceLine, jn as resolveUseCdkBootstrapAssets, jt as scrubResourceRecord, k as isStatefulRecreateTargetSync, kn as resolveStateBucketWithDefault, kt as maskSecretsInText, l as replayRollback, ln as parseBootstrapMarker, lr as NestedStackChildDirectDestroyError, lt as WAFv2WebACLProvider, m as withResourceDeadline, mn as buildDockerImage, mr as StackHasActiveImportsError, mt as configBooleanRefusal, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nn as rewriteTemplateAssetReferences, nr as DeployCancelledError, nt as disableInstanceApiTermination, o as planFailedOps, on as BOOTSTRAP_MARKER_PREFIX, or as LocalStartServiceError, ot as cfnRefValueFromPhysicalId, p as deleteSkipReason, pn as buildDenyExternalAccessPolicy, pr as ResourceUpdateNotSupportedError, pt as coerceCfnBoolean, q as ProviderRegistry, qn as AwsClients, qt as S3StateBackend, r as DeployEngine, rn as escapeRegExp, rr as DynamicReferenceRegionAmbiguousError, rt as isTerminationProtectionPropagationError, s as planRollback, sn as ensureAssetStorage, st as getAccountInfo, t as DEFAULT_RESOURCE_TIMEOUT_MS, tn as loadPublishableAssetManifest, tt as slowCcOperationTimeoutMs, u as updatePartialMessage, un as readBootstrapMarkerBody, ur as PartialFailureError, ut as normalizeAwsTagsToCfn, v as ATOMIC_FINAL_SNAPSHOT_TYPES, vn as runDockerStreaming, vt as requireConfigArray, w as refusesFinalSnapshot, wn as getLegacyStateBucketName, wr as isThrottlingError, wt as createSecretMasker, x as ccRoutedFinalSnapshotError, xn as Synthesizer, xr as withErrorHandling, xt as STATE_SOURCED_CROSS_GENERATION_RULES, y as PRE_DELETE_SNAPSHOT_TYPES, yn as AssetManifestLoader, yt as requireConfigObject, z as collectPublishedOutputNames, zn as expectedOwnerParam, zt as applyRoleArnIfSet } from "./deploy-engine-DyxASW-O.js";
+import { $ as startInterruptWatch, $n as CdkdError, $t as WorkGraph, A as renderStatefulReason, An as resolveStateBucketWithDefault, At as redactSecretsForState, B as exportAliasCollisionScrubWarning, Bn as expectedOwnerParam, Bt as DiffCalculator, C as isFinalSnapshotError, Cn as synthesisStatusMessage, Cr as isMarkedNonRetryable, Ct as TEMPLATE_SOURCED_RULES, D as extractDeploymentEventError, Dn as resolveAutoAssetStorage, Dt as isSingleDynamicReferenceToken, E as makeCanonicalizePropertiesFn, En as resolveApp, Er as markNonRetryable, Et as errorCauseChain, F as green, Fn as CFN_TEMPLATE_BODY_LIMIT, Ft as s3BucketDomainName, G as collectInlinePolicyNamesManagedBySiblings, Gn as processStackMessages, Gt as TemplateParser, H as secretBearingStateKeyWarning, Hn as canonicalizeRegion, Ht as describeTypeWithThrottleRetry, I as red, In as CFN_TEMPLATE_URL_LIMIT, It as s3BucketDualStackDomainName, J as findActionableSilentDrops, Jn as AwsClients, Jt as S3StateBackend, K as clearOnUpdateRemoval, Kt as LockManager, L as yellow, Ln as MIGRATE_TMP_PREFIX, Lt as s3BucketRegionalDomainName, M as bold, Mn as resolveUseCdkBootstrapAssets, Mt as classifyReplaySecretRegion, N as cyan, Nn as stateBucketExistenceConfirmed, Nt as producerRegionsFromState, O as MULTI_REGION_RECREATE_BLOCKED_TYPES, On as resolveCaptureObservedState, Ot as maskSecretsInError, P as gray, Pn as warnDeprecatedNoPrefixCliFlag, Pt as s3BucketArn, Q as isInterruptedWaitError, Qt as stringifyValue, R as collectDeclaredOutputNames, Rn as findLargeInlineResources, Rt as s3BucketWebsiteUrl, S as createPreDeleteFinalSnapshot, Sn as Synthesizer, Sr as withErrorHandling, St as STATE_SOURCED_READBACK_RULES, T as unsupportedFinalSnapshotError, Tn as getLegacyStateBucketName, Tr as isThrottlingError, Tt as dynamicReferenceTokens, U as stateKeySecretExposure, Un as derivePartitionAndUrlSuffix, Ut as withRetry, V as isExportAliasCollision, Vn as PARTITION_TABLE, Vt as INTRINSIC_KEYS, W as IAMRoleProvider, Wn as AssemblyReader, Wt as DagBuilder, X as beginCommandInterruptScope, Xn as resetAwsClients, Xt as shouldRetainResource, Y as findSilentDropProperties, Yn as getAwsClients, Yt as rebuildClientForBucketRegion, Z as endCommandInterruptScope, Zn as setAwsClients, Zt as AssetPublisher, _ as computeImplicitDeleteEdges, _n as getDockerCmd, _t as replayWarn, a as DeploymentEventsStore, an as stripControlChars, ar as LocalInvokeBuildError$1, at as carriesDynamicReference, b as buildFinalSnapshotIdentifier, bn as AssetManifestLoader, bt as requireConfigString, c as replayFailedOperations, cn as ensureAssetStorage, ct as refStateLookupFromResource, d as updatePartialReason, dn as readBootstrapMarkerBody, dr as PartialFailureError, dt as resolveExplicitPhysicalId, en as buildAssetRedirectMap, et as CloudControlProvider, f as UNSPECIFIED_SKIP_REASON, fn as validateAssetBucketName, fr as ProvisioningError, ft as assertRegionMatch, g as IMPLICIT_DELETE_DEPENDENCIES, gn as formatDockerLoginError, gr as StackTerminationProtectionError, gt as readConfigString, h as maskingRetryLogger, hn as buildDockerImage, hr as StackHasActiveImportsError, ht as configStringRefusal, i as DeploymentEventsReader, in as escapeRegExp, ir as DynamicReferenceRegionAmbiguousError, it as IntrinsicFunctionResolver, j as formatResourceLine, jn as resolveStateBucketWithDefaultAndSource, jt as scrubResourceRecord, k as isStatefulRecreateTargetSync, kn as resolveSkipPrefix, kt as maskSecretsInText, l as replayRollback, ln as getBootstrapMarkerKey, lr as MissingCdkCliError, lt as WAFv2WebACLProvider, m as withResourceDeadline, mn as buildDenyExternalAccessPolicy, mr as ResourceUpdateNotSupportedError, mt as configBooleanRefusal, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nn as loadPublishableAssetManifest, nt as disableInstanceApiTermination, o as planFailedOps, on as AssetModeResolver, or as LocalMigrateError, ot as cfnRefValueFromPhysicalId, p as deleteSkipReason, pn as validateContainerRepoName, pr as ResourceTimeoutError, pt as coerceCfnBoolean, q as ProviderRegistry, qn as resolveBucketRegion, qt as displaySafe, r as DeployEngine, rn as rewriteTemplateAssetReferences, rr as DeployCancelledError, rt as isTerminationProtectionPropagationError, s as planRollback, sn as BOOTSTRAP_MARKER_PREFIX, sr as LocalStartServiceError, st as getAccountInfo, t as DEFAULT_RESOURCE_TIMEOUT_MS, tn as createAssetRedirectResolver, tr as CrossAccountSecretRefusalError, tt as slowCcOperationTimeoutMs, u as updatePartialMessage, un as parseBootstrapMarker, ur as NestedStackChildDirectDestroyError, ut as normalizeAwsTagsToCfn, v as ATOMIC_FINAL_SNAPSHOT_TYPES, vn as runDockerForeground, vt as requireConfigArray, w as refusesFinalSnapshot, wn as getDefaultStateBucketName, wr as isRetryableTransientError, wt as createSecretMasker, x as ccRoutedFinalSnapshotError, xn as getDockerImageBySourceHash, xr as normalizeAwsError, xt as STATE_SOURCED_CROSS_GENERATION_RULES, y as PRE_DELETE_SNAPSHOT_TYPES, yn as runDockerStreaming, yt as requireConfigObject, z as collectPublishedOutputNames, zn as uploadCfnTemplate, zt as applyRoleArnIfSet } from "./deploy-engine-B3MQFW1K.js";
 import { a as getLiveRenderer, c as PATTERN_B_RESOURCE_TYPES, d as generateResourceNameWithFallback, f as getCurrentStackName, h as withStackName, i as runStackBuffered, m as withSkipPrefix, n as getLogger, o as PATTERN_B_NAME_OPTIONS, s as PATTERN_B_NAME_PROPERTIES, u as generateResourceName } from "./logger-zRrlbaQt.js";
-import { t as ASGProvider } from "./asg-provider-kqBWElNc.js";
+import { t as ASGProvider } from "./asg-provider-BeKDzUe9.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { CopyObjectCommand, CreateBucketCommand, DeleteBucketAnalyticsConfigurationCommand, DeleteBucketCommand, DeleteBucketCorsCommand, DeleteBucketEncryptionCommand, DeleteBucketIntelligentTieringConfigurationCommand, DeleteBucketInventoryConfigurationCommand, DeleteBucketLifecycleCommand, DeleteBucketMetricsConfigurationCommand, DeleteBucketOwnershipControlsCommand, DeleteBucketPolicyCommand, DeleteBucketReplicationCommand, DeleteBucketTaggingCommand, DeleteBucketWebsiteCommand, DeleteObjectsCommand, GetBucketAccelerateConfigurationCommand, GetBucketCorsCommand, GetBucketEncryptionCommand, GetBucketLifecycleConfigurationCommand, GetBucketLocationCommand, GetBucketLoggingCommand, GetBucketNotificationConfigurationCommand, GetBucketOwnershipControlsCommand, GetBucketPolicyCommand, GetBucketReplicationCommand, GetBucketTaggingCommand, GetBucketVersioningCommand, GetBucketWebsiteCommand, GetObjectCommand, GetObjectLockConfigurationCommand, GetPublicAccessBlockCommand, HeadBucketCommand, ListBucketAnalyticsConfigurationsCommand, ListBucketIntelligentTieringConfigurationsCommand, ListBucketInventoryConfigurationsCommand, ListBucketMetricsConfigurationsCommand, ListObjectVersionsCommand, ListObjectsV2Command, NoSuchBucket, PutBucketAccelerateConfigurationCommand, PutBucketAnalyticsConfigurationCommand, PutBucketCorsCommand, PutBucketEncryptionCommand, PutBucketIntelligentTieringConfigurationCommand, PutBucketInventoryConfigurationCommand, PutBucketLifecycleConfigurationCommand, PutBucketLoggingCommand, PutBucketMetricsConfigurationCommand, PutBucketNotificationConfigurationCommand, PutBucketOwnershipControlsCommand, PutBucketPolicyCommand, PutBucketReplicationCommand, PutBucketTaggingCommand, PutBucketVersioningCommand, PutBucketWebsiteCommand, PutObjectCommand, PutObjectLockConfigurationCommand, PutPublicAccessBlockCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
@@ -77,6 +77,23 @@ import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { WebSocketServer } from "ws";
 
+//#region src/state/state-prefix.ts
+/**
+* The default S3 key prefix for cdkd state.
+*
+* Homed in the STATE layer rather than in `src/cli/commands/state-file-keys.ts`
+* (which re-exports it, so its four existing importers are unchanged) because
+* `src/state/lock-contention-message.ts` needs it to decide whether a recovery
+* hint should spell `--state-prefix` at all, and a `src/state/**` module
+* importing from `src/cli/commands/**` inverts the layering — the CLI sits
+* ABOVE the state layer in the 7-layer architecture, not below it.
+*
+* Note this is only the DEFAULT. Other commands accept `--state-prefix`, so
+* whole-bucket listings deliberately do not scope to it.
+*/
+const DEFAULT_STATE_PREFIX = "cdkd";
+
+//#endregion
 //#region src/cli/commands/state-file-keys.ts
 /**
 * Shared helpers for enumerating and describing cdkd state-bucket keys.
@@ -94,20 +111,6 @@ import { WebSocketServer } from "ws";
 */
 const STATE_FILE_SUFFIX = "/state.json";
 /**
-* The prefix `cdkd bootstrap` writes under, and the one `gc` /
-* `bootstrap --destroy` configure their own state backend with.
-*
-* Shared here rather than spelled per command for the same reason this module
-* exists at all: `bootstrap-destroy.ts` and `gc.ts` each held their own copy,
-* and it is now also the `knownPrefix` argument to {@link describeStateKey},
-* where a copy that drifted from the backend's actual prefix would silently
-* send every key back to the shape heuristic instead of the exact depth rule.
-*
-* Note this is only the DEFAULT. Other commands accept `--state-prefix`, so
-* the whole-bucket listings deliberately do not scope to it.
-*/
-const DEFAULT_STATE_PREFIX = "cdkd";
-/**
 * Segments left under a known prefix for the legacy `{prefix}/{stack}` layout.
 *
 * The twin of `S3StateBackend`'s `LEGACY_KEY_DEPTH`, which counts the
@@ -23916,9 +23919,10 @@ const generations = /* @__PURE__ */ new Map();
 * long-lived process cannot grow the map without bound.
 */
 const MAX_TRACKED_GENERATIONS = 1e5;
-const tokenKey = (scope, logicalId) => `${scope}\u0000${process.env["AWS_REGION"] ?? ""}\u0000${getCurrentStackName() ?? ""}\u0000${logicalId}`;
-const derive = (key, generation, maxLength) => {
-	return `cdkd-${createHash("sha256").update(`${PROCESS_NONCE}\u0000${key}\u0000${generation}`).digest("hex")}`.slice(0, maxLength);
+const tokenKey = (scope, logicalId, maxLength, charset) => `${scope}\u0000${process.env["AWS_REGION"] ?? ""}\u0000${getCurrentStackName() ?? ""}\u0000${logicalId}\u0000${maxLength}\u0000${charset}`;
+const derive = (key, generation, maxLength, charset) => {
+	const digest = createHash("sha256").update(`${PROCESS_NONCE}\u0000${key}\u0000${generation}`).digest("hex");
+	return `cdkd${charset === "alphanumeric" ? "" : "-"}${digest}`.slice(0, maxLength);
 };
 /**
 * Get the idempotency token for one logical create, minting it on first use and
@@ -23932,10 +23936,10 @@ const derive = (key, generation, maxLength) => {
 * ```
 */
 function acquireIdempotencyToken(options) {
-	const { scope, logicalId, maxLength = 64 } = options;
-	const key = tokenKey(scope, logicalId);
+	const { scope, logicalId, maxLength = 64, charset = "default" } = options;
+	const key = tokenKey(scope, logicalId, maxLength, charset);
 	const existing = inFlight.get(key);
-	const value = existing ?? derive(key, generations.get(key) ?? 0, maxLength);
+	const value = existing ?? derive(key, generations.get(key) ?? 0, maxLength, charset);
 	if (existing === void 0) inFlight.set(key, value);
 	return {
 		value,
@@ -58162,6 +58166,104 @@ var ECRProvider = class {
 	}
 };
 
+//#endregion
+//#region src/state/lock-contention-message.ts
+/**
+* The message every fail-fast lock-contention site raises.
+*
+* Issue #2161 made six commands throw on `acquireLock` returning `false`
+* instead of running under a foreign lock. Issue #2170 is the follow-up: the
+* message those sites raise asked the user to decide "is another process
+* active?" while printing none of the evidence that would answer it, and the
+* recovery command it suggested could resolve against the wrong AWS account.
+*
+* Both matter more than they look, because of WHICH locks reach this message.
+* `LockManager.acquireLock` reaps an EXPIRED foreign lock and retries, so a
+* `false` return means the lock is LIVE — in practice a running `cdkd deploy`.
+* The user who follows a bare `cdkd force-unlock <stack>` suggestion therefore
+* deletes a live owner's lock and reproduces issue #2161's harm by hand, which
+* is the outcome #2161 exists to prevent.
+*
+* Centralising the text here also settles the third finding: the nine sites
+* had drifted to three spellings (`for stack` / `for nested stack` /
+* `for nested-stack child`), so a user grepping CI logs for one of them found
+* two of three. `subject` now varies only the noun.
+*/
+/**
+* Stand-in for a value with nothing renderable left after sanitization. Named
+* rather than inlined so the message and the command-suppression branch cannot
+* disagree about what "unrenderable" looks like.
+*/
+const UNRENDERABLE = "<unrenderable>";
+/** Render `expiresIn` without implying more precision than a clock skew allows. */
+function formatRemaining(ms) {
+	if (!Number.isFinite(ms)) return "at an unknown time";
+	if (ms <= 0) return "already expired";
+	const minutes = Math.round(ms / 6e4);
+	if (minutes < 1) return "in under a minute";
+	return `in ~${minutes}m`;
+}
+function shellQuote(value) {
+	return /^[A-Za-z0-9._/@:+-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* The `cdkd force-unlock ...` line, carrying every flag that decides which
+* lock object it resolves to.
+*/
+function buildForceUnlockCommand(stackName, region, recovery) {
+	const safeStack = displaySafe(stackName, { asciiOnly: true });
+	const stackIsExact = safeStack === stackName;
+	const safeRegion = region === void 0 ? void 0 : displaySafe(region, { asciiOnly: true });
+	if (!safeStack || safeRegion === "" || !stackIsExact || !(region === void 0 || safeRegion === region)) return "";
+	const parts = [safeRegion === void 0 ? `cdkd force-unlock ${shellQuote(safeStack)}` : `cdkd force-unlock ${shellQuote(safeStack)} --stack-region ${shellQuote(safeRegion)}`];
+	if (recovery?.profile) parts.push(`--profile ${shellQuote(recovery.profile)}`);
+	if (recovery?.stateBucket) parts.push(`--state-bucket ${shellQuote(recovery.stateBucket)}`);
+	if (recovery?.statePrefix && recovery.statePrefix !== "cdkd") parts.push(`--state-prefix ${shellQuote(recovery.statePrefix)}`);
+	return parts.join(" ");
+}
+/**
+* The force-quit banner's recovery sentence.
+*
+* Exported so the two `destroy-runner.ts` banners do not each decide what to
+* say when {@link buildForceUnlockCommand} suppresses — a banner ending in a
+* bare `run: ` is the shape the review found, and two copies of the branch is
+* how the next one drifts. Returns a leading-space clause so the caller can
+* concatenate it unconditionally.
+*/
+function forceQuitRecoveryClause(stackName, region, recovery) {
+	const command = buildForceUnlockCommand(stackName, region, recovery);
+	return command ? ` If the next run reports a lock, run: ${command}` : " Inspect the lock object directly: the name or region recorded for this stack cannot be reproduced safely on a command line, so any command shown here would address a different lock.";
+}
+/**
+* Build the contention message, reading the holder's identity best-effort.
+*
+* The `getLockInfo` read is one GetObject and is deliberately NOT allowed to
+* fail the command: the caller is already on its way to throwing, and turning
+* a contention refusal into an S3 error would lose the reason. A failed or
+* absent read degrades to the evidence-free wording rather than to a crash.
+*/
+async function buildLockContentionMessage(args) {
+	const { lockManager, stackName, region, subject = "stack", recovery, heldClause, suffix } = args;
+	let held = heldClause ?? "another cdkd process holds it";
+	let sawHolder = false;
+	try {
+		const info = await lockManager.getLockInfo(stackName, region);
+		if (info) {
+			const operation = info.operation ? `, operation: ${displaySafe(info.operation)}` : "";
+			const expires = formatRemaining(info.expiresAt - Date.now());
+			const owner = displaySafe(info.owner);
+			const holder = owner ? `held by ${owner}${operation}` : `held by an unnamed holder`;
+			held = `${heldClause ? `${heldClause} — ` : ""}${holder}, expires ${expires}`;
+			if (owner) sawHolder = true;
+		}
+	} catch {}
+	const advice = sawHolder ? `That process is still running — wait for it to finish. Only if you are certain it is gone` : `Wait for it to finish, or if you are certain no other process is active`;
+	const recoveryCommand = buildForceUnlockCommand(stackName, region, recovery);
+	const head = `Could not acquire lock for ${subject} '${displaySafe(stackName, { asciiOnly: true }) || "<unrenderable>"}' (${displaySafe(region, { asciiOnly: true }) || "<unrenderable>"}) — ${held}.` + (suffix ? ` ${suffix}` : "");
+	if (!recoveryCommand) return `${head} ${advice}. No recovery command can be shown: the name or region recorded for this lock contains characters that cannot be reproduced safely on a command line, so any command shown here would address a different lock — inspect the lock object directly.`;
+	return `${head} ${advice}, run: ${recoveryCommand}`;
+}
+
 //#endregion
 //#region src/cli/commands/destroy-runner.ts
 /**
@@ -58298,9 +58400,64 @@ async function runDestroyForStack(stackName, state, ctx) {
 	const regionForState = state.region ?? ctx.baseRegion;
 	if (resourceCount === 0) {
 		logger.info(`Stack ${stackName} has no resources, cleaning up state...`);
-		await ctx.stateBackend.deleteState(stackName, regionForState);
-		logger.info(`${green("✓")} State deleted`);
+		let emptyLockHeld = false;
+		let emptyInterrupted = false;
+		const emptySigintHandler = () => {
+			if (emptyInterrupted) {
+				if (emptyLockHeld) {
+					ctx.lockManager.releaseLock(stackName, regionForState).catch(() => {});
+					process.stderr.write(`\nForce-quit: stack lock may not be released.${forceQuitRecoveryClause(stackName, regionForState, {
+						profile: ctx.profile,
+						stateBucket: ctx.stateBucket,
+						statePrefix: ctx.statePrefix
+					})}\n`);
+				}
+				process.exit(130);
+			}
+			emptyInterrupted = true;
+			try {
+				process.stderr.write(`\nInterrupt received - finishing the state cleanup for ${stackName} (press Ctrl-C again to force-quit)\n`);
+			} catch {}
+		};
+		process.setMaxListeners(Math.max(process.getMaxListeners(), 100));
+		process.on("SIGINT", emptySigintHandler);
+		let emptyAcquired;
+		try {
+			emptyAcquired = await ctx.lockManager.acquireLock(stackName, regionForState, void 0, "destroy");
+		} catch (acquireErr) {
+			process.removeListener("SIGINT", emptySigintHandler);
+			throw acquireErr;
+		}
+		if (!emptyAcquired) {
+			process.removeListener("SIGINT", emptySigintHandler);
+			throw new Error(await buildLockContentionMessage({
+				lockManager: ctx.lockManager,
+				stackName,
+				region: regionForState,
+				recovery: {
+					profile: ctx.profile,
+					stateBucket: ctx.stateBucket,
+					statePrefix: ctx.statePrefix
+				}
+			}));
+		}
+		emptyLockHeld = true;
+		try {
+			const recheck = await ctx.stateBackend.getState(stackName, regionForState);
+			if (!(!recheck || Object.keys(recheck.state.resources).length === 0)) throw new Error(`Stack '${stackName}' (${regionForState}) was empty when this run started but now has ${Object.keys(recheck.state.resources).length} resource(s) — another cdkd process deployed into it. Re-run the destroy to act on the current state.`);
+			await ctx.stateBackend.deleteState(stackName, regionForState);
+			logger.info(`${green("✓")} State deleted`);
+		} finally {
+			try {
+				await ctx.lockManager.releaseLock(stackName, regionForState);
+			} catch (releaseErr) {
+				logger.warn(`Failed to release lock after empty-state cleanup: ${releaseErr instanceof Error ? releaseErr.message : String(releaseErr)}`);
+			} finally {
+				process.removeListener("SIGINT", emptySigintHandler);
+			}
+		}
 		result.skippedEmpty = true;
+		result.interrupted ||= emptyInterrupted;
 		return result;
 	}
 	const needsStrongRefCheck = !!(state.outputs && Object.keys(state.outputs).length > 0);
@@ -58377,7 +58534,11 @@ async function runDestroyForStack(stackName, state, ctx) {
 		if (draining) {
 			if (lockHeld) {
 				ctx.lockManager.releaseLock(stackName, regionForState).catch(() => {});
-				process.stderr.write(`\nForce-quit: stack lock may not be released. If the next run reports a lock, run: cdkd force-unlock ${stackName}\n`);
+				process.stderr.write(`\nForce-quit: stack lock may not be released.${forceQuitRecoveryClause(stackName, regionForState, {
+					profile: ctx.profile,
+					stateBucket: ctx.stateBucket,
+					statePrefix: ctx.statePrefix
+				})}\n`);
 			}
 			process.exit(130);
 		}
@@ -58390,7 +58551,16 @@ async function runDestroyForStack(stackName, state, ctx) {
 	process.on("SIGINT", sigintHandler);
 	try {
 		logger.info(`\nAcquiring lock for stack ${stackName}...`);
-		if (!await ctx.lockManager.acquireLock(stackName, regionForState, void 0, "destroy")) throw new Error(`Could not acquire lock for stack '${stackName}' (${regionForState}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${stackName} --stack-region ${regionForState}' if you are certain no other process is active.`);
+		if (!await ctx.lockManager.acquireLock(stackName, regionForState, void 0, "destroy")) throw new Error(await buildLockContentionMessage({
+			lockManager: ctx.lockManager,
+			stackName,
+			region: regionForState,
+			recovery: {
+				profile: ctx.profile,
+				stateBucket: ctx.stateBucket,
+				statePrefix: ctx.statePrefix
+			}
+		}));
 	} catch (error) {
 		restoreBaseRegionAndClients();
 		process.removeListener("SIGINT", sigintHandler);
@@ -58984,6 +59154,7 @@ var NestedStackProvider = class {
 			skipConfirmation: true,
 			...ctx.exportIndexStore && { exportIndexStore: ctx.exportIndexStore },
 			...ctx.destroyOptions?.profile && { profile: ctx.destroyOptions.profile },
+			...ctx.destroyOptions?.statePrefix !== void 0 && { statePrefix: ctx.destroyOptions.statePrefix },
 			...deleteContext?.removeProtection === true && { removeProtection: true },
 			...(ctx.destroyOptions?.skipFinalSnapshot === true || ctx.options?.skipFinalSnapshot === true) && { skipFinalSnapshot: true },
 			...ctx.destroyOptions?.resourceWarnAfterMs !== void 0 && { resourceWarnAfterMs: ctx.destroyOptions.resourceWarnAfterMs },
@@ -59210,6 +59381,19 @@ function isCertificateInUseError(error) {
 * consumers (CloudFront, ALB) will fail to start if they reach the cert
 * before it issues, but that's the documented trade-off.
 *
+* **A create that fails after requesting DELETES its certificate** (issue
+* [#2169](https://github.com/go-to-k/cdkd/issues/2169)). `RequestCertificate`
+* materializes the certificate immediately and everything after it can fail —
+* most commonly the ISSUED wait, which a DNS-validated certificate whose
+* validation records are not live yet exhausts by construction. Before this,
+* the ARN was thrown away with the error: the certificate existed in AWS with
+* nothing naming it (absent from state, so invisible to `cdkd state show` and
+* unreachable by `cdkd destroy`), and the next `cdkd deploy` requested another
+* one — an orphan per attempt. `create()` now retires the certificate it just
+* requested before re-throwing, so a failed deploy leaves nothing behind and a
+* retry starts clean. See {@link ACMCertificateProvider.cleanupRequestedCertificate}
+* for why deleting is safe and why it is preferred over recording the remnant.
+*
 * **CloudFront cross-region note**: ACM certificates referenced by a
 * CloudFront Distribution MUST live in `us-east-1`. cdkd does not enforce
 * this — it's the developer's responsibility to deploy the certificate
@@ -59259,12 +59443,22 @@ var ACMCertificateProvider = class {
 		if (Object.keys(options).length > 0) input["Options"] = options;
 		const tags = properties["Tags"];
 		if (tags && Array.isArray(tags) && tags.length > 0) input["Tags"] = tags;
+		const idempotencyToken = acquireIdempotencyToken({
+			scope: "RequestCertificate",
+			logicalId,
+			maxLength: 32,
+			charset: "alphanumeric"
+		});
+		input["IdempotencyToken"] = idempotencyToken.value;
+		let requestedArn;
 		try {
 			const certificateArn = (await this.acmClient.send(new RequestCertificateCommand(input))).CertificateArn;
 			if (!certificateArn) throw new ProvisioningError(`RequestCertificate succeeded but no CertificateArn returned for ${logicalId}`, resourceType, logicalId);
+			requestedArn = certificateArn;
 			this.logger.debug(`Requested ACM certificate: ${certificateArn}`);
-			if (!(process.env["CDKD_NO_WAIT"] === "true")) await this.waitForCertificateIssued(certificateArn, logicalId);
+			if (!(process.env["CDKD_NO_WAIT"] === "true")) await this.waitForCertificateIssued(certificateArn, logicalId, resourceType);
 			else this.logger.warn(`Skipping wait for ACM certificate ${logicalId} (CDKD_NO_WAIT=true). Downstream consumers (CloudFront / ALB) will fail until the cert reaches ISSUED.`);
+			idempotencyToken.release();
 			return {
 				physicalId: certificateArn,
 				attributes: {
@@ -59273,9 +59467,84 @@ var ACMCertificateProvider = class {
 				}
 			};
 		} catch (error) {
-			if (error instanceof CdkdError) throw error;
+			const survivorNote = requestedArn ? await this.cleanupRequestedCertificate(requestedArn, logicalId, idempotencyToken) : void 0;
+			if (error instanceof CdkdError) {
+				if (survivorNote === void 0) throw error;
+				throw new ProvisioningError(`${error.message} ${survivorNote}`, resourceType, logicalId, requestedArn, error);
+			}
 			const cause = error instanceof Error ? error : void 0;
-			throw new ProvisioningError(`Failed to create ACM certificate ${logicalId}: ${error instanceof Error ? error.message : String(error)}`, resourceType, logicalId, void 0, cause);
+			throw new ProvisioningError(`Failed to create ACM certificate ${logicalId}: ${error instanceof Error ? error.message : String(error)}` + (survivorNote === void 0 ? "" : ` ${survivorNote}`), resourceType, logicalId, requestedArn, cause);
+		}
+	}
+	/**
+	* Retire the certificate a FAILED `create()` just requested, so the failure
+	* leaves nothing behind (issue
+	* [#2169](https://github.com/go-to-k/cdkd/issues/2169)).
+	*
+	* Returns `undefined` when the certificate is gone, or a one-line note naming
+	* the survivor when it could not be deleted. Never throws: the original
+	* create error is what the user needs to see, and a cleanup failure must
+	* degrade that message rather than replace it.
+	*
+	* ## Why DELETING is right, when the obvious objection is that it throws away
+	* the user's DNS work
+	*
+	* It does not. ACM derives a domain's validation CNAME from the domain and
+	* the account, not from the certificate, and documents that the record "must
+	* be added to your DNS database only once": *"Without the need to repeat
+	* validation, you can request additional ACM certificates for your fully
+	* qualified domain name (FQDN) for as long as the CNAME record remains in
+	* place ... You can also replace a deleted certificate."*
+	* (https://docs.aws.amazon.com/acm/latest/userguide/dns-validation.html)
+	* So the CNAMEs a user adds after seeing this failure validate the NEXT
+	* certificate too, and the retry issues normally. The intuition that a
+	* `PENDING_VALIDATION` certificate is precious does not hold for ACM.
+	*
+	* ## Why not RECORD the remnant in cdkd state instead
+	*
+	* That was this fix's first shape, and it does not work. A state record makes
+	* the next deploy diff the resource as `NO_CHANGE` -- the recorded properties
+	* ARE the template's -- so cdkd would never touch that certificate again:
+	* `cdkd deploy` would print "No changes detected" and exit 0 over a
+	* certificate that is still unusable, and the CloudFront / ALB consuming it
+	* would fail with no explanation. Turning a loud failure into a silent one is
+	* worse than the orphan it fixes. Making the diff re-provision it instead
+	* needs a marker on the state record -- a schema bump -- to buy behaviour
+	* that deleting gives for free.
+	*
+	* ## The "keep it" escape hatch already exists
+	*
+	* A user who WANTS the certificate to outlive the deploy has
+	* `CDKD_NO_WAIT=true` (`cdkd deploy --no-wait`), which returns success with
+	* the certificate recorded in state and never reaches this path. "Wait for
+	* it" and "keep it even if the wait fails" are different requests, and cdkd
+	* already has a flag for the second.
+	*/
+	/**
+	* The region an ACM ARN names, for the manual retire command. Taken from the
+	* ARN rather than from the client so the command a user pastes matches the
+	* certificate it names even when their shell default differs. Falls back to
+	* the literal placeholder for a shape this cannot parse -- a wrong region
+	* would make the command silently address a different account/region.
+	*/
+	regionOfArn(arn) {
+		return arn.split(":")[3] || "<region>";
+	}
+	async cleanupRequestedCertificate(certificateArn, logicalId, idempotencyToken) {
+		try {
+			await this.acmClient.send(new DeleteCertificateCommand({ CertificateArn: certificateArn }));
+			this.logger.info(`Deleted the ACM certificate ${certificateArn} that the failed create of ${logicalId} requested, so nothing is left behind. DNS validation records you have already added stay valid for the retry.`);
+			idempotencyToken.release();
+			return;
+		} catch (cleanupError) {
+			if (cleanupError instanceof ResourceNotFoundException$7 || cleanupError instanceof Error && cleanupError.name === "ResourceNotFoundException") {
+				this.logger.info(`The ACM certificate ${certificateArn} that the failed create of ${logicalId} requested was already gone; nothing to clean up.`);
+				idempotencyToken.release();
+				return;
+			}
+			const detail = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+			this.logger.warn(`Could not delete the ACM certificate ${certificateArn} that the failed create of ${logicalId} requested: ${detail}`);
+			return `The certificate ${certificateArn} this attempt created could NOT be deleted, and cdkd is not tracking it -- retire it with \`aws acm delete-certificate --certificate-arn ${certificateArn} --region ${this.regionOfArn(certificateArn)}\` (the reason is in the warning above).`;
 		}
 	}
 	async update(logicalId, physicalId, resourceType, properties, previousProperties) {
@@ -59448,11 +59717,25 @@ var ACMCertificateProvider = class {
 	* Throws on `VALIDATION_TIMED_OUT` / `FAILED` (terminal failures) and on
 	* polling-cap exhaustion (treated as timeout). SIGINT short-circuits the
 	* loop and returns control to the deploy engine's cleanup path.
+	*
+	* Both throws are `ProvisioningError`s carrying `certificateArn` as their
+	* `physicalId` (issue
+	* [#2169](https://github.com/go-to-k/cdkd/issues/2169)). They used to be
+	* plain `Error`s whose only reference to the certificate was the message
+	* TEXT, which is not something a caller can act on. The certificate is real
+	* by the time either fires, so the error that reports the failure is the one
+	* piece of the failure path that should still be able to name it.
+	*
+	* Says nothing about what happens to the certificate afterwards: the caller
+	* owns that. `create()`'s catch retires it (see
+	* {@link ACMCertificateProvider.cleanupRequestedCertificate}) and appends a
+	* note to this message only when that cleanup could NOT.
 	*/
-	async waitForCertificateIssued(certificateArn, logicalId) {
+	async waitForCertificateIssued(certificateArn, logicalId, resourceType) {
 		this.logger.debug(`Waiting for ACM certificate ${certificateArn} to reach ISSUED status...`);
 		let interrupted = false;
-		let validationOptionsLogged = false;
+		/** The last validation-record block printed, so we re-print only on a CHANGE. */
+		let lastValidationOptions;
 		const sigintHandler = () => {
 			interrupted = true;
 		};
@@ -59470,17 +59753,20 @@ var ACMCertificateProvider = class {
 					this.logger.debug(`ACM certificate ${certificateArn} is ISSUED`);
 					return;
 				}
-				if (status === "FAILED" || status === "VALIDATION_TIMED_OUT" || status === "INACTIVE" || status === "REVOKED" || status === "EXPIRED") throw new Error(`ACM certificate ${logicalId} (${certificateArn}) entered terminal status ${status} during validation. Check ACM console / DNS records to diagnose.`);
-				if (status === "PENDING_VALIDATION" && !validationOptionsLogged && validations.length > 0) {
-					this.logValidationOptions(validations);
-					validationOptionsLogged = true;
+				if (status === "FAILED" || status === "VALIDATION_TIMED_OUT" || status === "INACTIVE" || status === "REVOKED" || status === "EXPIRED") throw new ProvisioningError(`ACM certificate ${logicalId} (${certificateArn}) entered terminal status ${status} during validation. Check ACM console / DNS records to diagnose.`, resourceType, logicalId, certificateArn);
+				if (status === "PENDING_VALIDATION") {
+					const rendered = this.renderValidationOptions(validations);
+					if (rendered !== void 0 && rendered !== lastValidationOptions) {
+						this.logger.info(rendered);
+						lastValidationOptions = rendered;
+					}
 				}
 				this.logger.debug(`ACM certificate ${certificateArn} status: ${status} (attempt ${attempt}/${this.maxPollAttempts})`);
 				const sleepEnd = Date.now() + this.pollIntervalMs;
 				const tickMs = Math.min(1e3, this.pollIntervalMs);
 				while (Date.now() < sleepEnd && !interrupted) await new Promise((resolve) => setTimeout(resolve, tickMs));
 			}
-			throw new Error(`ACM certificate ${logicalId} (${certificateArn}) did not reach ISSUED status within ${this.maxPollAttempts * this.pollIntervalMs / 1e3}s. If your DNS zone is manually managed, you may need to increase --resource-timeout AWS::CertificateManager::Certificate=<duration> or set CDKD_NO_WAIT=true.`);
+			throw new ProvisioningError(`ACM certificate ${logicalId} (${certificateArn}) did not reach ISSUED status within ${this.maxPollAttempts * this.pollIntervalMs / 1e3}s. ` + (lastValidationOptions === void 0 ? "AWS had not published this certificate's validation records before the wait ran out, so none were printed — re-run the deploy to request them again. " : `Add the validation records printed above to your DNS zone and re-run the deploy. `) + "ACM reuses a domain's validation CNAME across certificates, so records you add now validate the next attempt. To wait LONGER, raise CDKD_ACM_POLL_ATTEMPTS / CDKD_ACM_POLL_INTERVAL_MS — this cap is the provider's OWN and is what just fired; --resource-timeout alone will not lengthen it. Past ~30m also raise --resource-timeout AWS::CertificateManager::Certificate=<duration>, or the engine's per-resource deadline becomes the shorter of the two. Or set CDKD_NO_WAIT=true to keep the certificate and validate it out of band.", resourceType, logicalId, certificateArn);
 		} finally {
 			process.removeListener("SIGINT", sigintHandler);
 		}
@@ -59490,16 +59776,13 @@ var ACMCertificateProvider = class {
 	* user can copy / paste them into Route 53 / Cloudflare / etc. while the
 	* cert is still PENDING_VALIDATION.
 	*/
-	logValidationOptions(validations) {
+	renderValidationOptions(validations) {
 		const lines = ["ACM certificate is PENDING_VALIDATION. Add the following DNS records to validate:"];
 		for (const v of validations) if (v.ValidationMethod === "DNS" && v.ResourceRecord) {
 			const r = v.ResourceRecord;
 			lines.push(`  ${v.DomainName} — ${r.Type} ${r.Name} -> ${r.Value}`);
-		} else if (v.ValidationMethod === "EMAIL") {
-			const emails = (v.ValidationEmails ?? []).join(", ");
-			lines.push(`  ${v.DomainName} — confirmation email sent to: ${emails || "<none>"}`);
-		}
-		this.logger.info(lines.join("\n"));
+		} else if (v.ValidationMethod === "EMAIL" && (v.ValidationEmails ?? []).length > 0) lines.push(`  ${v.DomainName} — confirmation email sent to: ${v.ValidationEmails.join(", ")}`);
+		return lines.length === 1 ? void 0 : lines.join("\n");
 	}
 	async updateTags(certificateArn, newTags, oldTags) {
 		const newTagMap = new Map((newTags || []).map((t) => [t.Key, t.Value]));
@@ -59905,7 +60188,7 @@ async function deployCommand(stacks, options) {
 	let deployInterrupted = false;
 	const topLevelSigintHandler = () => {
 		if (deployInterrupted) {
-			process.stderr.write("\nForce-quit: stack locks may not be released. If the next run reports a lock, run: cdkd force-unlock <stackName>\n");
+			process.stderr.write("\nForce-quit: stack locks may not be released. If the next run reports a lock, run this for EACH stack it names (the region-qualified form — see the message that run prints): cdkd force-unlock <stackName> --stack-region <region>\n");
 			process.exit(130);
 		}
 		process.stderr.write("\nInterrupted — waiting for in-progress operations to complete...\n");
@@ -60172,6 +60455,10 @@ async function deployCommand(stacks, options) {
 					dagBuilder,
 					diffCalculator,
 					options: deployEngineOptions,
+					destroyOptions: {
+						statePrefix: options.statePrefix,
+						...options.profile && { profile: options.profile }
+					},
 					...assetRedirect && { assetRedirect }
 				}, () => stackDeployEngine.deploy(stackInfo.stackName, stackInfo.template));
 				logger.info(`\n${bold("Deployment Summary:")}`);
@@ -66142,6 +66429,11 @@ function setAtPath(target, path, value) {
 */
 async function runAccept(reports, stateBackend, stateConfig, awsClients, options) {
 	const logger = getLogger();
+	const lockRecovery = {
+		profile: options.profile,
+		stateBucket: stateConfig.bucket,
+		statePrefix: stateConfig.prefix
+	};
 	printAcceptPlan(reports);
 	if (options.dryRun) {
 		logger.info("--dry-run: state will NOT be written. Re-run without --dry-run to apply.");
@@ -66164,7 +66456,12 @@ async function runAccept(reports, stateBackend, stateConfig, awsClients, options
 			skipped: () => []
 		}));
 		if (driftedOutcomes.length === 0) continue;
-		if (!await lockManager.acquireLock(report.stackName, report.region, owner, "drift-accept")) throw new Error(`Could not acquire lock for stack '${report.stackName}' (${report.region}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${report.stackName} --stack-region ${report.region}' if you are certain no other process is active.`);
+		if (!await lockManager.acquireLock(report.stackName, report.region, owner, "drift-accept")) throw new Error(await buildLockContentionMessage({
+			lockManager,
+			stackName: report.stackName,
+			region: report.region,
+			recovery: lockRecovery
+		}));
 		try {
 			const resources = { ...report.state.resources };
 			for (const outcome of driftedOutcomes) {
@@ -66761,6 +67058,11 @@ function deepEqualUnordered(a, b) {
 */
 async function runRevert(reports, providerRegistry, stateBackend, stateConfig, awsClients, options) {
 	const logger = getLogger();
+	const lockRecovery = {
+		profile: options.profile,
+		stateBucket: stateConfig.bucket,
+		statePrefix: stateConfig.prefix
+	};
 	printRevertPlan(reports);
 	if (options.dryRun) {
 		logger.info("--dry-run: AWS will NOT be modified. Re-run without --dry-run to apply.");
@@ -66788,11 +67090,16 @@ async function runRevert(reports, providerRegistry, stateBackend, stateConfig, a
 			skipped: () => []
 		}));
 		if (driftedOutcomes.length === 0) continue;
-		if (!await lockManager.acquireLock(report.stackName, report.region, owner, "drift-revert")) throw new Error(`Could not acquire lock for stack '${report.stackName}' (${report.region}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${report.stackName} --stack-region ${report.region}' if you are certain no other process is active.`);
+		if (!await lockManager.acquireLock(report.stackName, report.region, owner, "drift-revert")) throw new Error(await buildLockContentionMessage({
+			lockManager,
+			stackName: report.stackName,
+			region: report.region,
+			recovery: lockRecovery
+		}));
 		const narrowedByLogicalId = /* @__PURE__ */ new Map();
-		const revertSecretResolvers = new DriftSecretResolvers(report.region);
-		const revertProducerRegions = producerRegionsFromState(report.state);
 		try {
+			const revertSecretResolvers = new DriftSecretResolvers(report.region);
+			const revertProducerRegions = producerRegionsFromState(report.state);
 			await runWithConcurrency(driftedOutcomes.map((outcome) => async () => {
 				const stateResource = report.state.resources[outcome.logicalId];
 				if (!stateResource) {
@@ -67415,6 +67722,7 @@ async function destroyCommand(stackArgs, options) {
 					exportIndexStore,
 					destroyOptions: {
 						...options.profile && { profile: options.profile },
+						statePrefix: options.statePrefix,
 						...options.removeProtection === true && { removeProtection: true },
 						...options.skipFinalSnapshot === true && { skipFinalSnapshot: true },
 						...options.resourceWarnAfter?.globalMs !== void 0 && { resourceWarnAfterMs: options.resourceWarnAfter.globalMs },
@@ -67430,6 +67738,7 @@ async function destroyCommand(stackArgs, options) {
 					baseRegion: region,
 					...options.profile && { profile: options.profile },
 					stateBucket,
+					statePrefix: options.statePrefix,
 					skipConfirmation: options.yes || options.force,
 					removeProtection: options.removeProtection === true,
 					skipFinalSnapshot: options.skipFinalSnapshot === true,
@@ -69003,6 +69312,11 @@ async function exportCommand(stackArg, options) {
 			bucket: stateBucket,
 			prefix: options.statePrefix
 		};
+		const lockRecovery = {
+			profile: options.profile,
+			stateBucket,
+			statePrefix: options.statePrefix
+		};
 		const stateBackend = new S3StateBackend(awsClients.s3, stateConfig, {
 			...options.region && { region: options.region },
 			...options.profile && { profile: options.profile }
@@ -69078,7 +69392,12 @@ async function exportCommand(stackArg, options) {
 		}
 		const owner = `${process.env["USER"] || "unknown"}@${process.env["HOSTNAME"] || "host"}:${process.pid}`;
 		if (!options.dryRun) {
-			if (!await lockManager.acquireLock(resolvedStackName, targetRegion, owner, "export")) throw new Error(`Could not acquire lock for stack '${resolvedStackName}' (${targetRegion}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${resolvedStackName} --stack-region ${targetRegion}' if you are certain no other process is active.`);
+			if (!await lockManager.acquireLock(resolvedStackName, targetRegion, owner, "export")) throw new Error(await buildLockContentionMessage({
+				lockManager,
+				stackName: resolvedStackName,
+				region: targetRegion,
+				recovery: lockRecovery
+			}));
 		}
 		try {
 			if (nestedStackRows.length > 0) {
@@ -69098,6 +69417,7 @@ async function exportCommand(stackArg, options) {
 				if (missingNested.length > 0) throw new Error(`Template requires parameter(s) without defaults: ${missingNested.join(", ")}. Pass each one as --parameter Key=Value (or set a Default in the CDK code).`);
 				const childOverrides = parseCfnChildStackNameOverrides(options.cfnChildStackName);
 				if ((await runPerStackImportLoop({
+					lockRecovery,
 					rootStackName: resolvedStackName,
 					rootRegion: targetRegion,
 					rootStackInfoNestedTemplates: rootNestedTemplatePaths,
@@ -70994,7 +71314,15 @@ async function runPerStackImportLoop(args) {
 			try {
 				await deps.lockManager.acquireLockWithRetry(node.stackName, node.region, deps.lockOwner, "export", CHILD_LOCK_RETRY_MAX_ATTEMPTS, CHILD_LOCK_RETRY_DELAY_MS);
 			} catch (err) {
-				throw new Error(`Could not acquire lock for nested-stack child '${node.stackName}' (${node.region}) — another cdkd process held it through the retry window. Wait for it to finish, or run 'cdkd force-unlock ${node.stackName} --stack-region ${node.region}' if you are certain no other process is active. No CloudFormation changeset has been submitted; cdkd state is unchanged.`, { cause: err instanceof Error ? err : void 0 });
+				throw new Error(await buildLockContentionMessage({
+					lockManager: deps.lockManager,
+					stackName: node.stackName,
+					region: node.region,
+					subject: "nested-stack child",
+					heldClause: "another cdkd process held it through the retry window",
+					recovery: args.lockRecovery,
+					suffix: "No CloudFormation changeset has been submitted; cdkd state is unchanged."
+				}), { cause: err instanceof Error ? err : void 0 });
 			}
 			acquiredChildLocks.push({
 				stackName: node.stackName,
@@ -71930,8 +72258,12 @@ async function stateOrphanCommand(stackArgs, options) {
 			}
 			if (!options.force) {
 				for (const target of targets) if (await setup.lockManager.isLocked(stackName, target.region)) {
-					const where = target.region ?? "(legacy)";
-					throw new Error(`Stack '${stackName}' (${where}) is locked. Run 'cdkd force-unlock ${stackName}${target.region ? ` --stack-region ${target.region}` : ""}' first, or pass --force to remove anyway.`);
+					const where = target.region ? displaySafe(target.region, { asciiOnly: true }) || "<unrenderable>" : "(legacy)";
+					throw new Error(`Stack '${displaySafe(stackName, { asciiOnly: true })}' (${where}) is locked. Run: ${buildForceUnlockCommand(stackName, target.region, {
+						profile: options.profile,
+						stateBucket: setup.bucket,
+						statePrefix: options.statePrefix
+					}) || "a command cdkd cannot show safely: the recorded name or region would not survive a command line intact, so inspect the lock object directly"} first, or pass --force to remove anyway.`);
 				}
 			}
 			if (!options.yes && !options.force) {
@@ -71951,9 +72283,13 @@ async function stateOrphanCommand(stackArgs, options) {
 			}
 			for (const target of targets) {
 				if (target.region) {
+					await warnOnLiveForeignLock(setup.lockManager, stackName, target.region, logger);
 					await setup.stateBackend.deleteState(stackName, target.region);
 					await setup.lockManager.forceReleaseLock(stackName, target.region);
-				} else await setup.lockManager.forceReleaseLock(stackName, void 0);
+				} else {
+					await warnOnLiveForeignLock(setup.lockManager, stackName, void 0, logger);
+					await setup.lockManager.forceReleaseLock(stackName, void 0);
+				}
 				logger.info(`✓ Removed state for stack: ${formatStackRef(target)}`);
 			}
 		}
@@ -72085,6 +72421,7 @@ async function stateDestroyCommand(stackArgs, options) {
 					exportIndexStore: setup.exportIndexStore,
 					destroyOptions: {
 						...options.profile && { profile: options.profile },
+						statePrefix: options.statePrefix,
 						...options.removeProtection === true && { removeProtection: true },
 						...options.skipFinalSnapshot === true && { skipFinalSnapshot: true },
 						...options.resourceWarnAfter?.globalMs !== void 0 && { resourceWarnAfterMs: options.resourceWarnAfter.globalMs },
@@ -72100,6 +72437,7 @@ async function stateDestroyCommand(stackArgs, options) {
 					baseRegion: setup.region,
 					...options.profile && { profile: options.profile },
 					stateBucket: setup.bucket,
+					statePrefix: options.statePrefix,
 					skipConfirmation: options.yes || options.all === true,
 					removeProtection: options.removeProtection === true,
 					skipFinalSnapshot: options.skipFinalSnapshot === true,
@@ -72461,7 +72799,12 @@ async function stateRefreshObservedCommand(stackArgs, options) {
 			if (!target.region) throw new Error(`Stack '${target.stackName}' has only a legacy state record without a region. Run 'cdkd deploy ${target.stackName}' (or any cdkd write) first to migrate it to the region-scoped layout, then re-run refresh-observed.`);
 			const counts = await refreshObservedForStack(target.stackName, target.region, setup.stateBackend, setup.lockManager, providerRegistry, {
 				dryRun: options.dryRun ?? false,
-				logger
+				logger,
+				lockRecovery: {
+					profile: options.profile,
+					stateBucket: setup.bucket,
+					statePrefix: options.statePrefix
+				}
 			});
 			totalRefreshed += counts.refreshed;
 			totalUnsupported += counts.unsupported;
@@ -72488,6 +72831,34 @@ async function stateRefreshObservedCommand(stackArgs, options) {
 */
 const NO_RECORDED_SECRETS = /* @__PURE__ */ new Map();
 /**
+* Warn before `cdkd state orphan` force-releases a lock that is still LIVE.
+*
+* `forceReleaseLock` is unconditional by design — a stuck lock must never make
+* a state record unremovable — but it deletes an in-flight `cdkd deploy`'s lock
+* just as readily as a stale one, and it did so silently (issue #2171). The
+* write it enables has already happened by the time anyone notices, so the
+* only useful thing is to name the owner at the moment of the release.
+*
+* Best-effort in both directions: an expired lock is not worth a line, and a
+* failed read must not block the removal the user asked for.
+*
+* (Issue #2171's own text called this command `cdkd state rm`; no such command
+* exists -- this file registers it as `orphan`.)
+*/
+async function warnOnLiveForeignLock(lockManager, stackName, region, logger) {
+	try {
+		const info = await lockManager.getLockInfo(stackName, region);
+		if (!info) return;
+		const expiryKnown = Number.isFinite(info.expiresAt);
+		if (expiryKnown && info.expiresAt <= Date.now()) return;
+		const safeStack = displaySafe(stackName, { asciiOnly: true }) || "<unrenderable>";
+		const where = region ? `${safeStack} (${displaySafe(region, { asciiOnly: true }) || "<unrenderable>"})` : `${safeStack} (legacy lock key)`;
+		const owner = info.owner;
+		const operation = info.operation ? `, operation: ${info.operation}` : "";
+		logger.warn(`Force-releasing a LIVE lock on ${where} ${owner ? `held by ${owner}${operation}` : "held by an unnamed holder"}. ` + (owner && expiryKnown ? `That process is still running and will keep writing; its next state write ` : expiryKnown ? `The lock has not expired, so a process may still be writing; its next state write ` : `The lock records no readable expiry, so a process may still be writing; its next state write `) + `may recreate the record being removed here.`);
+	} catch {}
+}
+/**
 * Refresh the `observedProperties` of every resource in one stack
 * record. Returns counts so the caller can aggregate across `--all`.
 *
@@ -72497,7 +72868,7 @@ const NO_RECORDED_SECRETS = /* @__PURE__ */ new Map();
 * for the underlying SDK reads.
 */
 async function refreshObservedForStack(stackName, region, stateBackend, lockManager, providerRegistry, opts) {
-	const { logger } = opts;
+	const { logger, lockRecovery } = opts;
 	const result = await stateBackend.getState(stackName, region);
 	if (!result) throw new Error(`No state found for stack '${stackName}' (${region}). Run 'cdkd state list' to see available stacks.`);
 	const { state, etag, migrationPending } = result;
@@ -72535,7 +72906,12 @@ async function refreshObservedForStack(stackName, region, stateBackend, lockMana
 		};
 	}
 	const owner = `${process.env["USER"] || "unknown"}@${process.env["HOSTNAME"] || "host"}:${process.pid}`;
-	if (!await lockManager.acquireLock(stackName, region, owner, "state-refresh-observed")) throw new Error(`Could not acquire lock for stack '${stackName}' (${region}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${stackName} --stack-region ${region}' if you are certain no other process is active.`);
+	if (!await lockManager.acquireLock(stackName, region, owner, "state-refresh-observed")) throw new Error(await buildLockContentionMessage({
+		lockManager,
+		stackName,
+		region,
+		recovery: lockRecovery
+	}));
 	try {
 		let refreshed = 0;
 		let unsupported = 0;
@@ -72878,7 +73254,10 @@ async function rollbackCommand(stackArg, options) {
 						awsClients: setup.awsClients,
 						stateBucket: setup.bucket,
 						exportIndexStore: setup.exportIndexStore,
-						destroyOptions: { ...options.profile && { profile: options.profile } }
+						destroyOptions: {
+							...options.profile && { profile: options.profile },
+							statePrefix: options.statePrefix
+						}
 					}, () => withStackName(stackName, async () => {
 						let failedOpFailures = 0;
 						let failedOpWarnings = 0;
@@ -74915,7 +75294,16 @@ async function orphanCommand(pathArgs, options) {
 		logger.info(`Target: ${stackInfo.stackName} (${targetRegion}); orphaning ${orphanLogicalIds.length} resource(s): ${orphanLogicalIds.join(", ")}`);
 		const owner = `${process.env["USER"] || "unknown"}@${process.env["HOSTNAME"] || "host"}:${process.pid}`;
 		if (!options.dryRun) {
-			if (!await lockManager.acquireLock(stackInfo.stackName, targetRegion, owner, "orphan")) throw new Error(`Could not acquire lock for stack '${stackInfo.stackName}' (${targetRegion}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${stackInfo.stackName} --stack-region ${targetRegion}' if you are certain no other process is active.`);
+			if (!await lockManager.acquireLock(stackInfo.stackName, targetRegion, owner, "orphan")) throw new Error(await buildLockContentionMessage({
+				lockManager,
+				stackName: stackInfo.stackName,
+				region: targetRegion,
+				recovery: {
+					profile: options.profile,
+					stateBucket,
+					statePrefix: options.statePrefix
+				}
+			}));
 		}
 		try {
 			const stateData = await stateBackend.getState(stackInfo.stackName, targetRegion);
@@ -75401,6 +75789,11 @@ async function importCommand(stackArg, options) {
 			bucket: stateBucket,
 			prefix: options.statePrefix
 		};
+		const lockRecovery = {
+			profile: options.profile,
+			stateBucket,
+			statePrefix: options.statePrefix
+		};
 		const stateBackend = new S3StateBackend(awsClients.s3, stateConfig, {
 			...options.region && { region: options.region },
 			...options.profile && { profile: options.profile }
@@ -75501,7 +75894,16 @@ async function importCommand(stackArg, options) {
 		}
 		for (const overrideId of overrides.keys()) if (!templateLogicalIds.has(overrideId)) throw new Error(`--resource / --resource-mapping references logical ID '${overrideId}' which is not in the synthesized template for stack '${stackInfo.stackName}'. Available IDs: ${[...templateLogicalIds].join(", ")}`);
 		const owner = `${process.env["USER"] || "unknown"}@${process.env["HOSTNAME"] || "host"}:${process.pid}`;
-		if (!await lockManager.acquireLock(stackInfo.stackName, targetRegion, owner, "import")) throw new Error(`Could not acquire lock for stack '${stackInfo.stackName}' (${targetRegion}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${stackInfo.stackName} --stack-region ${targetRegion}' if you are certain no other process is active.`);
+		if (!await lockManager.acquireLock(stackInfo.stackName, targetRegion, owner, "import")) throw new Error(await buildLockContentionMessage({
+			lockManager,
+			stackName: stackInfo.stackName,
+			region: targetRegion,
+			recovery: {
+				profile: options.profile,
+				stateBucket,
+				statePrefix: options.statePrefix
+			}
+		}));
 		try {
 			const rows = [];
 			for (const { logicalId, resource } of resources) {
@@ -75565,6 +75967,7 @@ async function importCommand(stackArg, options) {
 			logger.info(`✓ State written: ${stackInfo.stackName} (${targetRegion})`);
 			logger.info(`  ${importedRows.length} resource(s) imported. Run 'cdkd diff' to see how the imported state lines up with the template.`);
 			if (migrationCfnStackName && migrationTree && accountIdForNestedSynth) await importNestedStackChildrenRecursive({
+				lockRecovery,
 				parentStackName: stackInfo.stackName,
 				parentRegion: targetRegion,
 				parentNestedTemplates: stackInfo.nestedTemplates ?? {},
@@ -76230,7 +76633,13 @@ async function importNestedStackChildrenRecursive(args) {
 			const childRewritten = rewriteTemplateAssetReferences(childTemplate, assetRedirect);
 			if (childRewritten > 0) logger.info(`Note: ${childRewritten} asset reference(s) in nested stack ${childStackName} are recorded in state at their pre-rewrite (CDK bootstrap) values, so the next 'cdkd deploy' repoints any resource that still holds them to cdkd asset storage.`);
 		}
-		if (!await lockManager.acquireLock(childStackName, childRegion, lockOwner, "import")) throw new Error(`Could not acquire lock for nested stack '${childStackName}' (${childRegion}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${childStackName} --stack-region ${childRegion}' if you are certain no other process is active.`);
+		if (!await lockManager.acquireLock(childStackName, childRegion, lockOwner, "import")) throw new Error(await buildLockContentionMessage({
+			lockManager,
+			stackName: childStackName,
+			region: childRegion,
+			subject: "nested stack",
+			recovery: args.lockRecovery
+		}));
 		try {
 			const childResources = collectImportableResources(childTemplate);
 			const childTemplateLogicalIds = new Set(childResources.map((r) => r.logicalId));
@@ -76272,6 +76681,7 @@ async function importNestedStackChildrenRecursive(args) {
 			await stateBackend.saveState(childStackName, childRegion, childStackState);
 			logger.info(`✓ Nested stack state written: ${childStackName} (${childRegion}) — ${rows.filter((r) => r.outcome === "imported").length} resource(s) imported.`);
 			if (childTreeNode.nested.size > 0) await importNestedStackChildrenRecursive({
+				lockRecovery: args.lockRecovery,
 				parentStackName: childStackName,
 				parentRegion: childRegion,
 				parentNestedTemplates: indexGrandchildTemplatePaths(childTemplate, childTemplatePath),
@@ -86145,7 +86555,7 @@ function createMigrateCommand() {
 */
 function buildProgram() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.284.38");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.284.40");
 	program.hook("preAction", (_thisCommand, actionCommand) => {
 		const { profile } = actionCommand.optsWithGlobals();
 		if (profile !== void 0) process.env["AWS_PROFILE"] = profile;