@go-to-k/cdkd 0.285.14 → 0.285.16

package/dist/{program-BSanOkkV.js → program-C-xfsrSP.js}

@@ -1,8 +1,8 @@
-import { $ as DEFAULT_STATE_PREFIX, $n as resolveUseCdkBootstrapAssets, $r as retryClassificationText, $t as isSingleDynamicReferenceToken, A as bold, An as validateAssetBucketName, Ar as LocalMigrateError, At as requireConfigObject, B as secretBearingStateKeyWarning, Bn as runDockerStreaming, Br as StackTerminationProtectionError, Bt as DiffCalculator, C as unsupportedFinalSnapshotError, Cn as BOOTSTRAP_MARKER_PREFIX, Ct as assertRegionMatch, D as isStatefulRecreateTargetSync, Dn as isCrossRegionRedirect, Dr as DynamicReferenceRegionAmbiguousError, Dt as readConfigString, E as MULTI_REGION_RECREATE_BLOCKED_TYPES, En as getBootstrapMarkerKey, Er as DeployCancelledError, Et as configStringRefusal, F as yellow, Fn as dockerSpawnEnvWithSensitive, Fr as PartialFailureError, Ft as s3BucketDomainName, G as clearOnUpdateRemoval, Gn as getDefaultStateBucketName, Gr as normalizeAwsError, Gt as TemplateParser, H as getCurrentResourceSecrets, Hn as getDockerImageBySourceHash, Ht as describeTypeWithThrottleRetry, I as collectDeclaredOutputNames, In as formatDockerLoginError, Ir as ProvisioningError, It as s3BucketDualStackDomainName, J as findSilentDropProperties, Jn as resolveAutoAssetStorage, Jr as isRetryableTransientError, Jt as TEMPLATE_SOURCED_RULES, K as ProviderRegistry, Kn as getLegacyStateBucketName, Kr as withErrorHandling, Kt as STATE_SOURCED_CROSS_GENERATION_RULES, L as collectPublishedOutputNames, Ln as getDockerCmd, Lr as ResourceTimeoutError, Lt as s3BucketRegionalDomainName, M as gray, Mn as buildDenyExternalAccessPolicy, Mt as classifyReplaySecretRegion, N as green, Nn as describeAwsFailure, Nr as MissingCdkCliError, Nt as producerRegionsFromState, O as renderStatefulReason, On as parseBootstrapMarker, Or as IntrinsicResolutionRefusalError, Ot as replayWarn, P as red, Pn as buildDockerImage, Pr as NestedStackChildDirectDestroyError, Pt as s3BucketArn, Q as CUSTOM_RESOURCE_RESPONSE_PREFIX, Qn as resolveStateBucketWithDefaultAndSource, Qr as markRedactedCause, Qt as errorCauseChain, R as exportAliasCollisionScrubWarning, Rn as partitionSensitiveEnv, Rr as ResourceUpdateNotSupportedError, Rt as s3BucketWebsiteUrl, S as refusesFinalSnapshot, Sn as AssetModeResolver, Sr as CdkdError, St as resolveExplicitPhysicalId, T as extractDeploymentEventError, Tn as ensureAssetStorage, Tt as configBooleanRefusal, U as IAMRoleProvider, Un as Synthesizer, Ut as withRetry, V as stateKeySecretExposure, Vn as AssetManifestLoader, Vt as INTRINSIC_KEYS, W as collectInlinePolicyNamesManagedBySiblings, Wn as synthesisStatusMessage, Wt as DagBuilder, X as maskDeep, Xn as resolveSkipPrefix, Xr as isTransientServerError, Xt as createSecretMasker, Y as createMaskedRetryLogger, Yn as resolveCaptureObservedState, Yr as isThrottlingError, Yt as carriesSecretMask, Z as maskerOrIdentity, Zn as resolveStateBucketWithDefault, Zr as markNonRetryable, Zt as dynamicReferenceTokens, _ as PRE_DELETE_SNAPSHOT_TYPES, _n as createAssetRedirectResolver, _r as AwsClients, _t as isUnboundTemplateParameter, a as DeploymentEventsStore, an as scrubResourceRecord, ar as findLargeInlineResources, at as CloudControlProvider, b as createPreDeleteFinalSnapshot, bn as escapeRegExp, br as setAwsClients, bt as WAFv2WebACLProvider, c as replayFailedOperations, cn as rebuildClientForBucketRegion, cr as displaySafe, ct as deleteIndeterminateGuards, d as updatePartialReason, dn as importableOutputs, dr as canonicalizeRegion, dt as isTerminationProtectionPropagationError, en as maskSecretsInError, er as stateBucketExistenceConfirmed, et as beginCommandInterruptScope, f as withResourceDeadline, fn as shouldRetainResource, fr as derivePartitionAndUrlSuffix, ft as IntrinsicFunctionResolver, g as ATOMIC_FINAL_SNAPSHOT_TYPES, gn as buildAssetRedirectMap, gr as resolveBucketRegion, gt as getAccountInfo, h as computeImplicitDeleteEdges, hn as WorkGraph, ht as coerceParameterTypedValue, i as DeploymentEventsReader, in as redactSecretsForState, ir as MIGRATE_TMP_PREFIX, it as startInterruptWatch, j as cyan, jn as validateContainerRepoName, jr as LocalStartServiceError, jt as requireConfigString, k as formatResourceLine, kn as readBootstrapMarkerBody, kr as LocalInvokeBuildError$1, kt as requireConfigArray, l as replayRollback, ln as exportNamesCarriedFrom, lr as expectedOwnerParam, lt as deleteSkipReason, m as IMPLICIT_DELETE_DEPENDENCIES, mn as stringifyValue, mr as processStackMessages, mt as cfnRefValueFromPhysicalId, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nn as recordMaskOnlyValue, nr as CFN_TEMPLATE_BODY_LIMIT, nt as interruptWatchListenerCount, o as planFailedOps, on as LockManager, or as uploadCfnTemplate, ot as slowCcOperationTimeoutMs, p as maskingRetryLogger, pn as AssetPublisher, pr as AssemblyReader, pt as carriesDynamicReference, q as findActionableSilentDrops, qn as resolveApp, qr as isMarkedNonRetryable, qt as STATE_SOURCED_READBACK_RULES, r as DeployEngine, rn as recoverMaskedOutput, rr as CFN_TEMPLATE_URL_LIMIT, rt as isInterruptedWaitError, s as planRollback, sn as S3StateBackend, sr as CUSTOM_RESOURCE_RESPONSE_OBJECT_DESCRIPTION, st as UNSPECIFIED_SKIP_REASON, t as DEFAULT_RESOURCE_TIMEOUT_MS, tn as maskSecretsInText, tr as warnDeprecatedNoPrefixCliFlag, tt as endCommandInterruptScope, u as updatePartialMessage, un as importableOutputKeys, ur as PARTITION_TABLE, ut as disableInstanceApiTermination, v as buildFinalSnapshotIdentifier, vn as loadPublishableAssetManifest, vr as getAwsClients, vt as parameterTypeMayLoseSecretIdentity, w as makeCanonicalizePropertiesFn, wn as assertAssetBucketRegion, wr as CrossAccountSecretRefusalError, wt as coerceCfnBoolean, x as isFinalSnapshotError, xn as stripControlChars, xt as normalizeAwsTagsToCfn, y as ccRoutedFinalSnapshotError, yn as rewriteTemplateAssetReferences, yr as resetAwsClients, yt as refStateLookupFromResource, z as isExportAliasCollision, zn as runDockerForeground, zr as StackHasActiveImportsError, zt as applyRoleArnIfSet } from "./deploy-engine-CA50haPO.js";
+import { $ as endCommandInterruptScope, $n as resolveCaptureObservedState, $r as isThrottlingError, $t as maskSecretsInText, A as bold, An as getBootstrapMarkerKey, Ar as DeployCancelledError, At as classifyReplaySecretRegion, B as secretBearingStateKeyWarning, Bn as formatDockerLoginError, Br as ProvisioningError, Bt as describeTypeWithThrottleRetry, C as unsupportedFinalSnapshotError, Cn as rewriteTemplateAssetReferences, Cr as resetAwsClients, Ct as configBooleanRefusal, D as isStatefulRecreateTargetSync, Dn as BOOTSTRAP_MARKER_PREFIX, Dt as requireConfigArray, E as MULTI_REGION_RECREATE_BLOCKED_TYPES, En as AssetModeResolver, Er as CdkdError, Et as replayWarn, F as yellow, Fn as validateContainerRepoName, Fr as LocalStartServiceError, Ft as s3BucketRegionalDomainName, G as clearOnUpdateRemoval, Gn as AssetManifestLoader, Gt as STATE_SOURCED_READBACK_RULES, H as getCurrentResourceSecrets, Hn as partitionSensitiveEnv, Hr as ResourceUpdateNotSupportedError, Ht as DagBuilder, I as collectDeclaredOutputNames, In as buildDenyExternalAccessPolicy, It as s3BucketWebsiteUrl, J as findSilentDropProperties, Jn as synthesisStatusMessage, Jt as createSecretMasker, K as ProviderRegistry, Kn as getDockerImageBySourceHash, Kt as TEMPLATE_SOURCED_RULES, L as collectPublishedOutputNames, Ln as describeAwsFailure, Lr as MissingCdkCliError, Lt as applyRoleArnIfSet, M as gray, Mn as parseBootstrapMarker, Mr as IntrinsicResolutionRefusalError, Mt as s3BucketArn, N as green, Nn as readBootstrapMarkerBody, Nr as LocalInvokeBuildError$1, Nt as s3BucketDomainName, O as renderStatefulReason, On as assertAssetBucketRegion, Or as CrossAccountSecretRefusalError, Ot as requireConfigObject, P as red, Pn as validateAssetBucketName, Pr as LocalMigrateError, Pt as s3BucketDualStackDomainName, Q as beginCommandInterruptScope, Qn as resolveAutoAssetStorage, Qr as isRetryableTransientError, Qt as maskSecretsInError, R as exportAliasCollisionScrubWarning, Rn as buildDockerImage, Rr as NestedStackChildDirectDestroyError, Rt as DiffCalculator, S as refusesFinalSnapshot, Sn as loadPublishableAssetManifest, Sr as getAwsClients, St as coerceCfnBoolean, T as extractDeploymentEventError, Tn as stripControlChars, Tt as readConfigString, U as IAMRoleProvider, Un as runDockerForeground, Ur as StackHasActiveImportsError, Ut as TemplateParser, V as stateKeySecretExposure, Vn as getDockerCmd, Vr as ResourceTimeoutError, Vt as withRetry, W as collectInlinePolicyNamesManagedBySiblings, Wn as runDockerStreaming, Wr as StackTerminationProtectionError, Wt as STATE_SOURCED_CROSS_GENERATION_RULES, X as maskDeep, Xn as getLegacyStateBucketName, Xr as withErrorHandling, Xt as errorCauseChain, Y as createMaskedRetryLogger, Yn as getDefaultStateBucketName, Yr as normalizeAwsError, Yt as dynamicReferenceTokens, Z as maskerOrIdentity, Zn as resolveApp, Zr as isMarkedNonRetryable, Zt as isSingleDynamicReferenceToken, _ as PRE_DELETE_SNAPSHOT_TYPES, _n as AssetPublisher, _r as AssemblyReader, _t as refStateLookupFromResource, a as DeploymentEventsStore, an as S3StateBackend, ar as warnDeprecatedNoPrefixCliFlag, at as UNSPECIFIED_SKIP_REASON, b as createPreDeleteFinalSnapshot, bn as buildAssetRedirectMap, br as resolveBucketRegion, bt as resolveExplicitPhysicalId, c as replayFailedOperations, cn as buildForceUnlockCommand, cr as MIGRATE_TMP_PREFIX, ct as disableInstanceApiTermination, d as updatePartialReason, dn as CUSTOM_RESOURCE_RESPONSE_PREFIX, dr as CUSTOM_RESOURCE_RESPONSE_OBJECT_DESCRIPTION, dt as carriesDynamicReference, ei as isTransientServerError, en as recordMaskOnlyValue, er as resolveSkipPrefix, et as interruptWatchListenerCount, f as withResourceDeadline, fn as DEFAULT_STATE_PREFIX, fr as displaySafe, ft as cfnRefValueFromPhysicalId, g as ATOMIC_FINAL_SNAPSHOT_TYPES, gn as shouldRetainResource, gr as derivePartitionAndUrlSuffix, gt as parameterTypeMayLoseSecretIdentity, h as computeImplicitDeleteEdges, hn as importableOutputs, hr as canonicalizeRegion, ht as isUnboundTemplateParameter, i as DeploymentEventsReader, in as LockManager, ir as stateBucketExistenceConfirmed, it as slowCcOperationTimeoutMs, j as cyan, jn as isCrossRegionRedirect, jr as DynamicReferenceRegionAmbiguousError, jt as producerRegionsFromState, k as formatResourceLine, kn as ensureAssetStorage, kt as requireConfigString, l as replayRollback, ln as buildLockContentionMessage, lr as findLargeInlineResources, lt as isTerminationProtectionPropagationError, m as IMPLICIT_DELETE_DEPENDENCIES, mn as importableOutputKeys, mr as PARTITION_TABLE, mt as getAccountInfo, n as DEFAULT_RESOURCE_WARN_AFTER_MS, ni as markRedactedCause, nn as redactSecretsForState, nr as resolveStateBucketWithDefaultAndSource, nt as startInterruptWatch, o as planFailedOps, on as rebuildClientForBucketRegion, or as CFN_TEMPLATE_BODY_LIMIT, ot as deleteIndeterminateGuards, p as maskingRetryLogger, pn as exportNamesCarriedFrom, pr as expectedOwnerParam, pt as coerceParameterTypedValue, q as findActionableSilentDrops, qn as Synthesizer, qt as carriesSecretMask, r as DeployEngine, ri as retryClassificationText, rn as scrubResourceRecord, rr as resolveUseCdkBootstrapAssets, rt as CloudControlProvider, s as planRollback, sn as UNRENDERABLE, sr as CFN_TEMPLATE_URL_LIMIT, st as deleteSkipReason, t as DEFAULT_RESOURCE_TIMEOUT_MS, ti as markNonRetryable, tn as recoverMaskedOutput, tr as resolveStateBucketWithDefault, tt as isInterruptedWaitError, u as updatePartialMessage, un as forceQuitRecoveryClause, ur as uploadCfnTemplate, ut as IntrinsicFunctionResolver, v as buildFinalSnapshotIdentifier, vn as stringifyValue, vr as processStackMessages, vt as WAFv2WebACLProvider, w as makeCanonicalizePropertiesFn, wn as escapeRegExp, wr as setAwsClients, wt as configStringRefusal, x as isFinalSnapshotError, xn as createAssetRedirectResolver, xr as AwsClients, xt as assertRegionMatch, y as ccRoutedFinalSnapshotError, yn as WorkGraph, yt as normalizeAwsTagsToCfn, z as isExportAliasCollision, zn as dockerSpawnEnvWithSensitive, zr as PartialFailureError, zt as INTRINSIC_KEYS } from "./deploy-engine-DuFUy9D0.js";
 import { _ as withStackName, c as PATTERN_B_NAME_OPTIONS, f as generateResourceName, g as withSkipPrefix, i as reserveStdoutForPayload, l as PATTERN_B_NAME_PROPERTIES, m as getCurrentStackName, n as getLogger, o as runStackBuffered, p as generateResourceNameWithFallback, s as getLiveRenderer, u as PATTERN_B_RESOURCE_TYPES } from "./logger-Dw-3y48G.js";
 import { t as awsClientDefaults } from "./aws-client-defaults-D-iYiIJ6.js";
