@go-to-k/cdkd 0.285.13 → 0.285.15

package/dist/{program-DHJ4G_ZZ.js → program-D8-mNNcf.js}

@@ -1,8 +1,8 @@
-import { $ as DEFAULT_STATE_PREFIX, $n as resolveUseCdkBootstrapAssets, $t as isSingleDynamicReferenceToken, A as bold, An as validateAssetBucketName, Ar as LocalStartServiceError, At as requireConfigObject, B as secretBearingStateKeyWarning, Bn as runDockerStreaming, 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 ProvisioningError, Ft as s3BucketDomainName, G as clearOnUpdateRemoval, Gn as getDefaultStateBucketName, Gr as withErrorHandling, Gt as TemplateParser, H as getCurrentResourceSecrets, Hn as getDockerImageBySourceHash, Ht as describeTypeWithThrottleRetry, I as collectDeclaredOutputNames, In as formatDockerLoginError, Ir as ResourceTimeoutError, It as s3BucketDualStackDomainName, J as findSilentDropProperties, Jn as resolveAutoAssetStorage, Jr as isThrottlingError, Jt as TEMPLATE_SOURCED_RULES, K as ProviderRegistry, Kn as getLegacyStateBucketName, Kr as isMarkedNonRetryable, Kt as STATE_SOURCED_CROSS_GENERATION_RULES, L as collectPublishedOutputNames, Ln as getDockerCmd, Lr as ResourceUpdateNotSupportedError, Lt as s3BucketRegionalDomainName, M as gray, Mn as buildDenyExternalAccessPolicy, Mr as MissingCdkCliError, Mt as classifyReplaySecretRegion, N as green, Nn as describeAwsFailure, Nr as NestedStackChildDirectDestroyError, Nt as producerRegionsFromState, O as renderStatefulReason, On as parseBootstrapMarker, Or as LocalInvokeBuildError$1, Ot as replayWarn, P as red, Pn as buildDockerImage, Pr as PartialFailureError, Pt as s3BucketArn, Q as CUSTOM_RESOURCE_RESPONSE_PREFIX, Qn as resolveStateBucketWithDefaultAndSource, Qr as retryClassificationText, Qt as errorCauseChain, R as exportAliasCollisionScrubWarning, Rn as partitionSensitiveEnv, Rr as StackHasActiveImportsError, 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, Wr as normalizeAwsError, Wt as DagBuilder, X as maskDeep, Xn as resolveSkipPrefix, Xr as markNonRetryable, Xt as createSecretMasker, Y as createMaskedRetryLogger, Yn as resolveCaptureObservedState, Yr as isTransientServerError, Yt as carriesSecretMask, Z as maskerOrIdentity, Zn as resolveStateBucketWithDefault, Zr as markRedactedCause, 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, jt as requireConfigString, k as formatResourceLine, kn as readBootstrapMarkerBody, kr as LocalMigrateError, 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 isRetryableTransientError, 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 StackTerminationProtectionError, zt as applyRoleArnIfSet } from "./deploy-engine-DhMm2M33.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-DPh-XamZ.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-FLW4rE5A.js";
-import { t as ASGProvider } from "./asg-provider-DcFgnQQO.js";
+import { t as getCdkdVersion } from "./version-Dcdouqd3.js";
+import { t as ASGProvider } from "./asg-provider-CKEf903K.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
 /**
@@ -65391,15 +65356,14 @@ const DYNAMIC_REFERENCE_OPENING = "{{resolve:";
 * unactionable for prose. Requiring the service makes the count a count of
 * SECRET references rather than of the characters `{{resolve:`.
 *
-* `secretsmanager` / `ssm` mirror `REPLAY_SECRET_SERVICES` in
-* `rollback-executor.ts`, whose {@link classifyReplaySecretRegion} is what
-* classifies the tokens below — the same set on both sides, so the count and
-* the classification never disagree about what is in scope. `ssm-secure` is
-* added on top: it IS a CloudFormation secret spelling, and although cdkd does
-* not resolve it today (the resolver's unsupported-service arm leaves it
-* verbatim, so it can never become a wrong-region needle), counting it costs
-* only an assembled `ssm-secure` reference in a cross-region stack and keeps
-* the guard correct the day that arm changes.
+* All three mirror `REPLAY_SECRET_SERVICES` in
+* `secret-region-classification.ts`, whose {@link classifyReplaySecretRegion}
+* is what classifies the tokens below — the same set on both sides, so the
+* count and the classification never disagree about what is in scope. Until
+* issue #2482 `ssm-secure` was counted here AHEAD of that set (cdkd did not
+* resolve it, so it could never become a wrong-region needle, and counting it
+* kept the guard correct for the day the resolver's arm changed); that day
+* came, and the two lists agree again.
 *
 * THE TRADE, stated rather than hidden: an `Fn::Join` that splits BEFORE the
 * service name (`['{{resolve:', 'secretsmanager:db:SecretString:pw}}']`) has no
@@ -67751,9 +67715,9 @@ var DriftDetectedError = class DriftDetectedError extends CdkdError {
 *
 * SCOPED TO THE CLEARABLE CAUSES, not to everything the report calls
 * `notCompared`. The roll-up also contains resources whose only problem is a
-* surviving `{{resolve:ssm-secure:...}}` token — a pre-existing population cdkd resolves
-* for nobody, which can never clear on a re-run, and which this change did not
-* create. Exiting non-zero for them would break `cdkd drift` in CI forever over
+* surviving `{{resolve:...}}` token cdkd resolves for nobody — a look-alike
+* spelling, since issue #2482 moved `ssm-secure` onto the `ssm` path — which
+* can never clear on a re-run, and which this change did not create. Exiting non-zero for them would break `cdkd drift` in CI forever over
 * an unrelated defect, so the exit reads `refused` and `readFailed` while the
 * report covers all three. See `NotComparedCause` and `outcomeExitSignal`.
 *
@@ -67787,12 +67751,15 @@ var DriftDetectedError = class DriftDetectedError extends CdkdError {
 * honest SENTENCE, since their no-drift line claimed a clean bill of health for
 * a stack they had not read. See {@link incompleteRemediationMessage}.
 *
-* WHAT DOES NOT TRIGGER IT: a stack whose properties reference
-* `{{resolve:ssm-secure:...}}` still exits 0. Those properties genuinely are not
-* compared and the report says so, but nothing REFUSED them — cdkd has never
-* resolved that spelling — so the condition is permanent, unclearable by any
-* action the user can take, and predates this change. It is reported as
-* information and kept out of the exit code.
+* WHAT DOES NOT TRIGGER IT: a stack whose properties carry a `{{resolve:...}}`
+* spelling cdkd resolves for nobody still exits 0. Those properties genuinely
+* are not compared and the report says so, but nothing REFUSED them — cdkd has
+* never resolved that spelling — so the condition is permanent, unclearable by
+* any action the user can take, and predates this change. It is reported as
+* information and kept out of the exit code. (`ssm-secure` was that spelling
+* when this was written; since issue #2482 it resolves like `ssm`, and a
+* lookup that fails for it lands with the other resolution failures, not
+* here.)
 *
 * Carries no message of its own for the same reason {@link DriftDetectedError}
 * does -- the report was already printed.
@@ -67863,8 +67830,7 @@ function notComparedOutcomes(report) {
 * code covers only the CLEARABLE ones — `refused` (the population #2108 created)
 * and `readFailed` (issues #2151 / #1945). Exiting non-zero on
 * `unresolvedToken` would break `cdkd drift` in CI forever for every stack
-* holding an `{{resolve:ssm-secure:...}}` reference — permanent, unclearable,
-* and unrelated. See {@link NotComparedCause}.
+* holding such a spelling — permanent, unclearable, and unrelated. See {@link NotComparedCause}.
 *
 * A `drifted` outcome reports `drifted` even when its own comparison was
 * refused: drift is the stronger, actionable signal and the caller ranks it
@@ -68000,7 +67966,7 @@ function uncomparedTally(reports) {
 *
 *   - The TRIGGER is `anyIncomplete`, i.e. {@link outcomeExitSignal}'s
 *     `incomplete`. It is narrow on purpose: a stack whose ONLY uncompared
-*     resource holds a `{{resolve:ssm-secure:...}}` token must not start
+*     resource holds a `{{resolve:...}}` token cdkd resolves for nobody must not start
 *     shouting on every run about a comparison no action of the user's can ever
 *     complete -- the same CI-forever hazard that cause is kept out of the exit
 *     code on.
@@ -68285,25 +68251,6 @@ function carriesRecordedSecret(value, secrets) {
 	return false;
 }
 /**
-* Is this unresolvable token one whose value is a SECRET by definition?
-*
-* `ssm-secure` is the only such spelling, and it is decidable with no lookup:
-* CloudFormation defines exactly three dynamic-reference services (`ssm`,
-* `ssm-secure`, `secretsmanager`), cdkd resolves the other two, and
-* `ssm-secure` is the encrypted one.
-*
-* Anything else reaching the survivor arm is not a CloudFormation dynamic
-* reference at all — it is text that merely looks like one — and treating it as
-* secret is not the safe direction it appears to be: the path would be masked
-* to `***`, refused by `--accept`, and pinned to the live value by
-* {@link preserveLiveValuesAtUnresolvedTokens}, which is permanently stuck
-* drift with no remedy the user can apply. Such a token is still REPORTED; it
-* just does not claim to be a secret.
-*/
-function isSecretBySpelling(token) {
-	return token.startsWith("{{resolve:ssm-secure:");
-}
-/**
 * Every `{{resolve:...}}` token still present in `value`.
 *
 * Used to NAME an unresolvable reference without quoting the string it sits in.
@@ -68456,10 +68403,13 @@ var DriftSecretRefusalError = class DriftSecretRefusalError extends CdkdError {
 /**
 * Whether an error thrown out of `resolveStateSecretExpressions` is a
 * deliberate REFUSAL rather than a failed read. See
-* {@link DriftSecretRefusalError}.
+* {@link DriftSecretRefusalError} — drift's own region refusal — and
+* `IntrinsicResolutionRefusalError`, the resolver's: since issue #2482 the
+* `ssm-secure` arm refuses a definitive `String` / `StringList` parameter with
+* the latter, and that is a decision, not an IAM problem to go hunting for.
 */
 function isDriftSecretRefusal(err) {
-	return err instanceof DriftSecretRefusalError;
+	return err instanceof DriftSecretRefusalError || err instanceof IntrinsicResolutionRefusalError;
 }
 /**
 * One-line human phrasing for a {@link NotComparedCause}, used per entry in the
@@ -68638,17 +68588,19 @@ async function resolveDriftLeafByRegion(leaf, propertyPath, logicalId, consumerR
 *
 * A `{{resolve:...}}` token that SURVIVES the pass is reported through
 * `onUnresolved` and left in place — it is not an error. The resolver's
-* unsupported-service arm (`ssm-secure:` is the live example) warns and returns
-* the literal, and `cdkd deploy` resolves through the very same code, so AWS is
-* ALREADY holding that literal string and state records it. Replaying it is
-* therefore a correct no-op, and failing the resource over it would take every
-* other drifted property on that resource down with it (plus exit 2). The
-* report exists so the user learns cdkd is shipping a token it cannot resolve,
-* which is a real thing to know and not a reason to stop.
+* unsupported-service arm warns and returns the literal (`ssm-secure:` was the
+* live example until issue #2482 gave it an arm; what reaches it now is text
+* that merely looks like a reference), and `cdkd deploy` resolves through the
+* very same code, so AWS is ALREADY holding that literal string and state
+* records it. Replaying it is therefore a correct no-op, and failing the
+* resource over it would take every other drifted property on that resource
+* down with it (plus exit 2). The report exists so the user learns cdkd is
+* shipping a token it cannot resolve, which is a real thing to know and not a
+* reason to stop.
 *
 * Only the TOKENS are reported, never the leaf that held them: the leaf is
 * partially substituted by this point, so a mixed `secretsmanager` +
-* `ssm-secure` string comes back carrying real plaintext.
+* look-alike string comes back carrying real plaintext.
 *
 * Returns the input by identity when it holds no dynamic reference, so the
 * non-secret path is unchanged down to object identity.
@@ -68671,10 +68623,7 @@ async function resolveStateSecretExpressions(props, resolvers, secrets, options)
 			if (!v.includes("{{resolve:")) return v;
 			const resolved = await resolveDriftLeafByRegion(v, path, logicalId, consumerRegion, producerRegions, resolvers, ctx);
 			const survivors = survivingDynamicReferences(resolved).filter((t) => v.includes(t));
-			if (survivors.length > 0) {
-				if (survivors.some(isSecretBySpelling)) secretPaths?.add(path);
-				onUnresolved?.(survivors, path);
-			}
+			if (survivors.length > 0) onUnresolved?.(survivors, path);
 			if (carriesRecordedSecret(resolved, secrets)) secretPaths?.add(path);
 			return resolved;
 		}
@@ -68934,7 +68883,7 @@ async function runDriftForStack(stackName, region, stateBackend, providerRegistr
 					logger.warn(`${logicalId} (${resource.resourceType}): ` + (refused ? "refused to resolve a dynamic reference this resource's state records, so its secret-bearing properties are NOT compared — " : "could not resolve the dynamic reference(s) this resource's state records, so its secret-bearing properties are NOT compared — ") + `${maskSecretsInText(err instanceof Error ? err.message : String(err), secrets)}`);
 					secrets.clear();
 				}
-				if (unresolvedTokens.size > 0) logger.warn(`${logicalId} (${resource.resourceType}): cdkd cannot resolve ${maskSecretsInText([...unresolvedTokens].join(", "), secrets)} — those properties are NOT compared. A revert leaves a property whose WHOLE value is one of these tokens untouched; where a token is EMBEDDED in a longer string, the revert writes that string with the token literal, exactly as 'cdkd deploy' does — so a resolved value AWS holds there WOULD be overwritten. cdkd resolves 'secretsmanager' and 'ssm' references only.`);
+				if (unresolvedTokens.size > 0) logger.warn(`${logicalId} (${resource.resourceType}): cdkd cannot resolve ${maskSecretsInText([...unresolvedTokens].join(", "), secrets)} — those properties are NOT compared. A revert leaves a property whose WHOLE value is one of these tokens untouched; where a token is EMBEDDED in a longer string, the revert writes that string with the token literal, exactly as 'cdkd deploy' does — so a resolved value AWS holds there WOULD be overwritten. cdkd resolves 'secretsmanager', 'ssm' and 'ssm-secure' references; anything else is left as written.`);
 				const observedIgnorePaths = useObserved ? undeclaredEmptyObservedKeys(resource.observedProperties, resource.properties ?? {}) : [];
 				const normalized = await canonicalizePrincipalUniqueIds(comparisonBaseline, aws, resolvePrincipalUniqueId);
 				const protocolNormalized = canonicalizeIpProtocols(normalized.baseline, normalized.aws, resource.resourceType);
@@ -69505,19 +69454,24 @@ function mergeUntemplatedValue(awsValue, desiredValue) {
 * warning, on the premise that `cdkd deploy` resolves through the
 * resolver's same unsupported-service arm — so AWS already holds the literal
 * and replaying it is a no-op. **That premise holds only for records cdkd
-* deployed.** CloudFormation resolves `ssm-secure` SERVER-side, so a record
-* adopted by `cdkd import --migrate-from-cloudformation` has the literal token
-* in state while the live resource holds the PLAINTEXT. `diffAt` skips such a
-* leaf, so it never drifts — but `buildRevertNewProperties` overlays the whole
-* top-level subtree when any SIBLING key drifts, which would push the literal
-* token over a resolved value. That is defect 1 of this issue surviving in a
-* narrower case, on a live AWS write.
+* deployed.** A record adopted by `cdkd import --migrate-from-cloudformation`,
+* or one whose position was edited out of band, holds something ELSE there.
+* `diffAt` skips such a leaf, so it never drifts — but
+* `buildRevertNewProperties` overlays the whole top-level subtree when any
+* SIBLING key drifts, which would push the literal token over that value. That
+* is defect 1 of this issue surviving in a narrower case, on a live AWS write.
+*
+* (When this was written the population was `ssm-secure`, which CloudFormation
+* resolves SERVER-side, so a migrated record held the PLAINTEXT on AWS. Since
+* issue #2482 cdkd resolves that spelling itself and the token never reaches
+* this pass; what survives is a spelling nobody resolves, so the live value
+* here is whatever the user or another tool put at that position.)
 *
 * Deciding by PROVENANCE would need a flag state does not carry. Deciding by
 * what AWS actually holds needs nothing and is exact in both directions: for a
 * cdkd-deployed record AWS holds the token, so copying it back is the same
-* no-op the premise described; for a migrated record AWS holds the resolved
-* value, which is left untouched.
+* no-op the premise described; for any other record AWS holds a value cdkd
+* cannot compare, which is left untouched.
 *
 * Falls back to KEEPING the token wherever AWS has nothing at that position —
 * that is what `cdkd deploy` sends, so it is the safe residual rather than
@@ -69525,12 +69479,11 @@ function mergeUntemplatedValue(awsValue, desiredValue) {
 * and bails to that same residual on any length mismatch, since a reordered
 * readback cannot be positioned against.
 */