-import { t as getCdkdVersion } from "./version-DP5kGlzj.js";
-import { t as ASGProvider } from "./asg-provider-BvIH9Ivw.js";
+import { t as getCdkdVersion } from "./version-C_ZRHikq.js";
+import { t as ASGProvider } from "./asg-provider-DoP-32eU.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";
@@ -38,7 +38,7 @@ import { join as join$1 } from "path";
 import { BatchDeleteImageCommand, CreateRepositoryCommand, DeleteLifecyclePolicyCommand, DeleteRepositoryCommand, DeleteRepositoryPolicyCommand, DescribeImagesCommand as DescribeImagesCommand$1, DescribeRepositoriesCommand, ECRClient, GetAuthorizationTokenCommand, GetLifecyclePolicyCommand, LifecyclePolicyNotFoundException, ListTagsForResourceCommand as ListTagsForResourceCommand$9, PutImageScanningConfigurationCommand, PutImageTagMutabilityCommand, PutLifecyclePolicyCommand, RepositoryNotEmptyException, RepositoryNotFoundException, SetRepositoryPolicyCommand, TagResourceCommand as TagResourceCommand$12, UntagResourceCommand as UntagResourceCommand$12 } from "@aws-sdk/client-ecr";
 import graphlib from "graphlib";
 import { AddTagsToResourceCommand as AddTagsToResourceCommand$2, CreateDBClusterCommand, CreateDBInstanceCommand, CreateDBProxyCommand, CreateDBProxyEndpointCommand, CreateDBSubnetGroupCommand, DBProxyEndpointNotFoundFault, DBProxyNotFoundFault, DBProxyTargetGroupNotFoundFault, DBProxyTargetNotFoundFault, DeleteDBClusterCommand, DeleteDBInstanceCommand, DeleteDBProxyCommand, DeleteDBProxyEndpointCommand, DeleteDBSubnetGroupCommand, DeregisterDBProxyTargetsCommand, DescribeDBClustersCommand, DescribeDBInstancesCommand, DescribeDBProxiesCommand, DescribeDBProxyEndpointsCommand, DescribeDBProxyTargetGroupsCommand, DescribeDBProxyTargetsCommand, DescribeDBSubnetGroupsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$10, ModifyDBClusterCommand, ModifyDBInstanceCommand, ModifyDBProxyCommand, ModifyDBProxyEndpointCommand, ModifyDBProxyTargetGroupCommand, ModifyDBSubnetGroupCommand, RDSClient, RegisterDBProxyTargetsCommand, RemoveTagsFromResourceCommand as RemoveTagsFromResourceCommand$2 } from "@aws-sdk/client-rds";
-import { Command, Option } from "commander";
+import { Command, InvalidArgumentError, Option } from "commander";
 import * as readline$1 from "node:readline/promises";
 import readline from "node:readline/promises";
 import { writeFileSync as writeFileSync$1 } from "fs";
@@ -324,6 +324,50 @@ function parseDuration(value) {
 	return Math.round(num * (unit === "s" ? 1e3 : unit === "m" ? 6e4 : 36e5));
 }
 /**
+* Commander `argParser` for `--stack-region` (issue #2556).
+*
+* Refuses a value carrying no region name at all, at PARSE time rather than
+* in each consumer. `--stack-region ''` is falsy, so every consumer that
+* tested the option for truthiness read it as ABSENT — and absent means "all
+* regions" on the commands that take `--all`, so a flag passed to NARROW a
+* destructive operation silently WIDENED it. `drift --all --revert
+* --stack-region ''` wrote cdkd state values into AWS across every stack in
+* every region.
+*
+* Here rather than in the consumers because there are more consumers than
+* declarations, the value is threaded through helpers that cannot see how it
+* was spelled, and the empty value has no legitimate meaning — so it never
+* needs to reach them. `guardStackRegionOptions` extends the same guard to
+* declarations cdkd does not own.
+*
+* The rule is only "this is not a name": empty and whitespace-only are
+* refused, and everything else is passed through UNCHANGED — cdkd keeps no
+* list of region names, so a value that looks wrong is the caller's to own,
+* and trimming one would be the silent reinterpretation this whole class
+* started as.
+*/
+function parseStackRegion(value) {
+	if (value.trim() === "") throw new InvalidArgumentError(`expected a region name (e.g. us-east-1), got ${value === "" ? "an empty value" : "whitespace only"}. Omit the flag entirely to operate on every region a stack has state in.`);
+	return value;
+}
+/**
+* Attach {@link parseStackRegion} to every `--stack-region` the command tree
+* carries, including ones cdkd never declared.
+*
+* `cdkd local start-{service,alb,cloudfront,agentcore}` inherit the option
+* from cdk-local, so there is no declaration in this repo to hang a parser on
+* and a grep for the flag string does not find them. They are the worst place
+* to miss it: cdk-local resolves the CloudFormation client's region with
+* `options.stackRegion ?? options.region ?? AWS_REGION`, and `''` is not
+* nullish — so an empty value WINS over both fallbacks and reaches the client.
+*
+* Idempotent, and it never replaces a parser a declaration already set.
+*/
+function guardStackRegionOptions(cmd) {
+	for (const option of cmd.options) if (option.long === "--stack-region" && option.parseArg === void 0) option.argParser(parseStackRegion);
+	for (const sub of cmd.commands) guardStackRegionOptions(sub);
+}
+/**
 * Validate that a token's left-hand side looks like a CloudFormation
 * resource type (e.g. `AWS::S3::Bucket`). The check is intentionally
 * loose — we don't maintain a closed list of types — but it does reject
@@ -703,21 +747,39 @@ function parseRecreateViaSdkProviderToken(value, previous) {
 }
 const recreateViaSdkProviderOption = new Option("--recreate-via-sdk-provider <logicalId>", "Destroy + recreate the named resource (by CloudFormation logical id) via cdkd's SDK Provider in this deploy, so a resource currently sticky on provisionedBy: cc-api flips back to provisionedBy: sdk. Used after a #609 backfill release adds SDK coverage for a type the user originally needed CC for (e.g. Lambda LoggingConfig). Repeatable — pass the flag once per resource. Per-resource opt-in. Stateful resource types refuse unless --force-stateful-recreation is ALSO passed.").argParser(parseRecreateViaSdkProviderToken);
 /**
-* Issue [#615] — `--force-stateful-recreation` (boolean) is the second
-* flag required to allow `--recreate-via-cc-api` to operate on a
-* stateful resource (RDS / DynamoDB / EFS / S3 with data / etc.). Two
-* flags so the user explicitly opts into the data-loss footgun.
+* Issue [#615] — `--force-stateful-recreation` (boolean) confirms a
+* data-losing destroy + recreate of a stateful resource (RDS / DynamoDB /
+* EFS / S3 with data / etc.).
+*
+* It started as the second flag `--recreate-via-cc-api` needs, and that
+* two-flag shape still holds for the `--recreate-via-*` / `--replace`
+* opt-ins. But the guard now runs on the mid-deploy replacement paths
+* too — not only the flag-gated ones, and with its own exemptions (a
+* property-driven replacement under `UpdateReplacePolicy: Retain` creates
+* first, so it is skipped there) (see
+* `docs/cli-deploy-safety.md#stateful-resource-guard`), and some of them
+* reach a replacement with NO flag at all: a property-driven replacement
+* (an immutable / createOnly property changed in the template) and the
+* update-failure fallback's Cloud Control trigger (issue [#2514]). On
+* those, a plain `cdkd deploy` asks for this flag on its own — so the
+* help text must not describe it as scoped to `--recreate-via-cc-api`
+* targets.
 *
 * The guard list of "stateful" types lives in
 * `src/provisioning/stateful-types.ts` so it can be queried from both
-* the CLI pre-flight and the deploy engine.
+* the CLI pre-flight and the deploy engine, and it is published — as the
+* only enumeration users read — in `docs/cli-deploy-safety.md`, which a
+* set-equality fence keeps in step with the source. Prose elsewhere
+* (this help string included) names EXAMPLES and points there; it must
+* not read as exhaustive, because a widened guard would silently make it
+* wrong.
 *
 * There is no per-resource granularity on the force flag — when set,
 * EVERY named recreate target bypasses the stateful guard. Per-resource
 * force would create a false sense of granularity (the user is opting
 * into a footgun; pretending to scope it per-resource is misleading).
 */