-function preserveLiveValuesAtUnresolvedTokens(send, awsProperties, secrets) {
+function preserveLiveValuesAtUnresolvedTokens(send, awsProperties) {
 	const walk = (value, live) => {
 		if (typeof value === "string" && value.includes("{{resolve:")) {
 			if (!isSingleDynamicReferenceToken(value)) return value;
 			if (live === void 0) return value;
-			if (typeof live === "string" && live.length >= MIN_SECRET_NEEDLE_LENGTH && isSecretBySpelling(value)) secrets.set(live, value);
 			return live;
 		}
 		if (Array.isArray(value)) {
@@ -69884,7 +69837,7 @@ async function runRevert(reports, providerRegistry, stateBackend, stateConfig, a
 				let newProperties;
 				try {
 					const overlaid = buildRevertNewProperties(outcome.changes, desiredProperties, outcome.awsProperties, { preserveUntemplated: stateResource.observedProperties === void 0 });
-					const maskPreserved = preserveLiveValuesAtMaskedLeaves(unresolvedTokens.size > 0 ? preserveLiveValuesAtUnresolvedTokens(overlaid, outcome.awsProperties, secrets) : overlaid, outcome.awsProperties, secrets);
+					const maskPreserved = preserveLiveValuesAtMaskedLeaves(unresolvedTokens.size > 0 ? preserveLiveValuesAtUnresolvedTokens(overlaid, outcome.awsProperties) : overlaid, outcome.awsProperties, secrets);
 					if (maskPreserved.unpreservablePaths.length > 0) {
 						totalUnresolvable++;
 						logger.error(`  ✗ ${report.stackName}/${outcome.logicalId} (${outcome.resourceType}): refused to revert ${maskPreserved.unpreservablePaths.join(", ")} — the recorded baseline holds only the redaction mask there (a NoEcho custom-resource value), and AWS reports nothing to preserve, so cdkd has no value it may write. Force that custom resource to update (change one of its properties, e.g. a nonce) and re-deploy, so its handler runs again and supplies the value — an ordinary re-deploy leaves it unchanged and the mask stays.`);
@@ -70240,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.
@@ -70679,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}?`)) {
@@ -70686,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;
@@ -70864,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.
 */
@@ -74503,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 (currently only AWS::ApiGatewayV2::Stage, emitted by CDK HttpApi). 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,
@@ -75100,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,
@@ -75117,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;
@@ -75130,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 {
@@ -75145,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.
@@ -75939,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
@@ -76553,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"
@@ -78520,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,
@@ -78809,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,
@@ -85095,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,
@@ -86331,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,
@@ -87755,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);
 	}));
 	[
@@ -88755,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,
@@ -89888,9 +89847,10 @@ function buildProgram() {
 	program.addCommand(createLocalCommand());
 	program.addCommand(createExportCommand());
 	program.addCommand(createMigrateCommand());
+	guardStackRegionOptions(program);
 	return program;
 }
 
 //#endregion
 export { buildProgram };
-//# sourceMappingURL=program-DHJ4G_ZZ.js.map
+//# sourceMappingURL=program-D8-mNNcf.js.map