-const forceStatefulRecreationOption = new Option("--force-stateful-recreation", "Bypass the stateful-resource guard for --recreate-via-cc-api targets. Required when ANY named target is a stateful type (RDS / DynamoDB / EFS / FSx / EBS Volume / S3 with data / Logs with retention / Cognito / Secrets / SSM / Glue / ECR / CloudFront / Kinesis / OpenSearch). Destroy + recreate loses ALL data in the resource — no automatic data migration. Triple-opt-in for CI use: --recreate-via-cc-api <id> --force-stateful-recreation --yes.").default(false);
+const forceStatefulRecreationOption = new Option("--force-stateful-recreation", "Confirm a data-losing destroy + recreate of a stateful resource. Required whenever a replacement target is a stateful type — databases, filesystems, KMS keys, table / vector storage, source repositories, log groups with retention, and more; docs/cli-deploy-safety.md carries the full list, and S3 is the special case (a non-empty bucket at pre-flight, ANY bucket mid-deploy, where the emptiness probe cannot run) — on the --recreate-via-cc-api / --recreate-via-sdk-provider pre-flight, with --replace, AND on the paths a plain deploy reaches with no flag: a template immutable-property change, and an in-place update the provisioning layer rejects. Destroy + recreate loses ALL data in the resource — no automatic data migration. Full opt-in for CI use: --recreate-via-cc-api <id> --force-stateful-recreation --yes.").default(false);
 const replaceOption = new Option("--replace", "Replace (DELETE + CREATE) a resource whose in-place update is rejected because an immutable property changed and AWS exposes no update API for it (e.g. Lambda LayerVersion content, EFS AccessPoint, ECS TaskDefinition, ApiGatewayV2 immutable fields). Without this flag such a change fails the deploy. Stateful types (RDS / DynamoDB / EFS / S3 with data / Logs with retention / etc.) ALSO require --force-stateful-recreation since the replacement is a data-losing DELETE + CREATE.").default(false);
 /**
 * Issue #1002 PR 2 — per-invocation legacy pin for asset destinations
@@ -2437,7 +2499,7 @@ function isPromptAbortError(error) {
 *      bucket with objects, LogGroup with retention) MUST be matched
 *      by an explicit `--force-stateful-recreation` flag. The sync
 *      first-cut runs from the recorded properties alone; the live
-*      `s3:ListObjectsV2` probe (issue [#648]) promotes a `null`
+*      `s3:ListObjectVersions` probe (issue [#648]) promotes a `null`
 *      reason to `'has-objects'` when a bucket actually contains data.
 *   4. Multi-region refusal: every named target whose resource type
 *      is in {@link MULTI_REGION_RECREATE_BLOCKED_TYPES} (e.g.
@@ -2456,7 +2518,7 @@ function isPromptAbortError(error) {
 *
 * Pure with respect to AWS — does NOT probe S3 bucket emptiness. Wrap
 * the result with {@link probeAndRevalidateStateful} to promote S3
-* targets' `statefulReason` via a live `s3:ListObjectsV2` round-trip
+* targets' `statefulReason` via a live `s3:ListObjectVersions` round-trip
 * before rendering errors. The deploy command does this; the validator
 * itself stays sync so unit tests don't need an S3 mock.
 *
@@ -2792,7 +2854,7 @@ function renderDownstreamConsumers(producerStack, consumers) {
 *
 * The per-target plan surfaces a **DATA LOSS** prefix for stateful
 * targets (those with a non-null `statefulReason` after the live
-* `s3:ListObjectsV2` probe — see issue [#648]); these reached pre-flight
+* `s3:ListObjectVersions` probe — see issue [#648]); these reached pre-flight
 * only because the user opted in with `--force-stateful-recreation`,
 * so the prompt's **DATA LOSS** wording is the third "stop and think"
 * moment.
@@ -9590,7 +9652,7 @@ var S3BucketProvider = class S3BucketProvider {
 	* `ServerSideEncryptionConfigurationNotFoundError`, `NoSuchTagSet`,
 	* `NoSuchPublicAccessBlockConfiguration`, etc.) — those are caught
 	* individually and the corresponding key is emitted as a CFn-shape
-	* placeholder (per docs/provider-development.md § 3b: always-emit
+	* placeholder (per docs/provider-rules.md#readcurrentstate-for-drift-detection: always-emit
 	* user-controllable top-level keys), NOT treated as the bucket being
 	* absent.
 	*
@@ -32319,7 +32381,7 @@ var CloudFrontOACProvider = class {
 	* identical, so the reverse mapping is a straight per-field copy.
 	*
 	* Every field is emitted unconditionally, with `?? ''` standing in for an
-	* AWS response that omits it (docs/provider-development.md § 3b): the
+	* AWS response that omits it (docs/provider-rules.md#readcurrentstate-for-drift-detection): the
 	* optional `Description` is user-controllable and mutable, so dropping the
 	* key when AWS returns nothing would leave it out of `observedProperties`
 	* on a stack that never templated it — and the drift comparator's
@@ -47566,12 +47628,13 @@ var GlueProvider = class {
 	* | no             | no              | AWS-AUTHORED -> preserved from live  |
 	*
 	* That keeps this provider on the repo's established clear-on-removal
-	* position (docs/provider-development.md §2a, issue #1155): a removal the
+	* position (docs/provider-rules.md#update-removal-semantics-clear-on-removal, issue #1155): a removal the
 	* user expressed in the template still reaches AWS. Glue's update APIs are
 	* full-replace, so removal needs no explicit reset sentinel — omitting the
 	* key IS the reset, and the only thing this helper adds back is the set of
 	* keys the user never authored in the first place. The generalized rule for
-	* any full-replace update API lives in docs/provider-development.md §2b.
+	* any full-replace update API lives in
+	* docs/provider-rules.md#full-replace-update-apis-erase-aws-authored-values.
 	*
 	* Audited siblings that do NOT get this treatment: `JobUpdate`'s
 	* `DefaultArguments` / `NonOverridableArguments`, `ConnectionInput`'s
@@ -53664,7 +53727,7 @@ var FSxFileSystemProvider = class {
 	* by their respective `read*Configuration` helpers; the few inputs AWS
 	* never returns stay listed in {@link getDriftUnknownPaths}.
 	*
-	* Emission follows `docs/provider-development.md` §3b: every top-level
+	* Emission follows `docs/provider-rules.md#readcurrentstate-for-drift-detection`: every top-level
 	* property `update()` can mutate is emitted unconditionally with a
 	* placeholder, registry-createOnly properties keep their guard, and the
 	* `<Variant>Configuration` blocks take the Class 1 type-discriminator
@@ -57806,7 +57869,7 @@ var CodeCommitRepositoryProvider = class {
 	*
 	* Every user-controllable top-level key `update()` can mutate is emitted
 	* ALWAYS — with a `?? ''` / `?? []` placeholder when AWS returns the field
-	* as undefined / empty (docs/provider-development.md §3b). Omitting the key
+	* as undefined / empty (docs/provider-rules.md#readcurrentstate-for-drift-detection). Omitting the key
 	* on the empty path would let a resource deployed WITHOUT a description
 	* never carry `RepositoryDescription` in `observedProperties`, making a
 	* console-side ADD of a description invisible to drift forever. `Tags` are
@@ -60122,104 +60185,6 @@ 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
 /**
@@ -70228,7 +70193,7 @@ function formatScalar(value) {
 * Reusable `--stack-region <region>` option (mirrors `state show`).
 */
 function stackRegionOption$2() {
-	return new Option("--stack-region <region>", "Region of the stack record to inspect. Required when the same stack name has state in multiple regions.");
+	return new Option("--stack-region <region>", "Region of the stack record to inspect. Required when the same stack name has state in multiple regions.").argParser(parseStackRegion);
 }
 /**
 * Create the `drift` command.
@@ -70667,6 +70632,11 @@ async function stateMigrateCommand(options) {
 			const sourceObjects = await listAllObjects(legacyS3, legacyBucket);
 			logger.info(`  source object count: ${sourceObjects.length}`);
 			if (sourceObjects.length === 0) logger.info("Source bucket is empty — no objects to copy.");
+			if (options.dryRun) {
+				if (options.removeLegacy) logger.info(`--remove-legacy: '${legacyBucket}' would then be emptied (every object version and delete marker) and deleted.`);
+				logger.info("--dry-run: no changes will be made. Stopping here.");
+				return;
+			}
 			if (!options.yes) {
 				const action = options.removeLegacy ? "and DELETE the source bucket" : "(source bucket will be kept)";
 				if (!await confirmPrompt$4(`Copy ${sourceObjects.length} object(s) from ${legacyBucket} -> ${newBucket} ${action}?`)) {
@@ -70674,10 +70644,6 @@ async function stateMigrateCommand(options) {
 					return;
 				}
 			}
-			if (options.dryRun) {
-				logger.info("--dry-run: no changes will be made. Stopping here.");
-				return;
-			}
 			const newS3 = await ensureDestinationBucket(newBucket, legacyRegion, accountId, logger);
 			try {
 				let copied = 0;
@@ -70852,7 +70818,11 @@ async function emptyBucketAllVersions(s3, bucket) {
 /**
 * `cdkd state migrate`'s confirmation prompt. Its only call site is inside the
 * `if (!options.yes)` block above, which is what keeps `confirmOrRefuse`'s
-* non-interactive refusal (issue #2275) from firing on a `--yes` run.
+* non-interactive refusal (issue #2275) from firing on a `--yes` run — and it
+* sits BELOW the `--dry-run` bail (issue #2538), so a preview never reaches it
+* either. Together those are the two ways not to be asked, matching
+* `state refresh-observed`, whose prompt condition spells both:
+* `!options.yes && !options.dryRun`.
 *
 * Exported for unit testing — internal to the command flow otherwise.
 */
@@ -74491,7 +74461,7 @@ async function confirmPrompt$3(prompt) {
 	return confirmOrRefuse(prompt, { refusal: "The cdkd export confirmation prompt cannot run in a non-interactive environment. Pass -y / --yes to confirm, or run the command from a real terminal." });
 }
 function createExportCommand() {
-	const cmd = new Command("export").description("Hand a cdkd-managed stack over to CloudFormation via CFn IMPORT (changeset). AWS resources are unchanged; cdkd state for the stack is deleted on success. Mirror of `cdkd import` (AWS → cdkd) in the reverse direction (cdkd → CFn). Accepts JSON and YAML templates (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Aborts if any resource is not CFn-importable.").argument("[stack]", "Stack name to export (auto-detected for single-stack apps)").option("--cfn-stack-name <name>", "Name of the destination CloudFormation stack for the root stack. Defaults to the cdkd stack name (or the cdkd2cfnStackName mapping when the name contains '~'). For per-nested-child overrides, use --cfn-child-stack-name.").option("--cfn-child-stack-name <pair...>", "Per-nested-child CFn stack-name override. Repeatable. Format: '<cdkdName>=<cfnName>' (e.g. --cfn-child-stack-name 'MyApp~Database=my-app-db'). The cdkd stack name for a nested child is '<parent>~<childLogicalId>' (v6 state-key form). Without an override the CFn name is derived by replacing '~' with '-'. Only consulted when the exported stack tree contains nested children; ignored for flat stacks.").option("--template <path>", "Path to a pre-rendered CloudFormation template (JSON or YAML — format auto-detected). Skips synth.").option("--stack-region <region>", "Region of the cdkd state record to operate on. Required when the same stack name has state in multiple regions.").option("--dry-run", "Print the import plan without creating a changeset.", false).option("--accept-transient-context", "Allow CLI -c key=value overrides at export time even though they are not persisted to cdk.json / cdk.context.json (default: refuse). When set, the user is responsible for passing the same -c flags to every future cdk deploy.", false).option("--include-non-importable", "Run a 2-phase migration when the stack contains non-importable resources (Custom::*). Phase 1 imports the importable resources; phase 2 CFn-CREATEs the non-importable ones, which re-invokes each Custom Resource's onCreate handler. Make sure onCreate is idempotent before enabling.", false).option("--parameter <key=value...>", "CFn template Parameter override, repeatable. Required when the synthesized template has Parameters without Default values; otherwise overrides the template's default value. Format: --parameter Key=Value.").option("--strict-cross-stack", "Refuse to export when sibling cdkd stacks in the same CDK app reference the exporting stack via Fn::GetStackOutput. Without the flag, cdkd warns and proceeds — the consumers keep resolving via the CloudFormation fallback (weak reference) unless they deploy with --no-cfn-fallback.", false).option("--skip-import-support-preflight", "Skip the pre-flight that refuses resource types whose CloudFormation registry schema says CFn cannot IMPORT them (no read handler AND NON_PROVISIONABLE), and let CreateChangeSet answer instead. The pre-flight is a registry HEURISTIC, not AWS's supported-for-import list, so this is the escape hatch for a type AWS has since made importable. Expect the changeset to be rejected if the heuristic was right.", false).option("--no-recreate-import-unsupported", "Block instead of auto-handling resource types AWS does NOT support in IMPORT changesets (AWS::ApiGatewayV2::Stage and AWS::IAM::Policy). Default behavior: cdkd skips these from phase 1, deletes the AWS-side resource between phases, and lets CFn re-CREATE in phase 2 (brief unavailability window). With this flag, the export aborts with a clear error instead.").action(withErrorHandling(exportCommand));
+	const cmd = new Command("export").description("Hand a cdkd-managed stack over to CloudFormation via CFn IMPORT (changeset). AWS resources are unchanged; cdkd state for the stack is deleted on success. Mirror of `cdkd import` (AWS → cdkd) in the reverse direction (cdkd → CFn). Accepts JSON and YAML templates (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Aborts if any resource is not CFn-importable.").argument("[stack]", "Stack name to export (auto-detected for single-stack apps)").option("--cfn-stack-name <name>", "Name of the destination CloudFormation stack for the root stack. Defaults to the cdkd stack name (or the cdkd2cfnStackName mapping when the name contains '~'). For per-nested-child overrides, use --cfn-child-stack-name.").option("--cfn-child-stack-name <pair...>", "Per-nested-child CFn stack-name override. Repeatable. Format: '<cdkdName>=<cfnName>' (e.g. --cfn-child-stack-name 'MyApp~Database=my-app-db'). The cdkd stack name for a nested child is '<parent>~<childLogicalId>' (v6 state-key form). Without an override the CFn name is derived by replacing '~' with '-'. Only consulted when the exported stack tree contains nested children; ignored for flat stacks.").option("--template <path>", "Path to a pre-rendered CloudFormation template (JSON or YAML — format auto-detected). Skips synth.").option("--stack-region <region>", "Region of the cdkd state record to operate on. Required when the same stack name has state in multiple regions.", parseStackRegion).option("--dry-run", "Print the import plan without creating a changeset.", false).option("--accept-transient-context", "Allow CLI -c key=value overrides at export time even though they are not persisted to cdk.json / cdk.context.json (default: refuse). When set, the user is responsible for passing the same -c flags to every future cdk deploy.", false).option("--include-non-importable", "Run a 2-phase migration when the stack contains non-importable resources (Custom::*). Phase 1 imports the importable resources; phase 2 CFn-CREATEs the non-importable ones, which re-invokes each Custom Resource's onCreate handler. Make sure onCreate is idempotent before enabling.", false).option("--parameter <key=value...>", "CFn template Parameter override, repeatable. Required when the synthesized template has Parameters without Default values; otherwise overrides the template's default value. Format: --parameter Key=Value.").option("--strict-cross-stack", "Refuse to export when sibling cdkd stacks in the same CDK app reference the exporting stack via Fn::GetStackOutput. Without the flag, cdkd warns and proceeds — the consumers keep resolving via the CloudFormation fallback (weak reference) unless they deploy with --no-cfn-fallback.", false).option("--skip-import-support-preflight", "Skip the pre-flight that refuses resource types whose CloudFormation registry schema says CFn cannot IMPORT them (no read handler AND NON_PROVISIONABLE), and let CreateChangeSet answer instead. The pre-flight is a registry HEURISTIC, not AWS's supported-for-import list, so this is the escape hatch for a type AWS has since made importable. Expect the changeset to be rejected if the heuristic was right.", false).option("--no-recreate-import-unsupported", "Block instead of auto-handling resource types AWS does NOT support in IMPORT changesets (AWS::ApiGatewayV2::Stage and AWS::IAM::Policy). Default behavior: cdkd skips these from phase 1, deletes the AWS-side resource between phases, and lets CFn re-CREATE in phase 2 (brief unavailability window). With this flag, the export aborts with a clear error instead.").action(withErrorHandling(exportCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -75088,14 +75058,14 @@ async function stateOrphanCommand(stackArgs, options) {
 				logger.info(`No state found for stack: ${stackName}, skipping`);
 				continue;
 			}
-			const targets = options.stackRegion ? stackRefs.filter((r) => r.region === options.stackRegion) : stackRefs;
+			const targets = options.stackRegion !== void 0 ? stackRefs.filter((r) => r.region === options.stackRegion) : stackRefs;
 			if (targets.length === 0) {
-				const seen = stackRefs.map((r) => r.region ?? "(legacy)").join(", ");
-				throw new Error(`No state found for stack '${stackName}' in region '${options.stackRegion}'. Available regions: ${seen}.`);
+				const seen = stackRefs.map((r) => r.region ? displaySafe(r.region, { asciiOnly: true }) || "<unrenderable>" : "(legacy)").join(", ");
+				throw new Error(`No state found for stack '${displaySafe(stackName, { asciiOnly: true }) || "<unrenderable>"}' in region '${displaySafe(options.stackRegion ?? "", { asciiOnly: true })}'. Available regions: ${seen}.`);
 			}
 			if (!options.force) {
 				for (const target of targets) if (await setup.lockManager.isLocked(stackName, target.region)) {
-					const where = target.region ? displaySafe(target.region, { asciiOnly: true }) || "<unrenderable>" : "(legacy)";
+					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,
@@ -75105,7 +75075,7 @@ async function stateOrphanCommand(stackArgs, options) {
 			}
 			if (!options.yes && !options.force) {
 				const targetList = targets.map((t) => formatStackRefSafe(t)).join(", ");
-				process.stdout.write(`\nWARNING: This removes cdkd's state record for [${targetList}] only. AWS resources will NOT be deleted.\nUse 'cdkd destroy ${stackName}' if you want to delete the actual resources.\n\n`);
+				process.stdout.write(`\nWARNING: This removes cdkd's state record for [${targetList}] only. AWS resources will NOT be deleted.\nUse 'cdkd destroy ${displaySafe(stackName, { asciiOnly: true }) || "<unrenderable>"}' if you want to delete the actual resources.\n\n`);
 				if (!await confirmStateOrphanRemoval(`Remove state for ${targetList} from s3://${setup.bucket}/${setup.prefix}/?`)) {
 					logger.info(`Cancelled removal of state for stack: ${stackName}`);
 					continue;
@@ -75118,9 +75088,10 @@ async function stateOrphanCommand(stackArgs, options) {
 					await setup.lockManager.forceReleaseLock(stackName, target.region);
 				} else {
 					await warnOnLiveForeignLock(setup.lockManager, stackName, void 0, logger);
+					await setup.stateBackend.deleteLegacyState(stackName);
 					await setup.lockManager.forceReleaseLock(stackName, void 0);
 				}
-				logger.info(`✓ Removed state for stack: ${formatStackRef(target)}`);
+				logger.info(`✓ Removed state for stack: ${formatStackRefSafe(target)}`);
 			}
 		}
 	} finally {
@@ -75133,7 +75104,7 @@ async function stateOrphanCommand(stackArgs, options) {
 * `--region` (AWS profile region) defined in `commonOptions`.
 */
 function stackRegionOption$1() {
-	return new Option("--stack-region <region>", "Region of the stack record to operate on. Required when the same stack name has state in multiple regions.");
+	return new Option("--stack-region <region>", "Region of the stack record to operate on. Required when the same stack name has state in multiple regions.").argParser(parseStackRegion);
 }
 /**
 * Create the `state orphan` subcommand.
@@ -75927,7 +75898,7 @@ function createStateCommand() {
 * in multiple regions (same pattern + messages as the `state` subcommands).
 */
 function stackRegionOption() {
-	return new Option("--stack-region <region>", "Region of the target stack when the same name has state in multiple regions");
+	return new Option("--stack-region <region>", "Region of the target stack when the same name has state in multiple regions").argParser(parseStackRegion);
 }
 /**
 * Discover every stack that currently has a rollback journal. One raw key
@@ -76541,7 +76512,7 @@ function colorizeEventType(eventType) {
 * Create the `cdkd events` command.
 */
 function createEventsCommand() {
-	const cmd = new Command("events").description("Read back structured deployment events (cdkd's DescribeStackEvents equivalent, issue #808)").argument("<stack>", "Stack name (physical CloudFormation name)").option("--run <runId>", "Read a single run's full event stream instead of the run listing").option("--stack-region <region>", "Disambiguate a stack with event history in multiple regions").option("--json", "Output as JSON", false).option("--format <format>", "Output format ('json' is equivalent to --json)").action(withErrorHandling((stack, options) => {
+	const cmd = new Command("events").description("Read back structured deployment events (cdkd's DescribeStackEvents equivalent, issue #808)").argument("<stack>", "Stack name (physical CloudFormation name)").option("--run <runId>", "Read a single run's full event stream instead of the run listing").option("--stack-region <region>", "Disambiguate a stack with event history in multiple regions", parseStackRegion).option("--json", "Output as JSON", false).option("--format <format>", "Output format ('json' is equivalent to --json)").action(withErrorHandling((stack, options) => {
 		return eventsCommand(stack, {
 			...options,
 			json: options.json === true || options.format === "json"
@@ -78508,7 +78479,7 @@ async function confirmPrompt$1(prompt) {
 * Create the top-level `cdkd orphan` command.
 */
 function createOrphanCommand() {
-	const cmd = new Command("orphan").description("Remove one or more resources from cdkd state by construct path (does NOT delete AWS resources). Mirrors aws-cdk-cli's 'cdk orphan --unstable=orphan'. Synth-driven; for the previous whole-stack-orphan behavior, use 'cdkd state orphan <stack>'.").argument("<paths...>", "Construct paths to orphan, e.g. 'MyStack/MyTable'. Multiple paths must reference the same stack.").option("--stack-region <region>", "Region of the stack record to operate on. Required when the same stack name has state in multiple regions.").option("--dry-run", "Compute and print the rewrite audit table without acquiring a lock or saving state.", false).action(withErrorHandling(orphanCommand));
+	const cmd = new Command("orphan").description("Remove one or more resources from cdkd state by construct path (does NOT delete AWS resources). Mirrors aws-cdk-cli's 'cdk orphan --unstable=orphan'. Synth-driven; for the previous whole-stack-orphan behavior, use 'cdkd state orphan <stack>'.").argument("<paths...>", "Construct paths to orphan, e.g. 'MyStack/MyTable'. Multiple paths must reference the same stack.").option("--stack-region <region>", "Region of the stack record to operate on. Required when the same stack name has state in multiple regions.", parseStackRegion).option("--dry-run", "Compute and print the rewrite audit table without acquiring a lock or saving state.", false).action(withErrorHandling(orphanCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -78797,7 +78768,7 @@ async function forceUnlockCommand(stackArgs, options) {
 * Create force-unlock command
 */
 function createForceUnlockCommand() {
-	const cmd = new Command("force-unlock").description("Force-release a stale lock on a stack").argument("[stacks...]", "Stack name(s) to unlock").addOption(new Option("--stack-region <region>", "Stack region whose lock to release (use when the same stack name has locks in multiple regions). Defaults to all regions where the stack has state.")).action(withErrorHandling(forceUnlockCommand));
+	const cmd = new Command("force-unlock").description("Force-release a stale lock on a stack").argument("[stacks...]", "Stack name(s) to unlock").addOption(new Option("--stack-region <region>", "Stack region whose lock to release (use when the same stack name has locks in multiple regions). Defaults to all regions where the stack has state.").argParser(parseStackRegion)).action(withErrorHandling(forceUnlockCommand));
 	[
 		...commonOptions,
 		...stateOptions,
@@ -85083,7 +85054,7 @@ function resolveMtlsConfig(options) {
 * Builder for the `start-api` subcommand. Wired up by `local.ts`.
 */
 function createLocalStartApiCommand() {
-	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and AWS_IAM auth (REST v1 `AuthorizationType: AWS_IAM` and Function URL `AuthType: AWS_IAM` — SigV4 signature verification only; IAM policy evaluation is NOT emulated; see https://github.com/go-to-k/cdkd/blob/main/docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Two forms: (1) `--assume-role <arn>` sets a single global default ARN used for every routed Lambda; (2) `--assume-role <LogicalId>=<arn>` (repeatable) is a per-Lambda override (wins over the global default and over --assume-role-auto for the named Lambda). Pair with --assume-role-auto to auto-resolve every other Lambda. Precedence: per-Lambda > (--assume-role-auto OR global default) > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--assume-role-auto", "Auto-resolve EACH routed Lambda's own execution role per-Lambda (literal ARN / Fn::GetAtt against template / --from-cfn-stack state). Slower boot — one STS call per Lambda — but the right shape when each Lambda's deployed role differs. Mutually exclusive with `--assume-role <arn>` (global default); errors at boot. Compatible with `--assume-role <LogicalId>=<arn>` per-Lambda overrides — the map wins for named Lambdas, auto-resolve handles the rest.").default(false)).addOption(new Option("--watch", "Hot-reload: watch the CDK app source tree and re-synth + re-discover routes on a source edit (cdk.out / node_modules / .git excluded; honors cdk.json watch.include / watch.exclude). Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).addOption(new Option("--mtls-truststore <path>", "PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj \"/CN=cdkd-local-ca\" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj \"/CN=localhost\"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj \"/CN=client\"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...")).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--strict-sigv4", "Opt-in: enforce strict AWS_IAM SigV4 verification. When set, requests whose signature cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) are denied. DEFAULT off — warn-and-pass with a placeholder principalId, matching cdk-local's `cdkl start-api`. Enable this when you want local parity with the deployed API Gateway's signature enforcement.").default(false)).action(withErrorHandling(localStartApiCommand));
+	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and AWS_IAM auth (REST v1 `AuthorizationType: AWS_IAM` and Function URL `AuthType: AWS_IAM` — SigV4 signature verification only; IAM policy evaluation is NOT emulated; see https://github.com/go-to-k/cdkd/blob/main/docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Two forms: (1) `--assume-role <arn>` sets a single global default ARN used for every routed Lambda; (2) `--assume-role <LogicalId>=<arn>` (repeatable) is a per-Lambda override (wins over the global default and over --assume-role-auto for the named Lambda). Pair with --assume-role-auto to auto-resolve every other Lambda. Precedence: per-Lambda > (--assume-role-auto OR global default) > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--assume-role-auto", "Auto-resolve EACH routed Lambda's own execution role per-Lambda (literal ARN / Fn::GetAtt against template / --from-cfn-stack state). Slower boot — one STS call per Lambda — but the right shape when each Lambda's deployed role differs. Mutually exclusive with `--assume-role <arn>` (global default); errors at boot. Compatible with `--assume-role <LogicalId>=<arn>` per-Lambda overrides — the map wins for named Lambdas, auto-resolve handles the rest.").default(false)).addOption(new Option("--watch", "Hot-reload: watch the CDK app source tree and re-synth + re-discover routes on a source edit (cdk.out / node_modules / .git excluded; honors cdk.json watch.include / watch.exclude). Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).").argParser(parseStackRegion)).addOption(new Option("--mtls-truststore <path>", "PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj \"/CN=cdkd-local-ca\" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj \"/CN=localhost\"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj \"/CN=client\"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...")).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--strict-sigv4", "Opt-in: enforce strict AWS_IAM SigV4 verification. When set, requests whose signature cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) are denied. DEFAULT off — warn-and-pass with a placeholder principalId, matching cdk-local's `cdkl start-api`. Enable this when you want local parity with the deployed API Gateway's signature enforcement.").default(false)).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -86319,7 +86290,7 @@ async function resolveSidecarCredentials(options, assumedCredentials) {
 	if (options.profile) return resolveProfileCredentials(options.profile);
 }
 function createLocalRunTaskCommand() {
-	const cmd = new Command("run-task").description("Run an AWS::ECS::TaskDefinition locally — pulls/builds images, sets up a per-task docker network with the AWS-published metadata-endpoints sidecar, and starts every container in dependsOn order. Target accepts a CDK display path (MyStack/MyService/TaskDef) or stack-qualified logical ID (MyStack:MyServiceTaskDefXYZ1234). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the AWS::ECS::TaskDefinition to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed function role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--keep-running", "Don't docker rm -f the user containers on task exit (network + sidecar are still torn down). Use when you want to docker exec into a stopped container for post-mortems.").default(false)).addOption(new Option("--detach", "Start the containers in the background and exit (skip log streaming + auto teardown). Useful in CI smoke tests; caller manages container lifecycle.").default(false)).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt references to same-stack AWS::ECR::Repository resources with the deployed URI. Off by default — only the AWS pseudo-parameter tier (${AWS::AccountId} / ${AWS::Region}) is resolved without this flag.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in container env vars / secrets / image URIs with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).action(withErrorHandling(localRunTaskCommand));
+	const cmd = new Command("run-task").description("Run an AWS::ECS::TaskDefinition locally — pulls/builds images, sets up a per-task docker network with the AWS-published metadata-endpoints sidecar, and starts every container in dependsOn order. Target accepts a CDK display path (MyStack/MyService/TaskDef) or stack-qualified logical ID (MyStack:MyServiceTaskDefXYZ1234). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the AWS::ECS::TaskDefinition to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed function role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--keep-running", "Don't docker rm -f the user containers on task exit (network + sidecar are still torn down). Use when you want to docker exec into a stopped container for post-mortems.").default(false)).addOption(new Option("--detach", "Start the containers in the background and exit (skip log streaming + auto teardown). Useful in CI smoke tests; caller manages container lifecycle.").default(false)).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt references to same-stack AWS::ECR::Repository resources with the deployed URI. Off by default — only the AWS pseudo-parameter tier (${AWS::AccountId} / ${AWS::Region}) is resolved without this flag.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in container env vars / secrets / image URIs with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).").argParser(parseStackRegion)).action(withErrorHandling(localRunTaskCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -87743,7 +87714,7 @@ function readEnvOverridesFile$1(filePath) {
 	return parsed;
 }
 function createLocalInvokeAgentCoreCommand() {
-	const cmd = new Command("invoke-agentcore").description("Run a Bedrock AgentCore Runtime container locally and invoke it once over its protocol contract: HTTP (POST /invocations + GET /ping on 8080) or MCP (POST /mcp Streamable HTTP on 8000). Resolves the AWS::BedrockAgentCore::Runtime, pulls/builds its container, injects env vars + AWS credentials, and prints the response. For an MCP runtime, runs the session handshake then sends one JSON-RPC request (tools/list by default, or the method/params from --event). Target accepts a CDK display path (MyStack/MyAgent) or stack-qualified logical ID (MyStack:MyAgentRuntime1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick from a list. Supports the container artifact and the CodeConfiguration managed-runtime artifact (fromCodeAsset, built from source) on the HTTP + MCP protocols; the agent calls real AWS for managed services.").argument("[target]", "CDK display path or stack-qualified logical ID of the AgentCore Runtime to invoke (omit to pick interactively in a TTY)").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--session-id <id>", "AgentCore runtime session id header value (default: a random UUID)")).addOption(new Option("--ws", "Stream over the HTTP-protocol agent's bidirectional /ws WebSocket endpoint (on 8080) instead of POST /invocations: send --event as the first frame and print every received frame to stdout until the agent closes. When stdin is a TTY, auto-enters a REPL — each typed line is sent as a follow-up text frame until Ctrl-D / agent close; pipe from /dev/null to force one-shot in a TTY. Ignored for an MCP runtime.").default(false)).addOption(new Option("--watch", "Re-synth and reload the agent container on CDK source changes (follows cdk-local #270). Supported on the HTTP / AGUI protocols, both the --ws session AND the default one-shot POST /invocations (the reload re-runs the single shot). An interpreted-language source edit inside a CodeConfiguration source tree takes a soft-reload fast path (docker cp + docker restart, no rebuild); Dockerfile / compiled-source / asset-hash-changed / ambiguous edits force a full rebuild. For MCP / A2A runtimes --watch is a no-op WARN and the single shot proceeds.").default(false)).addOption(new Option("--bearer-token <jwt>", "Bearer JWT to present when the runtime declares a customJwtAuthorizer. Verified against the runtime OIDC discovery URL (signature / issuer / expiry / audience) before the container starts, then forwarded to /invocations as Authorization: Bearer <jwt>.")).addOption(new Option("--no-verify-auth", "Skip inbound JWT verification even when the runtime declares a customJwtAuthorizer (local-dev escape hatch). A --bearer-token, if given, is still forwarded.")).addOption(new Option("--sigv4", "Sign the /invocations POST with AWS SigV4 (service bedrock-agentcore) using the resolved credentials, matching the cloud default when the runtime declares no customJwtAuthorizer. Opt-in: default unsigned. Mutually exclusive with --bearer-token; ignored on a JWT-protected runtime.").default(false)).addOption(new Option("--platform <platform>", "docker --platform for the agent container (linux/amd64 or linux/arm64)").choices(["linux/amd64", "linux/arm64"]).default("linux/arm64")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for the local-build path")).addOption(new Option("--no-build", "Skip docker build on the local-asset path (use the previously-built tag). No-op for the ECR / registry pull paths.")).addOption(new Option("--container-host <host>", "Host to bind the agent port to").default("127.0.0.1")).addOption(new Option("--timeout <ms>", "Per-request timeout in milliseconds. Applied to POST /invocations, POST /mcp, and the /ws open-to-close window. Raise this for long-running agent calls that exceed the default.").default(12e4).argParser(parseTimeoutMs)).addOption(new Option("--assume-role [arn]", "Assume the runtime's execution role and forward STS-issued temp credentials to the container so the agent runs with the deployed role. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) uses the runtime's RoleArn when it is a literal ARN; (3) `--no-assume-role` opts out. Off by default — the developer's shell credentials are forwarded unchanged.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Load cdkd's S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::ImportValue in env vars with the deployed physical IDs / cross-stack exports. Mutually exclusive with --from-cfn-stack.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. For CDK apps deployed via the upstream CDK CLI. Bare form uses the resolved stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state.")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).action(withErrorHandling(async (target, options) => {
+	const cmd = new Command("invoke-agentcore").description("Run a Bedrock AgentCore Runtime container locally and invoke it once over its protocol contract: HTTP (POST /invocations + GET /ping on 8080) or MCP (POST /mcp Streamable HTTP on 8000). Resolves the AWS::BedrockAgentCore::Runtime, pulls/builds its container, injects env vars + AWS credentials, and prints the response. For an MCP runtime, runs the session handshake then sends one JSON-RPC request (tools/list by default, or the method/params from --event). Target accepts a CDK display path (MyStack/MyAgent) or stack-qualified logical ID (MyStack:MyAgentRuntime1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick from a list. Supports the container artifact and the CodeConfiguration managed-runtime artifact (fromCodeAsset, built from source) on the HTTP + MCP protocols; the agent calls real AWS for managed services.").argument("[target]", "CDK display path or stack-qualified logical ID of the AgentCore Runtime to invoke (omit to pick interactively in a TTY)").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--session-id <id>", "AgentCore runtime session id header value (default: a random UUID)")).addOption(new Option("--ws", "Stream over the HTTP-protocol agent's bidirectional /ws WebSocket endpoint (on 8080) instead of POST /invocations: send --event as the first frame and print every received frame to stdout until the agent closes. When stdin is a TTY, auto-enters a REPL — each typed line is sent as a follow-up text frame until Ctrl-D / agent close; pipe from /dev/null to force one-shot in a TTY. Ignored for an MCP runtime.").default(false)).addOption(new Option("--watch", "Re-synth and reload the agent container on CDK source changes (follows cdk-local #270). Supported on the HTTP / AGUI protocols, both the --ws session AND the default one-shot POST /invocations (the reload re-runs the single shot). An interpreted-language source edit inside a CodeConfiguration source tree takes a soft-reload fast path (docker cp + docker restart, no rebuild); Dockerfile / compiled-source / asset-hash-changed / ambiguous edits force a full rebuild. For MCP / A2A runtimes --watch is a no-op WARN and the single shot proceeds.").default(false)).addOption(new Option("--bearer-token <jwt>", "Bearer JWT to present when the runtime declares a customJwtAuthorizer. Verified against the runtime OIDC discovery URL (signature / issuer / expiry / audience) before the container starts, then forwarded to /invocations as Authorization: Bearer <jwt>.")).addOption(new Option("--no-verify-auth", "Skip inbound JWT verification even when the runtime declares a customJwtAuthorizer (local-dev escape hatch). A --bearer-token, if given, is still forwarded.")).addOption(new Option("--sigv4", "Sign the /invocations POST with AWS SigV4 (service bedrock-agentcore) using the resolved credentials, matching the cloud default when the runtime declares no customJwtAuthorizer. Opt-in: default unsigned. Mutually exclusive with --bearer-token; ignored on a JWT-protected runtime.").default(false)).addOption(new Option("--platform <platform>", "docker --platform for the agent container (linux/amd64 or linux/arm64)").choices(["linux/amd64", "linux/arm64"]).default("linux/arm64")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for the local-build path")).addOption(new Option("--no-build", "Skip docker build on the local-asset path (use the previously-built tag). No-op for the ECR / registry pull paths.")).addOption(new Option("--container-host <host>", "Host to bind the agent port to").default("127.0.0.1")).addOption(new Option("--timeout <ms>", "Per-request timeout in milliseconds. Applied to POST /invocations, POST /mcp, and the /ws open-to-close window. Raise this for long-running agent calls that exceed the default.").default(12e4).argParser(parseTimeoutMs)).addOption(new Option("--assume-role [arn]", "Assume the runtime's execution role and forward STS-issued temp credentials to the container so the agent runs with the deployed role. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) uses the runtime's RoleArn when it is a literal ARN; (3) `--no-assume-role` opts out. Off by default — the developer's shell credentials are forwarded unchanged.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Load cdkd's S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::ImportValue in env vars with the deployed physical IDs / cross-stack exports. Mutually exclusive with --from-cfn-stack.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. For CDK apps deployed via the upstream CDK CLI. Bare form uses the resolved stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state.")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.").argParser(parseStackRegion)).action(withErrorHandling(async (target, options) => {
 		await localInvokeAgentCoreCommand(target, options);
 	}));
 	[
@@ -88743,7 +88714,7 @@ function pickReferencedLogicalId(intrinsic) {
 function createLocalCommand() {
 	setEmbedConfig(CDKD_EMBED_CONFIG);
 	const local = new Command("local").description("Local execution of Lambda functions (RIE) and ECS task definitions (Docker required)");
-	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name; pass an explicit value when CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).action(withErrorHandling(localInvokeCommand));
+	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name; pass an explicit value when CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).").argParser(parseStackRegion)).action(withErrorHandling(localInvokeCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -89876,9 +89847,10 @@ function buildProgram() {
 	program.addCommand(createLocalCommand());
 	program.addCommand(createExportCommand());
 	program.addCommand(createMigrateCommand());
+	guardStackRegionOptions(program);
 	return program;
 }
 
 //#endregion
 export { buildProgram };
-//# sourceMappingURL=program-BSanOkkV.js.map
+//# sourceMappingURL=program-C-xfsrSP.js.map