@go-to-k/cdkd 0.286.1 → 0.286.3

package/dist/{deploy-engine-D0RCEQ6D.js → deploy-engine--rkIGhow.js}

@@ -1,9 +1,9 @@
 import { _ as withStackName, d as applyDefaultNameForFallback, f as generateResourceName, h as looksLikeCdkdGeneratedName, m as getCurrentStackName, n as getLogger, p as generateResourceNameWithFallback, r as isStdoutReservedForPayload, s as getLiveRenderer } from "./logger-Dw-3y48G.js";
 import { t as awsClientDefaults } from "./aws-client-defaults-D-iYiIJ6.js";
-import { t as getCdkdVersion } from "./version-CnQK6Jeh.js";
+import { t as getCdkdVersion } from "./version-D3md0Lde.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
-import { CreateBucketCommand, DeleteObjectCommand, DeleteObjectsCommand, GetBucketLocationCommand, GetObjectCommand, HeadBucketCommand, HeadObjectCommand, ListObjectVersionsCommand, ListObjectsV2Command, NoSuchKey, PutBucketEncryptionCommand, PutBucketPolicyCommand, PutObjectCommand, PutPublicAccessBlockCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
+import { CreateBucketCommand, DeleteObjectCommand, DeleteObjectsCommand, GetBucketLocationCommand, GetBucketReplicationCommand, GetObjectCommand, HeadBucketCommand, HeadObjectCommand, ListObjectVersionsCommand, ListObjectsV2Command, NoSuchKey, PutBucketEncryptionCommand, PutBucketPolicyCommand, PutObjectCommand, PutPublicAccessBlockCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
 import { CloudControlClient, CreateResourceCommand, DeleteResourceCommand, GetResourceCommand, GetResourceRequestStatusCommand, ListResourcesCommand, UpdateResourceCommand } from "@aws-sdk/client-cloudcontrol";
 import { AttachRolePolicyCommand, CreateRoleCommand, DeleteRoleCommand, DeleteRolePermissionsBoundaryCommand, DeleteRolePolicyCommand, DetachRolePolicyCommand, GetRoleCommand, GetRolePolicyCommand, IAMClient, ListAttachedRolePoliciesCommand, ListInstanceProfilesForRoleCommand, ListRolePoliciesCommand, ListRoleTagsCommand, NoSuchEntityException, PutRolePermissionsBoundaryCommand, PutRolePolicyCommand, RemoveRoleFromInstanceProfileCommand, TagRoleCommand, UntagRoleCommand, UpdateAssumeRolePolicyCommand, UpdateRoleCommand } from "@aws-sdk/client-iam";
 import { SQSClient } from "@aws-sdk/client-sqs";
@@ -35,6 +35,7 @@ import { KMSClient, ListAliasesCommand } from "@aws-sdk/client-kms";
 import { readFile } from "fs/promises";
 import { join as join$1 } from "path";
 import { CreateRepositoryCommand, DescribeImagesCommand as DescribeImagesCommand$1, DescribeRepositoriesCommand, ECRClient, GetAuthorizationTokenCommand, PutImageTagMutabilityCommand } from "@aws-sdk/client-ecr";
+import { inspect } from "node:util";
 import { hostname } from "os";
 import graphlib from "graphlib";
 import { DescribeDBClustersCommand, DescribeDBInstancesCommand, RDSClient } from "@aws-sdk/client-rds";
@@ -836,6 +837,116 @@ function isNameCooldownError(message) {
 function isRecreateRetryableError(message) {
 	return isNameCollisionError(message) || isNameCooldownError(message);
 }
+/**
+* The Cloud Control exception NAME for "this resource type ships no handler
+* for the action you asked for" (issue
+* [#2520](https://github.com/go-to-k/cdkd/issues/2520)).
+*
+* A NAME, not a message fragment: AWS SDK v3 sets `error.name` to the service
+* exception's own identifier, which is a wire-level contract, while the prose
+* beside it is text AWS is free to reword. The sibling READ classifier in
+* `src/cli/commands/drift.ts` (`NO_READ_HANDLER_NAMES`) already keys on this
+* same name for the GET direction.
+*/
+const CC_UNSUPPORTED_ACTION_ERROR_NAME = "UnsupportedActionException";
+/**
+* The AWS prose the update-not-supported classifier accepted before the
+* structured signal existed. Kept as a TOP-LEVEL-only fallback — see
+* {@link isUpdateUnsupportedError} for why it is not walked down the chain.
+*/
+const CC_UPDATE_UNSUPPORTED_MESSAGE_FALLBACK = "does not support UPDATE";
+/**
+* True when a failed `provider.update()` for `logicalId` was rejected because
+* the resource type has no UPDATE handler at all — the signal the deploy
+* engine's update-failure fallback fires on, turning the update into a
+* replacement.
+*
+* ## Why the chain is walked
+*
+* `CloudControlProvider.handleError` WRAPS the raw AWS rejection in a
+* `ProvisioningError` and interpolates `err.message` only; the exception name
+* is never copied into the wrapper's text. Measured 2026-09-04: `aws
+* cloudcontrol update-resource --type-name AWS::DocDB::DBCluster` answers
+* `UnsupportedActionException` with the message `Resource type
+* AWS::DocDB::DBCluster does not support UPDATE action`, which does not repeat
+* the name. That is why the predicate's pre-#2520
+* `message.includes('UnsupportedActionException')` half matched nothing cdkd
+* produces, and why the structured read has to look one link down.
+*
+* Two structured signals, both read off a link rather than out of prose:
+*
+*  - `name` — the synchronous `UpdateResource` rejection, one cause link below
+*    the provider's wrapper.
+*  - `ccErrorCode` PLUS `ccOperation === 'UPDATE'` — the two fields
+*    `CloudControlOperationFailedError` carries for an asynchronous
+*    progress-event failure, read structurally exactly as
+*    `cloud-control-provider.ts` reads the code for `AlreadyExists` /
+*    `NotFound`. No async occurrence has been MEASURED
+*    (`UnsupportedActionException` is raised synchronously by `UpdateResource`
+*    today); the arm exists so the async shape cannot silently fall through to
+*    prose, and it is pinned by unit cases built from the real error class.
+*    `ccOperation` is required rather than decorative precisely BECAUSE the
+*    arm is unmeasured: a CREATE or DELETE sub-operation reporting the same
+*    code says nothing about whether the type has an UPDATE handler, and
+*    reading the code alone would let it trigger a DELETE + CREATE. The
+*    narrowing is not absolute and the gap is stated rather than papered over:
+*    such a failure arriving at the TOP level still classifies if its own
+*    MESSAGE quotes AWS's prose. Unreachable today —
+*    `CloudControlOperationFailedError`'s message is built as
+*    `${operation} failed for <id>: <StatusMessage>`, so a CREATE's text
+*    cannot contain the UPDATE phrase unless AWS puts it there — and closing
+*    it would mean anchoring the prose read on the operation too, which would
+*    narrow the retained pre-#2520 reach rather than preserve it.
+*
+* ## Why the walk stops at another resource's error
+*
+* `logicalId` is not decoration — it is the fence that keeps a chain walk from
+* being WIDER than the message read it replaces. `NestedStackProvider.update`
+* runs a whole child deploy inside the PARENT's `provider.update()` call, so a
+* child resource's Cloud Control rejection propagates into the parent's update
+* catch, several cause links down. An unanchored walk would classify that as
+* "the nested stack cannot be updated in place" and DELETE + CREATE the entire
+* child stack. The pre-#2520 message read was immune by accident — the child
+* engine's wrapper is `Failed to update resource <child>`, which quotes no AWS
+* text — and this anchor makes the immunity deliberate: `ProvisioningError`
+* and `ResourceUpdateNotSupportedError` both carry `logicalId`, so the walk
+* stops dead at the first link that names a resource other than the one being
+* updated.
+*
+* The prose fallback is read at the TOP LEVEL ONLY, exactly as the pre-#2520
+* predicate did, and for the same asymmetry: missing the signal fails the
+* deploy (safe), matching it too broadly replaces a resource nobody asked to
+* replace (unsafe). It is read INSIDE the walk, after the anchor, so the
+* anchor governs every route into a `true` — ordered ahead of it, the
+* nested-stack immunity would rest on the child engine's wrapper happening to
+* quote no AWS text, which is a property of another file.
+*
+* ## Codes deliberately NOT matched
+*
+* The Cloud Control handler error code `NotUpdatable` reports "this particular
+* patch is not applicable" (a create-only property, an invalid document)
+* rather than "the type has no UPDATE handler", and cdkd already routes the
+* create-only case through its own property-driven replacement — accepting it
+* here would convert ordinary update rejections into replacements.
+* `TypeNotFoundException`, which `handleError` wraps into the SAME sentence as
+* the unsupported-action case, is not matched either: an unregistered type has
+* no replacement story, so it must keep failing the deploy rather than
+* deleting the resource.
+*/
+function isUpdateUnsupportedError(error, logicalId) {
+	let current = error;
+	for (let depth = 0; current !== null && current !== void 0 && depth < MAX_CAUSE_CHAIN_DEPTH; depth++) {
+		const link = current;
+		if (typeof link.logicalId === "string" && link.logicalId !== logicalId) return false;
+		if (link.name === "UnsupportedActionException") return true;
+		if (link.ccErrorCode === "UnsupportedActionException" && link.ccOperation === "UPDATE") return true;
+		if (depth === 0) {
+			if ((current instanceof Error ? current.message : String(current)).includes("does not support UPDATE")) return true;
+		}
+		current = link.cause;
+	}
+	return false;
+}
 
 //#endregion
 //#region src/utils/error-handler.ts
@@ -3917,16 +4028,402 @@ function displaySafe(value, opts) {
 }
 
 //#endregion
-//#region src/state/s3-noncurrent-version-purge.ts
+//#region src/state/s3-replication-purge-gap.ts
+/**
+* Tell the user when S3 REPLICATION has silently kept the bodies that
+* {@link ../state/s3-noncurrent-version-purge.js | the noncurrent-version
+* purge} just removed (issue
+* [#2447](https://github.com/go-to-k/cdkd/issues/2447)).
+*
+* ## The hole this closes
+*
+* `purgeNoncurrentKeyVersions` exists so that "cdkd deleted the object" means
+* the body is no longer retrievable. It reaches that by issuing
+* `DeleteObjects` entries that name a specific `VersionId`.
+*
+* **S3 never replicates a version-id delete.** Replication propagates PUTs
+* and — only when `DeleteMarkerReplication` is enabled — delete markers; a
+* delete naming a version id is deliberately not replicated, so that a delete
+* on the source cannot destroy data on the destination. On a state bucket
+* with Cross-Region (CRR) or Same-Region (SRR) replication the purge is
+* therefore SOURCE-ONLY: the replica keeps its own copy of every version,
+* `GetObject` with a `VersionId` still returns the secret, and cdkd reports
+* the purge as complete because on the only bucket it knows about, it was.
+*
+* That is exactly the shape the purge was built to remove — an operation that
+* reports success while the value stays readable — reproduced one bucket over
+* and invisible from every signal cdkd emitted. The user is not merely
+* unprotected, they are REASSURED, which is the direction this repo treats as
+* a defect rather than a gap.
+*
+* ## Why a probe and not only a doc line
+*
+* Documentation reaches the reader who goes looking. This reaches the one who
+* does not, at the moment the false belief would be formed. The whole cost is
+* one bucket-metadata call per process (see the cache below) and one IAM
+* action the caller may well not hold.
+*
+* ## Degrading is the DEFAULT, not the failure
+*
+* The purge's contract is that a missing permission produces a warning and
+* never an abort, and a detector bolted onto it must not be able to break
+* that. So this module NEVER THROWS, and treats every non-answer as "we do
+* not know" rather than as either polarity:
+*
+* - `ReplicationConfigurationNotFoundError` — the answer "no replication
+*   configuration exists". S3 reports the ABSENCE of a configuration as an
+*   ERROR, not as an empty response body, so this arm is the ordinary case
+*   for almost every bucket and must not read as a failure.
+*   `ReplicationConfiguration` ABSENT from a 200 response is treated the same
+*   way: the SDK models the field as optional, and a modelled field is not a
+*   promise that the API populates it.
+* - `AccessDenied` and friends — the caller lacks
+*   `s3:GetReplicationConfiguration`. Logged at DEBUG and never at `warn`:
+*   the overwhelming majority of buckets are not replicated, so warning here
+*   would tell almost every user to grant a permission in order to be told
+*   nothing. The doc names the action for the user who wants the check.
+* - anything else (throttle, 5xx, network) — DEBUG, and deliberately NOT
+*   cached, so the next purge in the same process retries.
+*
+* ## What is cached, what is deduped, and why they are different keys
+*
+* The PROBE is cached per (bucket, asserted owner) for the process lifetime, as
+* the sibling `src/provisioning/create-only-properties.ts` caches its
+* `DescribeType` lookups and for the same reason: the answer cannot change
+* mid-run, the value stored is the in-flight PROMISE so concurrent purges share
+* one call, and only non-transient outcomes are kept. Without it a stack with
+* thirty custom resources would issue thirty identical `GetBucketReplication`
+* calls.
+*
+* The WARNING is deduped too, but on a DIFFERENT and deliberately wider key —
+* (bucket, object description, destinations) — with the repeats sent to
+* `debug`. The two keys answer two questions and must not be merged:
+*
+* - the bucket alone is not enough, because `lock-manager.ts` routes this
+*   module's `warn` sink to `debug` on the ordinary release path (it purges a
+*   heartbeat record on every command and must not warn about it). Keyed on the
+*   bucket, that demoted line would consume the one warning the rollback
+*   journal or the response sidecar needed;
+* - adding the description is still not enough, because two rules covering
+*   different prefixes can name DIFFERENT destinations. Purging a `cdkd/dev/…`
+*   key can match only the first rule; a later `cdkd/prod/…` purge under the
+*   same description matches both, and without the destinations in the key the
+*   user would clean the first replica and never learn the second one holds the
+*   production journal.
+*
+* Deduping at all is a departure from the sibling purge module, which
+* deliberately repeats its own failure warning. The difference is that a
+* failure RECURS — each one is another object cdkd could not remove — while
+* this is a fact about a BUCKET, identical every time it is re-derived.
+* Repeating it thirty times in a deploy adds nothing and erodes the failure
+* warning standing next to it.
+*/
 /**
 * Parenthetical used when a caller names nothing.
 *
-* True of ANY object this function is pointed at, which is the bar for a
-* default here: a caller that forgets to describe its object must still emit a
-* warning that is correct, just less specific. It deliberately does not guess
-* at content.
+* True of ANY object the purge is pointed at, which is the bar for a default
+* here: a caller that forgets to describe its object must still emit a warning
+* that is correct, just less specific. It deliberately does not guess at
+* content.
+*
+* Lives HERE rather than in `s3-noncurrent-version-purge.ts` only to keep the
+* import one-directional — the purge imports this module, so a shared constant
+* defined there and read here would be a cycle. It is the same sentence both
+* warnings fall back to, and one definition is what stops the two drifting.
+*/
+const DEFAULT_PURGED_OBJECT_DESCRIPTION = "the body of an object cdkd has just reported as removed";
+/**
+* Cache of the replication probe, holding the in-flight promise.
+*
+* Keyed on the bucket AND the `ExpectedBucketOwner` the caller asserts. The
+* SUCCESS answer does not depend on the owner assertion — two callers
+* differing only in whether they assert it read the same configuration — but
+* the FAILURE does: a mismatched-owner 403 is an answer about that caller's
+* request, and caching it under the bare bucket name silenced the detector for
+* every correctly-scoped caller in the process. cdkd has two shapes today (the
+* provider probes without an owner, the state backend and lock manager with
+* one), so the two are distinguishable in practice.
+*/
+const replicationProbeCache = /* @__PURE__ */ new Map();
+/**
+* (bucket, object description, destinations) triples already warned about.
+*
+* The one thing the warning says that VARIES is `objectDescription`; the rest
+* is a fact about the bucket, identical every time. So a stack with thirty
+* custom resources repeated a ~600-character warning thirty times while adding
+* no information after the first — and warning fatigue erodes the purge's own
+* failure warning standing next to it.
+*
+* Keyed on all three precisely so this cannot become a silence hole; the
+* module doc above gives the two failures a narrower key produces. Entries are
+* added only after the warning is actually emitted, so a throwing sink does
+* not burn a slot.
+*
+* RESIDUAL, bounded and recorded: cdkd cannot see whether the caller's sink
+* DEMOTED the line, so a `lock-manager.ts` release (which routes `warn` to
+* `debug`) claims the lock's slot and a later reap of a stale lock — which
+* would have warned — is suppressed. It is bounded to the LOCK description,
+* whose object the docs describe as carrying no secret, and to one process.
+*/
+const warnedWarnings = /* @__PURE__ */ new Set();
+/** How many destinations the warning names before it truncates. */
+const MAX_NAMED_DESTINATIONS = 3;
+/** Shown when a rule carries no `Destination.Bucket` for us to name. */
+const UNNAMED_DESTINATION = "<destination not named by the replication rule>";
+/**
+* Error codes meaning "this principal will never get an answer here".
+*
+* Cached like a real answer, because unlike a throttle they do not clear
+* within the process: retrying on every purge would spend one denied API call
+* per custom resource for a result that cannot change.
+*/
+const PERMANENT_DENIALS = /* @__PURE__ */ new Set([
+	"AccessDenied",
+	"AccessDeniedException",
+	"AllAccessDisabled",
+	"MethodNotAllowed",
+	"NotImplemented"
+]);
+/**
+* Credential-shaped failures that ARRIVE AS 403 and are nonetheless transient.
+*
+* Checked BEFORE the blanket 403 rule, which is the only way they can win:
+* `InvalidAccessKeyId` is the classic blip while an IAM principal or an
+* assumed-role credential propagates — this repo retries that whole class over
+* a 47.75 s schedule elsewhere — and an expired or skewed token clears on
+* refresh. Cached as permanent, ONE such blip on the first purge of a long
+* deploy would silence the detector for the rest of the process, which is the
+* "false silence leaves them believing a secret is gone" direction this module
+* forbids.
+*/
+const TRANSIENT_CREDENTIAL_CODES = /* @__PURE__ */ new Set([
+	"InvalidAccessKeyId",
+	"ExpiredToken",
+	"ExpiredTokenException",
+	"InvalidToken",
+	"TokenRefreshRequired",
+	"RequestTimeTooSkewed",
+	"RequestExpired"
+]);
+const describe$2 = (error) => error instanceof Error ? error.message : String(error);
+/**
+* Every wire error code the value offers, `name` and `Code` alike.
+*
+* NO PRECEDENCE, deliberately. An earlier revision collapsed the two to one
+* string and preferred a specific `name`, which had two failure modes in
+* opposite directions: preferring `name` unconditionally made the `Code`
+* fallback dead (`{ name: 'Error', Code: 'AccessDenied' }` classified as
+* retryable, so a denied principal re-probed on every purge), while
+* preferring a SPECIFIC `name` let a wrapper's own name hide
+* `Code: 'InvalidAccessKeyId'` and cache a credential blip as a permanent
+* denial. Membership is tested against every code the error carries, so
+* neither field can mask the other. (Verified against real S3: a missing
+* replication configuration arrives with that string on BOTH fields.)
+*
+* Null-safe because a `send` that rejects with `null` used to throw a
+* TypeError INSIDE the probe's own catch, leaving a REJECTED promise in the
+* cache forever: every later purge on that bucket then fell into the outer
+* `catch {}` with no warning and no debug line — a silently dead detector,
+* which is the worst possible failure for this module.
+*
+* This guard and `probe`'s rejection arm both serve one invariant — **no
+* rejection ever reaches the cache** — and the honest statement of their
+* relationship, measured one mutation at a time on 2026-09-05, is:
+*
+* - removing the ARM alone REDS a case (a rejection whose own `toString`
+*   throws: the guards pass that value through and `describe()` is what
+*   raises), so the arm is independently fenced;
+* - removing these GUARDS alone leaves the CACHING behaviour identical:
+*   `errorCodes` runs inside `runProbe`'s own catch, so a TypeError here is
+*   caught by the arm and produces the same `unknown` / `retry: true` /
+*   evicted outcome. What DOES change is the debug line's reason — guarded it
+*   reports the rejection (`: null`), unguarded it reports the classifier's
+*   own crash — and that difference is what the `throw null` case asserts, so
+*   the guards are fenced after all.
+*
+* They also earn their place structurally: classification is inside the catch
+* TODAY. An edit that hoists it out — or that adds a caller of `errorCodes`
+* outside a try — reinstates the original defect, in which a `null` rejection
+* crashed the classifier and left a REJECTED promise cached for the process,
+* so every later purge on that bucket fell into the outer `catch {}` with no
+* warning and no debug line: a silently dead detector.
+*/
+const errorCodes = (error) => {
+	if (error === null || typeof error !== "object" && typeof error !== "function") return [];
+	const e = error;
+	const codes = [];
+	if (typeof e.name === "string" && e.name.length > 0) codes.push(e.name);
+	if (typeof e.Code === "string" && e.Code.length > 0) codes.push(e.Code);
+	return codes;
+};
+/** True when ANY code the error carries is in `set`. */
+const hasCode = (error, set) => errorCodes(error).some((code) => set.has(code));
+const httpStatus = (error) => {
+	if (error === null || typeof error !== "object" && typeof error !== "function") return void 0;
+	const meta = error.$metadata;
+	return typeof meta?.httpStatusCode === "number" ? meta.httpStatusCode : void 0;
+};
+/**
+* Strip the ARN wrapper off `Destination.Bucket`, which S3 returns as
+* `arn:<partition>:s3:::<name>`.
+*
+* Partition-agnostic on purpose: `aws-cn` and `aws-us-gov` produce a
+* different second segment, and a hard-coded `arn:aws:s3:::` would leave the
+* whole ARN in the message there rather than mis-parse it — survivable, but
+* the regex costs nothing. A value that is not ARN-shaped is passed through
+* unchanged rather than rejected; the field is only ever displayed.
+*/
+function destinationName(bucketArn, account) {
+	if (bucketArn === void 0 || bucketArn === "") return UNNAMED_DESTINATION;
+	const name = bucketArn.replace(/^arn:[^:]*:s3:::/, "");
+	return account !== void 0 && account !== "" ? `${name} (account ${account})` : name;
+}
+/**
+* Reduce a `ReplicationConfiguration` to the ENABLED rules and their effective
+* prefixes.
+*
+* Exported for its own unit tests: the mapping from the four filter shapes S3
+* accepts onto one prefix string is the part with real cases in it, and
+* pinning it through a stubbed client would test the plumbing instead.
+*
+* Over-approximates DELIBERATELY, in the direction of warning:
+*
+* - a rule filtering on a TAG (`Filter.Tag`, or `Filter.And.Tags` with no
+*   `Prefix`) cannot be evaluated without reading each object's tag set, so
+*   its prefix reduces to `''` and it covers everything. A false warning
+*   sends the reader to look at a replica; a false silence leaves them
+*   believing a secret is gone.
+* - a `Disabled` rule is KEPT, flagged rather than dropped. Disabling a rule
+*   stops FUTURE replication; it does not remove what the rule already
+*   copied, so a bucket whose rule covered `cdkd/` last month and is disabled
+*   today still holds every body ever purged. Dropping it was the first cut
+*   and is the reassured-user failure this module exists to remove, arriving
+*   inside the module that removes it. A rule with no `Status` at all is kept
+*   as ENABLED: `Status` is required by the model, so an absent one means the
+*   response was not what we assumed — the same reason the sibling purge
+*   treats an absent `IsLatest` as "assume the unsafe thing is true".
+*
+* Pure: it reads only its argument, so no ambient locale, clock or
+* environment can change the answer.
+*/
+function normalizeReplicationRules(config) {
+	const targets = [];
+	for (const rule of config.Rules ?? []) {
+		const prefix = rule.Filter !== void 0 ? rule.Filter.Prefix ?? rule.Filter.And?.Prefix ?? "" : rule.Prefix ?? "";
+		targets.push({
+			prefix,
+			destination: destinationName(rule.Destination?.Bucket, rule.Destination?.Account),
+			enabled: rule.Status !== "Disabled"
+		});
+	}
+	return targets;
+}
+async function runProbe(s3Client, bucket, requestFields) {
+	try {
+		const config = (await s3Client.send(new GetBucketReplicationCommand({
+			Bucket: bucket,
+			...requestFields
+		}))).ReplicationConfiguration;
+		if (config === void 0) return { kind: "none" };
+		const rules = normalizeReplicationRules(config);
+		return rules.length === 0 ? { kind: "none" } : {
+			kind: "rules",
+			rules
+		};
+	} catch (error) {
+		if (errorCodes(error).includes("ReplicationConfigurationNotFoundError")) return { kind: "none" };
+		if (hasCode(error, TRANSIENT_CREDENTIAL_CODES)) return {
+			kind: "unknown",
+			reason: describe$2(error),
+			retry: true
+		};
+		const permanent = hasCode(error, PERMANENT_DENIALS) || httpStatus(error) === 403;
+		return {
+			kind: "unknown",
+			reason: describe$2(error),
+			retry: !permanent
+		};
+	}
+}
+function probe(s3Client, bucket, requestFields) {
+	const key = `${bucket}\u0000${requestFields.ExpectedBucketOwner ?? ""}`;
+	const cached = replicationProbeCache.get(key);
+	if (cached) return cached;
+	const pending = runProbe(s3Client, bucket, requestFields).then((result) => {
+		if (result.kind === "unknown" && result.retry) evictIfOwn(key, pending);
+		return result;
+	}, (error) => {
+		evictIfOwn(key, pending);
+		return {
+			kind: "unknown",
+			reason: describe$2(error),
+			retry: true
+		};
+	});
+	replicationProbeCache.set(key, pending);
+	return pending;
+}
+/**
+* Remove a cache entry only when it is still the one we put there.
+*
+* The identity check is UNFENCED by a test, deliberately and stated rather
+* than left to be discovered: the only way a stale probe can settle against a
+* newer entry under the same key is for something to have cleared the cache
+* mid-flight, and the sole clearer is `clearReplicationProbeCache()`, a
+* test-only helper. Writing a test for it would be writing a test for the test
+* helper. It is kept because the alternative is an unconditional `delete` that
+* is wrong the moment a non-test clearer appears.
 */
-const DEFAULT_OBJECT_DESCRIPTION = "the body of an object cdkd has just reported as removed";
+function evictIfOwn(key, own) {
+	if (replicationProbeCache.get(key) === own) replicationProbeCache.delete(key);
+}
+/**
+* Warn if replication on `bucket` covers any of `keys`.
+*
+* `keys` are the keys whose bodies were actually removed (or could not be
+* settled) — NOT everything the caller asked about. The purge scopes them; see
+* its call site for why announcing a survival that never happened is worse
+* than saying nothing.
+*
+* NEVER THROWS and never rejects: the caller runs on a cleanup path that must
+* not abort, and this is a diagnostic bolted onto it.
+*/
+async function warnIfPurgeIsReplicated(s3Client, bucket, keys, options = {}) {
+	if (keys.length === 0) return;
+	const emitDebug = (message) => {
+		const sink = options.logger;
+		if (sink?.debug) sink.debug(message);
+		else getLogger().child("s3-replication-check").debug(message);
+	};
+	try {
+		const safeBucket = displaySafe(bucket, { asciiOnly: true });
+		const result = await probe(s3Client, bucket, options.requestFields ?? {});
+		if (result.kind === "none") return;
+		if (result.kind === "unknown") {
+			emitDebug(`Could not determine whether s3://${safeBucket} is replicated (grant s3:GetReplicationConfiguration to enable the check): ${displaySafe(result.reason)}`);
+			return;
+		}
+		const covered = result.rules.filter((rule) => keys.some((key) => key.startsWith(rule.prefix)));
+		if (covered.length === 0) return;
+		const destinations = [...new Set(covered.map((rule) => rule.enabled ? rule.destination : `${rule.destination} (rule currently Disabled -- it stops FUTURE replication, not what it already copied)`))].sort();
+		const warnKey = [
+			bucket,
+			options.objectDescription ?? "",
+			...destinations
+		].join("\0");
+		if (warnedWarnings.has(warnKey)) {
+			emitDebug(`S3 replication on s3://${safeBucket} still covers purged keys (${options.objectDescription ?? "the body of an object cdkd has just reported as removed"}); already reported once this run for ${destinations.map((d) => displaySafe(d, { asciiOnly: true })).join(", ")}.`);
+			return;
+		}
+		const named = destinations.slice(0, MAX_NAMED_DESTINATIONS).map((d) => displaySafe(d, { asciiOnly: true }));
+		const elided = destinations.length - named.length;
+		(options.logger ?? getLogger().child("s3-replication-check")).warn(`S3 replication is enabled on s3://${safeBucket} and covers the key(s) cdkd just purged. S3 NEVER replicates a version-id delete, so the purge removed those versions from THIS bucket only — the copies in the destination bucket survive and remain readable there via GetObject with a VersionId (${options.objectDescription ?? "the body of an object cdkd has just reported as removed"}). cdkd cannot delete them. Remove them in the destination bucket yourself (aws s3api list-object-versions, then delete-object --version-id), or narrow the replication rule so it excludes the prefixes cdkd purges under. Destination(s): ${named.join(", ")}` + (elided > 0 ? ` (and ${elided} more; aws s3api get-bucket-replication --bucket ${safeBucket} lists them all)` : ""));
+		warnedWarnings.add(warnKey);
+	} catch {}
+}
+
+//#endregion
+//#region src/state/s3-noncurrent-version-purge.ts
 /**
 * `objectDescription` for the custom-resource response sidecar.
 *
@@ -4000,17 +4497,27 @@ async function purgeNoncurrentKeyVersions(s3Client, bucket, keys, options = {})
 	const prefixes = options.listPrefix !== void 0 ? [options.listPrefix] : keys;
 	const failed = /* @__PURE__ */ new Map();
 	const unknown = { n: 0 };
+	const purged = /* @__PURE__ */ new Set();
+	const unsettledBodies = /* @__PURE__ */ new Set();
 	for (const prefix of prefixes) try {
-		await purgeUnderPrefix(s3Client, bucket, prefix, wanted, requestFields, failed, unknown);
+		await purgeUnderPrefix(s3Client, bucket, prefix, wanted, requestFields, failed, unknown, purged, unsettledBodies);
 	} catch (error) {
 		const affected = options.listPrefix !== void 0 ? keys : [prefix];
-		for (const key of affected) recordFailure(failed, key, describe$1(error));
+		for (const key of affected) {
+			recordFailure(failed, key, describe$1(error));
+			unsettledBodies.add(key);
+		}
 	}
 	if (failed.size > 0) {
 		const named = [...failed.entries()].slice(0, MAX_NAMED_FAILURES).map(([key, reasons]) => displaySafe(`${key} (${reasons.join("; ")})`));
 		const elided = failed.size - named.length;
-		logger.warn(`Could not purge noncurrent versions of ${failed.size} key(s) in s3://${bucket}. Their previous versions survive and remain readable via GetObject with a VersionId (${options.objectDescription ?? DEFAULT_OBJECT_DESCRIPTION}). Grant s3:ListBucketVersions and s3:DeleteObjectVersion on the state bucket, or purge the key(s) by hand. Failures: ${named.join(", ")}` + (elided > 0 ? ` (and ${elided} more)` : ""));
+		logger.warn(`Could not purge noncurrent versions of ${failed.size} key(s) in s3://${displaySafe(bucket, { asciiOnly: true })}. Their previous versions survive and remain readable via GetObject with a VersionId (${options.objectDescription ?? "the body of an object cdkd has just reported as removed"}). Grant s3:ListBucketVersions and s3:DeleteObjectVersion on the state bucket, or purge the key(s) by hand. Failures: ${named.join(", ")}` + (elided > 0 ? ` (and ${elided} more)` : ""));
 	}
+	await warnIfPurgeIsReplicated(s3Client, bucket, [.../* @__PURE__ */ new Set([...purged, ...unsettledBodies])], {
+		requestFields,
+		logger,
+		...options.objectDescription !== void 0 && { objectDescription: options.objectDescription }
+	});
 }
 /**
 * Paginate `ListObjectVersions` under one prefix and delete every returned
@@ -4025,7 +4532,7 @@ async function purgeNoncurrentKeyVersions(s3Client, bucket, keys, options = {})
 * id is NOT filtered out on its own, because a bucket whose versioning was
 * SUSPENDED can carry a genuine noncurrent `'null'` version holding the body.
 */
-async function purgeUnderPrefix(s3Client, bucket, prefix, wanted, requestFields, failed, unknown) {
+async function purgeUnderPrefix(s3Client, bucket, prefix, wanted, requestFields, failed, unknown, purged, unsettledBodies) {
 	let keyMarker;
 	let versionIdMarker;
 	do {
@@ -4037,15 +4544,30 @@ async function purgeUnderPrefix(s3Client, bucket, prefix, wanted, requestFields,
 			...versionIdMarker !== void 0 && { VersionIdMarker: versionIdMarker }
 		}));
 		const stale = [];
-		for (const entry of [...resp.Versions ?? [], ...resp.DeleteMarkers ?? []]) {
+		const entries = [...(resp.Versions ?? []).map((entry) => ({
+			entry,
+			hasBody: true
+		})), ...(resp.DeleteMarkers ?? []).map((entry) => ({
+			entry,
+			hasBody: false
+		}))];
+		for (const { entry, hasBody } of entries) {
 			if (entry.Key === void 0 || !wanted.has(entry.Key)) continue;
-			if (entry.IsLatest === void 0) recordFailure(failed, entry.Key, `version ${entry.VersionId ?? "<unknown>"}: listing omitted IsLatest, so the entry was left alone rather than risk deleting a current version`);
+			if (entry.IsLatest === void 0) {
+				recordFailure(failed, entry.Key, `version ${entry.VersionId ?? "<unknown>"}: listing omitted IsLatest, so the entry was left alone rather than risk deleting a current version`);
+				if (hasBody) unsettledBodies.add(entry.Key);
+			}
 			if (entry.IsLatest !== false) continue;
-			if (!entry.VersionId) continue;
+			if (!entry.VersionId) {
+				recordFailure(failed, entry.Key, `listing returned a noncurrent entry with no VersionId, so it could not be deleted`);
+				if (hasBody) unsettledBodies.add(entry.Key);
+				continue;
+			}
 			stale.push({
 				Key: entry.Key,
 				VersionId: entry.VersionId
 			});
+			if (hasBody) purged.add(entry.Key);
 		}
 		for (let i = 0; i < stale.length; i += DELETE_BATCH_SIZE) {
 			const batch = stale.slice(i, i + DELETE_BATCH_SIZE);
@@ -4072,7 +4594,10 @@ async function purgeUnderPrefix(s3Client, bucket, prefix, wanted, requestFields,
 			}
 		}
 		if (resp.IsTruncated === true && resp.NextKeyMarker === void 0) {
-			for (const key of wanted) if (key.startsWith(prefix)) recordFailure(failed, key, TRUNCATED_NO_MARKER);
+			for (const key of wanted) if (key.startsWith(prefix)) {
+				recordFailure(failed, key, TRUNCATED_NO_MARKER);
+				unsettledBodies.add(key);
+			}
 		}
 		keyMarker = resp.IsTruncated === true ? resp.NextKeyMarker : void 0;
 		versionIdMarker = keyMarker !== void 0 ? resp.NextVersionIdMarker : void 0;
@@ -5963,6 +6488,374 @@ function mergeEnv(overrides) {
 	else merged[k] = v;
 	return merged;
 }
+/** Replaces a redacted argv VALUE wherever this module masks one. */
+const REDACTED_ARGV_VALUE = "***";
+/**
+* `docker` argv flags whose NEXT token is a `KEY=VALUE` pair built from
+* user-supplied template data, and whose VALUE therefore must not reach a
+* user-visible error string:
+*
+* - `-e` / `--env` — a container's `Environment.Variables` (Lambda) or
+*   `ContainerDefinition.Environment` (ECS), plus `--env-vars` overrides.
+*   Values that cdkd classifies as sensitive never get here at all
+*   ({@link partitionSensitiveEnv} emits those as a value-less `-e KEY`),
+*   but everything else does: connection strings, endpoints, API base URLs.
+* - `--opt` — `DockerVolumeConfiguration.DriverOpts`, which for the `local`
+*   driver carries mount options (`o=addr=…,username=…,password=…`).
+* - `--label` — `DockerVolumeConfiguration.Labels`, user-authored metadata.
+*
+* A flag NOT in this list keeps its value. For most of the argv that is
+* because the value is cdkd-authored or infrastructure-shaped — a container
+* id, an image ref, a `--subnet` CIDR, a `--format` template — and is the
+* diagnostic.
+*
+* That is NOT true of the whole remainder, and the residual is recorded here
+* rather than quietly implied: `--health-cmd`, `--ulimit`, `--link`,
+* `--entrypoint`, `--workdir` and the positional image + container command are
+* all template-supplied and still echoed. They stay unmasked deliberately —
+* each is a COMMAND or a structural knob whose text IS what an operator reads
+* the failure for, and none is a documented place to put a secret, unlike
+* `Environment` / `Secrets` / `DriverOpts`. Revisit per flag if a real leak is
+* found through one; do not widen the set on suspicion, since every addition
+* trades away diagnostic text.
+*/
+const ARGV_VALUE_BEARING_FLAGS = /* @__PURE__ */ new Set([
+	"-e",
+	"--env",
+	"--opt",
+	"--label"
+]);
+/**
+* Structural, whitespace-delimited form of {@link ARGV_VALUE_BEARING_FLAGS}
+* for scanning a STRING that embeds a space-joined argv. Keyed on the FLAG's
+* position — never on the secret's value, so an unrelated literal that merely
+* coincides with a value is left alone.
+*
+* What each piece actually buys, since one of them was mis-credited in review:
+* the `(^|\s)` lead is what stops `-e` matching inside `--env` (there is no
+* `m` flag, so `^` is start-of-INPUT), NOT the alternation order — reordering
+* the branches leaves every test green. The order is kept as belt and braces
+* only. The mandatory `\s+` after the flag IS load-bearing: it is what stops
+* `-easy` / `--environment` matching. The KEY is `[^\s=]*` rather than `+` so
+* an EMPTY key (`-e =value`) is masked too.
+*/
+const ARGV_VALUE_TOKEN_RE = /(^|\s)(--env|--label|--opt|-e)(\s+)([^\s=]*)=\S*/g;
+/**
+* Return a copy of `args` with the VALUE of every
+* {@link ARGV_VALUE_BEARING_FLAGS} pair replaced by `***`. The KEY survives —
+* "which variable" is the diagnostic, "what it was set to" is the disclosure.
+*
+* A value-less `-e KEY` (the form {@link partitionSensitiveEnv} emits for a
+* sensitive key) has nothing to mask and is returned unchanged. `args` is
+* never mutated: the redacted copy is for DISPLAY only, never for `spawn`.
+*/
+function redactDockerArgvValues(args) {
+	const out = [];
+	for (let i = 0; i < args.length; i++) {
+		const cur = args[i];
+		const next = args[i + 1];
+		if (ARGV_VALUE_BEARING_FLAGS.has(cur) && typeof next === "string") {
+			const eqIdx = next.indexOf("=");
+			if (eqIdx >= 0) {
+				out.push(cur, `${next.substring(0, eqIdx)}=${REDACTED_ARGV_VALUE}`);
+				i++;
+				continue;
+			}
+		}
+		out.push(cur);
+	}
+	return out;
+}
+/**
+* Redact argv-borne values inside an error TEXT before it reaches the user.
+*
+* **Wrap EVERY `execFile`-derived docker failure text in this**, including one
+* whose argv carries no user data today — `execFile` puts the WHOLE command
+* line into `err.message` (`Command failed: <file> <args joined by ' '>\n<stderr>`,
+* measured on Node 24), so any argv that later gains a `-e` pair starts leaking
+* with no edit to the error site. That silent-gap shape is exactly what
+* [#2440](https://github.com/go-to-k/cdkd/issues/2440) reported: the debug log
+* one screen earlier redacted the same argv and the error path did not.
+*
+* Two passes, both structural (positional), never value-based — matching on a
+* secret's VALUE would also blank an unrelated string that happens to equal it:
+*
+* 1. **Exact command-line substitution** (only when `args` is given). The raw
+*    `args.join(' ')` is replaced by {@link redactDockerArgvValues}' rendering
+*    of the same array. This is the pass that matters, because it is the only
+*    one that can mask a value CONTAINING WHITESPACE (`-e CFG={"a": 1}`), which
+*    no token scan of a space-joined string can delimit.
+* 2. **Token scan** ({@link ARGV_VALUE_TOKEN_RE}) over the result. Catches an
+*    argv echoed in a shape pass 1 cannot see — a future Node message format,
+*    a docker stderr quoting the flag back, or a call site with no `args` to
+*    hand. Deliberately fail-loud rather than fail-open: a `-e X=y` occurring
+*    in unrelated stderr prose loses its value and keeps its key.
+*
+* Idempotent (`-e KEY=***` re-masks to itself), so double-wrapping is safe.
+*
+* **Call sites should use a composer** ({@link describeDockerFailure} and its
+* siblings) rather than this function: the composers take a REQUIRED `args`,
+* which is what makes the redaction impossible to forget. This is the
+* primitive they are built from, exported so the four passes can be tested
+* against Node's real message shapes directly — it has no other caller in
+* `src/`, and that is deliberate rather than an oversight.
+*/
+function redactDockerArgvInText(text, args) {
+	let out = text;
+	if (args && args.length > 0) {
+		const maskedArgs = redactDockerArgvValues(args);
+		const raw = args.join(" ");
+		const masked = maskedArgs.join(" ");
+		if (masked !== raw) out = out.split(raw).join(masked);
+		for (let i = 0; i < args.length; i++) {
+			const rawArg = args[i];
+			const maskedArg = maskedArgs[i];
+			if (maskedArg === rawArg) continue;
+			if (!isSubstitutableToken(rawArg)) continue;
+			out = out.split(rawArg).join(maskedArg);
+			const escapedRaw = nodeQuotedRendering(rawArg);
+			const escapedMasked = nodeQuotedRendering(maskedArg);
+			if (escapedRaw !== void 0 && escapedMasked !== void 0 && escapedRaw !== rawArg) out = out.split(escapedRaw).join(escapedMasked);
+		}
+		out = repairSpawnRefusal(out, args, maskedArgs);
+	}
+	return out.replace(ARGV_VALUE_TOKEN_RE, (_match, lead, flag, gap, key) => `${lead}${flag}${gap}${key}=${REDACTED_ARGV_VALUE}`);
+}
+/**
+* Shortest VALUE that pass 1b will substitute as a bare token.
+*
+* Pass 1b's needle is the whole `KEY=VALUE` element, and it is replaced
+* EVERYWHERE in the text — so a tiny needle is a liability rather than a
+* protection. The empty-key case makes that concrete: a non-sensitive
+* `{ Name: '', Value: '1' }` produces the two-character token `=1`, and
+* substituting that rewrites every `=1` in the message (`--cpus=1`,
+* `status=1`, a path segment). Below this floor the value is not worth
+* protecting by substring match, and passes 1 and 3 still cover it in the
+* message shapes that carry a `-e ` prefix or the joined command line.
+*/
+const MIN_SUBSTITUTABLE_VALUE_LENGTH = 4;
+/** Is this `KEY=VALUE` element long enough to substitute as a bare token? */
+function isSubstitutableToken(arg) {
+	const eqIdx = arg.indexOf("=");
+	if (eqIdx < 0) return false;
+	return arg.length - eqIdx - 1 >= MIN_SUBSTITUTABLE_VALUE_LENGTH;
+}
+/**
+* Render `value` the way Node renders an argv element it quotes back at you —
+* i.e. with the SAME function Node used, `util.inspect`, minus the quote
+* characters it chose.
+*
+* This started as a hand-rolled `\xNN` escaper and it was WRONG for 16 of the
+* first 128 code points. Measured against real `execFile` rejections on Node
+* 24.19.0 (this repo, 2026-09-05): hand-rolled matched 4 of 13 cases,
+* `inspect` matched 13 of 13.
+*
+*   input        Node emits          hand-rolled built
+*   LF           `K=a\nb\x00S`        `K=a\x0ab\x00S`   (Node uses a short escape)
+*   DEL          `K=a\x7Fb\x00S`      `K=a\x7fb\x00S`   (Node uses UPPERCASE hex)
+*   backslash    `K=a\\b\x00S`        `K=a\b\x00S`     (not escaped at all)
+*
+* Every miss printed the whole secret. The trigger for this path is a NUL in
+* a value — binary-ish data, which almost always carries a second control
+* byte or a backslash — so the table missed the REALISTIC case and hit only
+* the synthetic NUL-alone one its own fixture happened to use.
+*
+* `slice(1, -1)` is safe across the quote Node picks: `inspect` switches
+* between `'`, `"` and a backtick depending on content and escapes whichever
+* it chose; because this is the same call Node made, the rendering matches
+* whatever it picked (verified for a value containing a single quote, a
+* double quote, both, and a backtick).
+*
+* The general lesson, and why this is no longer a table: do not re-implement
+* another program's formatter — call it.
+*/
+function nodeQuotedRendering(value) {
+	const rendered = inspect(value);
+	const quote = rendered[0];
+	if (quote === void 0 || !`'"\``.includes(quote)) return void 0;
+	if (rendered.length < 2 || !rendered.endsWith(quote)) return void 0;
+	const inner = rendered.slice(1, -1);
+	return inner.includes(`${quote} +`) ? void 0 : inner;
+}
+/**
+* Node's refusal to spawn, which QUOTES ONE argv element and names its INDEX:
+*
+*   The argument 'args[2]' must be a string without null bytes. Received '…'
+*
+* The one message shape where the index tells us exactly which of OUR args is
+* being echoed — so the clause can be REWRITTEN from cdkd's own copy of the
+* element rather than searched for. That matters because Node does not print
+* the element whole: it truncates near 200 characters and renders a
+* newline-bearing value as concatenated chunks, so no needle can match it.
+*
+* Global, and scanned to exhaustion rather than bailing on the first match.
+* Anchoring at `^` was an earlier attempt at forgery resistance and it was
+* WORSE: it made a refusal anywhere but position 0 unrepairable, which is a
+* LEAK, and a leak beats a truncated message every time. Pinning Node's
+* literal prefix keeps the forgery bar high without that trade.
+*
+* Pinning the wording has its own cost: if Node rewords the message the repair
+* silently stops firing. That is why `tests/unit/utils/docker-cmd.test.ts`
+* drives this path from a REAL rejection — a reword turns CI red instead of
+* turning the redaction off.
+*/
+const SPAWN_REFUSAL_RE = /The argument 'args\[(\d+)\]'[^']*?Received /g;
+/**
+* The quoted element Node prints after `Received `.
+*
+* Three shapes, and the third is the one that matters. `inspect` renders a
+* newline-bearing value as chunks joined by ` +`, and Node then SLICES the
+* whole rendering at 128 characters and appends `...` — so the last chunk is
+* usually UNTERMINATED:
+*
+*   Received 'DB_URL=AAA…\n' +
+*     'hunter2SECRETCCC...
+*
+* A pattern that only accepts complete chunks stops after the second `'` and
+* leaves that tail in place. Measured on a real rejection: 272 of 288 probe
+* shapes leaked the secret verbatim, and the end-of-string version this
+* replaced did not — the bound was a regression, not a hardening, until the
+* trailing open chunk was admitted.
+*
+* The separator is Node's own (` +\n  `) with HORIZONTAL space only, and an
+* open chunk runs to end of LINE. Both are deliberate: `\s*\+\s*` and an
+* unbounded tail let a crafted value swallow the diagnostic lines that follow
+* the clause.
+*/
+const QUOTED_CHUNK = String.raw`'(?:[^'\\\n]|\\.)*'|"(?:[^"\\\n]|\\.)*"|\`(?:[^\`\\\n]|\\.)*\``;
+/** An opening quote whose closing one was truncated away; bounded to its line. */
+const OPEN_CHUNK = String.raw`['"\`](?:[^\\\n]|\\.)*`;
+/** Node's chunk join: horizontal space, `+`, at most one newline, horizontal space. */
+const CHUNK_SEPARATOR = String.raw`[^\S\n]*\+[^\S\n]*\n?[^\S\n]*`;
+const QUOTED_ELEMENT_RE = new RegExp(`^(?:(?:${QUOTED_CHUNK})(?:${CHUNK_SEPARATOR}(?:${QUOTED_CHUNK}))*(?:${CHUNK_SEPARATOR}(?:${OPEN_CHUNK}))?|(?:${OPEN_CHUNK}))`);
+/**
+* Replace the quoted argv element in a spawn-refusal message with the masked
+* rendering of the arg its OWN index names.
+*
+* Known cosmetic effect: the replacement prints the FULL key where Node had
+* truncated, so a pathologically long env-var NAME makes the message longer
+* than Node's ~200 characters. Keys are not secret, and the width is not worth
+* a second truncation rule with its own edge cases.
+*/
+function repairSpawnRefusal(text, args, maskedArgs) {
+	const scanner = new RegExp(SPAWN_REFUSAL_RE.source, "g");
+	let out = "";
+	let cursor = 0;
+	for (let match = scanner.exec(text); match !== null; match = scanner.exec(text)) {
+		if (match.index < cursor) continue;
+		const index = Number(match[1]);
+		const rawArg = args[index];
+		const maskedArg = maskedArgs[index];
+		if (rawArg !== void 0 && maskedArg === rawArg) continue;
+		const clauseEnd = match.index + match[0].length;
+		const quoted = QUOTED_ELEMENT_RE.exec(text.slice(clauseEnd));
+		if (quoted === null) continue;
+		const replacement = maskedArg === void 0 ? `'${REDACTED_ARGV_VALUE}'` : inspect(maskedArg);
+		out += text.slice(cursor, clauseEnd) + replacement;
+		cursor = clauseEnd + quoted[0].length;
+		scanner.lastIndex = cursor;
+	}
+	return out + text.slice(cursor);
+}
+/**
+* Compose a user-visible description of a `child_process` rejection from a
+* docker call, ALREADY REDACTED against that call's own argv.
+*
+* Moved here from `src/local/invoke-agentcore-watch-loop.ts` in issue #2440's
+* review round 3, and the move is the point: `args` is REQUIRED, so a call
+* site cannot obtain the text without handing over the argv to redact it
+* with. That is a stronger guarantee than any text fence over the call sites
+* — which is what the round-2 reviewers demonstrated, by writing four
+* spellings of an unredacted read that the fence could not see.
+*
+* Shape differs from the `stderr || message` composition the other sites use,
+* and deliberately so: `err.stderr` is where docker writes its actionable
+* diagnostics, while `err.message` carries the exit status, so the AgentCore
+* soft-reload path APPENDS rather than prefers — without stderr the wrapped
+* error would only say "Command failed with exit code N".
+*/
+function describeDockerExecFailure(error, args) {
+	const message = thrownMessageText(error) || safeStringify(error);
+	const stderrText = capturedStreamText(error, "stderr");
+	return redactDockerArgvInText(stderrText ? `${message}\n${stderrText}` : message, args);
+}
+/**
+* A captured stream of a `child_process` rejection as trimmed text, or `''`.
+*
+* Takes `unknown`, not `Error`, and duck-types the field. Every composer here
+* is called from a `catch`, where the value is whatever was thrown — and the
+* shapes the call sites actually see are plain objects
+* (`{ stderr, message }`), `SpawnError`, and cross-realm `Error`s that
+* `instanceof` misses. An earlier revision narrowed this to `Error` and the
+* standard composer then wrapped non-Errors in a FRESH `Error`, which has no
+* `.stderr` at all — so the whole diagnostic silently became
+* `'[object Object]'` for exactly the shape most of the call sites throw.
+*
+* `execFile` hands back a string under the default encoding and a `Buffer`
+* under `encoding: 'buffer'`; `ArrayBuffer.isView` covers a plain
+* `Uint8Array` too.
+*/
+function capturedStreamText(error, field) {
+	try {
+		const raw = error?.[field];
+		if (typeof raw === "string") return raw.trim();
+		if (ArrayBuffer.isView(raw)) return Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString("utf8").trim();
+	} catch {}
+	return "";
+}
+/** A thrown value's `message` as text, or `''`. Duck-typed, for the same reason. */
+function thrownMessageText(error) {
+	try {
+		const raw = error?.["message"];
+		return typeof raw === "string" ? raw : "";
+	} catch {
+		return "";
+	}
+}
+/**
+* `String(value)` that cannot itself throw. A rejection with a null prototype
+* (or a `toString` that throws) would otherwise blow up INSIDE a `catch` — and
+* two of these call sites are in `cleanupEcsRun`, where an exception aborts
+* the remaining volume / network teardown and leaks real Docker resources.
+*/
+function safeStringify(error) {
+	try {
+		return String(error);
+	} catch {
+		return "[unstringifiable rejection]";
+	}
+}
+/**
+* The STANDARD composer for a docker failure text: the captured stderr if
+* there is any, else the error's own message, else its string form —
+* ALREADY REDACTED against that call's argv.
+*
+* Use this at every site that wraps a docker `execFile` / spawn rejection.
+* `args` is REQUIRED, which is the whole point: a call site cannot obtain the
+* text without handing over the argv to redact it with, so the guarantee is
+* type-checked rather than fenced. Issue #2440's review spent three rounds
+* showing that a text fence over hand-composed sites is evadable — an
+* intermediate variable, an inline cast, a destructure, a computed member, a
+* concat — while this shape has nothing to evade.
+*
+* Prefer stderr over message because docker writes its actionable diagnostic
+* there, and `execFile`'s message is mostly the command line plus an exit
+* status. {@link describeDockerExecFailure} keeps BOTH, for a caller whose
+* wrapper text needs the status as well.
+*/
+function describeDockerFailure(error, args) {
+	return redactDockerArgvInText(capturedStreamText(error, "stderr") || thrownMessageText(error) || safeStringify(error), args);
+}
+/**
+* Composer for a captured-output failure where the diagnostic may be on
+* STDOUT rather than stderr (`runDockerStreaming`'s non-zero-exit path, whose
+* `SpawnError` carries both). `fallback` is used when neither stream said
+* anything. Redacted, and `args` is required, for the same reason as
+* {@link describeDockerFailure}.
+*/
+function describeDockerCapturedOutput(error, args, fallback) {
+	return redactDockerArgvInText(capturedStreamText(error, "stderr") || capturedStreamText(error, "stdout") || fallback, args);
+}
 
 //#endregion
 //#region src/assets/docker-build.ts
@@ -21642,7 +22535,8 @@ function ccProtectionProperty(resourceType) {
 const NON_PROVISIONABLE_TYPES = /* @__PURE__ */ new Set([
 	"Alexa::ASK::Skill",
 	"AWS::AmazonMQ::ConfigurationAssociation",
-	"AWS::ApiGatewayV2::ApiGatewayManagedOverrides",
+	"AWS::Amplify::Jobs",
+	"AWS::AmplifyUIBuilder::CodegenJob",
 	"AWS::AppMesh::GatewayRoute",
 	"AWS::AppMesh::Mesh",
 	"AWS::AppMesh::Route",
@@ -21651,64 +22545,90 @@ const NON_PROVISIONABLE_TYPES = /* @__PURE__ */ new Set([
 	"AWS::AppMesh::VirtualRouter",
 	"AWS::AppMesh::VirtualService",
 	"AWS::AppStream::Fleet",
+	"AWS::AppStream::StackFleetAssociation",
 	"AWS::AppSync::ApiCache",
 	"AWS::Artifact::Report",
 	"AWS::Athena::Session",
 	"AWS::AutoScalingPlans::ScalingPlan",
 	"AWS::BackupSearch::SearchJob",
+	"AWS::BackupSearch::SearchResultExportJob",
 	"AWS::BCMDataExports::Table",
+	"AWS::Bedrock::AsyncInvoke",
 	"AWS::Bedrock::DefaultPromptRouter",
+	"AWS::Bedrock::FlowExecution",
+	"AWS::Bedrock::FoundationModel",
+	"AWS::Bedrock::ImportedModel",
+	"AWS::Bedrock::ModelImportJob",
 	"AWS::Bedrock::ModelInvocationJob",
+	"AWS::BedrockAgentCore::ConfigurationBundleVersion",
+	"AWS::BedrockAgentCore::HarnessVersion",
+	"AWS::BedrockAgentCore::PolicyGeneration",
 	"AWS::BedrockAgentCore::TokenVault",
+	"AWS::Braket::Job",
+	"AWS::Cassandra::Stream",
 	"AWS::Cloud9::EnvironmentEC2",
 	"AWS::CloudFormation::Macro",
 	"AWS::CloudFormation::ResourceScan",
 	"AWS::CloudFormation::WaitCondition",
 	"AWS::CloudFront::StreamingDistribution",
 	"AWS::CodeArtifact::Package",
-	"AWS::CodeBuild::ReportGroup",
+	"AWS::CodeBuild::Build",
+	"AWS::CodeBuild::BuildBatch",
 	"AWS::CodeBuild::Sandbox",
-	"AWS::CodeBuild::SourceCredential",
 	"AWS::CodeStar::GitHubRepository",
 	"AWS::CognitoSync::Dataset",
+	"AWS::Comprehend::DocumentClassificationJob",
+	"AWS::Comprehend::DominantLanguageDetectionJob",
+	"AWS::Comprehend::EntitiesDetectionJob",
+	"AWS::Comprehend::FlywheelDataset",
+	"AWS::Comprehend::SentimentDetectionJob",
+	"AWS::Comprehend::TargetedSentimentDetectionJob",
 	"AWS::Config::ConfigurationRecorder",
 	"AWS::Config::DeliveryChannel",
 	"AWS::Config::OrganizationConfigRule",
+	"AWS::ControlCatalog::CommonControl",
+	"AWS::ControlCatalog::Control",
 	"AWS::ControlCatalog::Objective",
+	"AWS::DataExchange::Assets",
+	"AWS::DataExchange::EntitledDataSets",
+	"AWS::DataExchange::Job",
+	"AWS::DataSync::TaskExecution",
 	"AWS::DAX::Cluster",
-	"AWS::DAX::ParameterGroup",
 	"AWS::DAX::SubnetGroup",
+	"AWS::Deadline::Job",
 	"AWS::DirectoryService::MicrosoftAD",
-	"AWS::DMS::EventSubscription",
 	"AWS::DMS::ReplicationInstance",
-	"AWS::DMS::ReplicationSubnetGroup",
-	"AWS::DMS::ReplicationTask",
-	"AWS::DocDB::DBClusterParameterGroup",
+	"AWS::DRS::RecoveryInstance",
 	"AWS::DynamoDB::Export",
+	"AWS::DynamoDB::Stream",
 	"AWS::EC2::ClientVpnAuthorizationRule",
 	"AWS::EC2::ClientVpnEndpoint",
 	"AWS::EC2::ClientVpnRoute",
 	"AWS::EC2::ClientVpnTargetNetworkAssociation",
+	"AWS::EC2::ExportInstanceTask",
 	"AWS::EC2::NetworkInterfacePermission",
+	"AWS::EC2::ReplaceRootVolumeTask",
+	"AWS::EC2::VpnConnectionDeviceType",
 	"AWS::EC2::VPNGatewayRoutePropagation",
+	"AWS::ECRPublic::Registry",
+	"AWS::ECS::ContainerInstance",
+	"AWS::ECS::Task",
 	"AWS::ElastiCache::ReservedCacheNode",
 	"AWS::ElastiCache::SecurityGroup",
 	"AWS::ElastiCache::SecurityGroupIngress",
 	"AWS::ElasticLoadBalancingV2::ListenerCertificate",
 	"AWS::Elasticsearch::Domain",
 	"AWS::EMR::NotebookExecution",
+	"AWS::EMRContainers::JobRun",
+	"AWS::EMRServerless::JobRun",
 	"AWS::Events::Replay",
+	"AWS::FIS::Experiment",
 	"AWS::FIS::SafetyLever",
 	"AWS::FSx::Snapshot",
 	"AWS::FSx::StorageVirtualMachine",
-	"AWS::FSx::Volume",
-	"AWS::Glue::Classifier",
-	"AWS::Glue::CustomEntityType",
-	"AWS::Glue::DataQualityRuleset",
 	"AWS::Glue::DevEndpoint",
-	"AWS::Glue::MLTransform",
 	"AWS::Glue::Partition",
-	"AWS::Glue::TableOptimizer",
+	"AWS::Glue::TableVersion",
 	"AWS::Greengrass::ConnectorDefinition",
 	"AWS::Greengrass::ConnectorDefinitionVersion",
 	"AWS::Greengrass::CoreDefinition",
@@ -21730,11 +22650,18 @@ const NON_PROVISIONABLE_TYPES = /* @__PURE__ */ new Set([
 	"AWS::IdentityStore::AllGroupMemberships",
 	"AWS::ImageBuilder::AllImageBuildVersions",
 	"AWS::ImageBuilder::AllWorkflowBuildVersions",
+	"AWS::ImageBuilder::LifecycleExecution",
 	"AWS::ImageBuilder::WorkflowExecution",
 	"AWS::ImageBuilder::WorkflowStepExecution",
+	"AWS::InternetMonitor::InternetEvent",
+	"AWS::IoT::Index",
 	"AWS::IoT::PolicyPrincipalAttachment",
 	"AWS::IoT::ThingPrincipalAttachment",
+	"AWS::IoTDeviceAdvisor::SuiteRun",
 	"AWS::IoTThingsGraph::FlowTemplate",
+	"AWS::IoTTwinMaker::MetadataTransferJob",
+	"AWS::IVS::Composition",
+	"AWS::KafkaConnect::ConnectorOperation",
 	"AWS::KinesisAnalytics::Application",
 	"AWS::KinesisAnalytics::ApplicationOutput",
 	"AWS::KinesisAnalytics::ApplicationReferenceDataSource",
@@ -21744,22 +22671,32 @@ const NON_PROVISIONABLE_TYPES = /* @__PURE__ */ new Set([
 	"AWS::LakeFormation::DataLakeSettings",
 	"AWS::LakeFormation::Permissions",
 	"AWS::LakeFormation::Resource",
+	"AWS::Lambda::DurableExecution",
+	"AWS::Lightsail::ExportSnapshotRecord",
+	"AWS::Location::Job",
+	"AWS::Macie2::ClassificationJob",
 	"AWS::ManagedBlockchain::Member",
 	"AWS::ManagedBlockchain::Node",
 	"AWS::MediaConnect::Offering",
 	"AWS::MediaConnect::Reservation",
 	"AWS::MediaConvert::JobTemplate",
-	"AWS::MediaConvert::Preset",
 	"AWS::MediaConvert::Queue",
 	"AWS::MediaLive::Channel",
 	"AWS::MediaLive::Input",
 	"AWS::MediaLive::InputSecurityGroup",
 	"AWS::MediaLive::Offering",
 	"AWS::MediaPackage::HarvestJob",
+	"AWS::MediaPackageV2::HarvestJob",
 	"AWS::MediaStore::Container",
+	"AWS::MedicalImaging::ImageSet",
 	"AWS::MemoryDB::MultiRegionParameterGroup",
 	"AWS::MemoryDB::ReservedNode",
+	"AWS::NeptuneGraph::ExportTask",
+	"AWS::NovaAct::WorkflowRun",
+	"AWS::Omics::ReadSet",
 	"AWS::Omics::Reference",
+	"AWS::Omics::Run",
+	"AWS::Omics::Task",
 	"AWS::OpsWorks::App",
 	"AWS::OpsWorks::ElasticLoadBalancerAttachment",
 	"AWS::OpsWorks::Instance",
@@ -21767,8 +22704,14 @@ const NON_PROVISIONABLE_TYPES = /* @__PURE__ */ new Set([
 	"AWS::OpsWorks::Stack",
 	"AWS::OpsWorks::UserProfile",
 	"AWS::OpsWorks::Volume",
+	"AWS::Organizations::Root",
 	"AWS::OSIS::PipelineBlueprint",
+	"AWS::PartnerCentral::ConnectionPreferences",
+	"AWS::PartnerCentral::Partner",
+	"AWS::Personalize::BatchInferenceJob",
+	"AWS::Personalize::BatchSegmentJob",
 	"AWS::Personalize::DataDeletionJob",
+	"AWS::Personalize::DatasetExportJob",
 	"AWS::Personalize::Recipe",
 	"AWS::Pinpoint::ADMChannel",
 	"AWS::Pinpoint::APNSChannel",
@@ -21793,33 +22736,50 @@ const NON_PROVISIONABLE_TYPES = /* @__PURE__ */ new Set([
 	"AWS::PinpointEmail::DedicatedIpPool",
 	"AWS::PinpointEmail::Identity",
 	"AWS::QLDB::Ledger",
+	"AWS::QuickSight::AssetBundleExportJob",
+	"AWS::QuickSight::AssetBundleImportJob",
 	"AWS::RDS::DBSecurityGroup",
 	"AWS::RDS::DBSecurityGroupIngress",
+	"AWS::RDS::ReservedDBInstance",
 	"AWS::Redshift::ClusterSecurityGroup",
 	"AWS::Redshift::ClusterSecurityGroupIngress",
+	"AWS::Redshift::DataShare",
 	"AWS::RedshiftServerless::RecoveryPoint",
+	"AWS::ResilienceHub::RecommendationTemplate",
 	"AWS::Route53::RecordSetGroup",
+	"AWS::Route53Resolver::FirewallConfig",
+	"AWS::SageMaker::AutoMLJob",
 	"AWS::SageMaker::CodeRepository",
-	"AWS::SageMaker::EndpointConfig",
+	"AWS::SageMaker::ExperimentTrialComponent",
+	"AWS::SageMaker::HubContentVersion",
+	"AWS::SageMaker::HyperParameterTuningJob",
 	"AWS::SageMaker::ModelCardExportJob",
 	"AWS::SageMaker::MonitoringScheduleAlert",
 	"AWS::SageMaker::NotebookInstance",
 	"AWS::SageMaker::NotebookInstanceLifecycleConfig",
+	"AWS::SageMaker::OptimizationJob",
+	"AWS::SageMaker::PipelineExecution",
+	"AWS::SageMaker::TrainingJob",
 	"AWS::SageMaker::TransformJob",
 	"AWS::SageMaker::Workteam",
-	"AWS::SDB::Domain",
+	"AWS::SavingsPlans::SavingsPlan",
+	"AWS::SecurityAgent::PentestTask",
 	"AWS::ServiceDiscovery::Instance",
-	"AWS::SES::ReceiptFilter",
-	"AWS::SES::ReceiptRule",
-	"AWS::SES::ReceiptRuleSet",
+	"AWS::ServiceQuotas::Quota",
 	"AWS::Signer::SigningJob",
+	"AWS::SSM::AutomationExecution",
+	"AWS::SSM::ManagedInstance",
 	"AWS::SSM::Session",
 	"AWS::SSO::ApplicationProvider",
 	"AWS::States::Execution",
 	"AWS::StepFunctions::MapRun",
 	"AWS::ThinClient::SoftwareSet",
+	"AWS::Transcribe::CallAnalyticsJob",
+	"AWS::Transcribe::MedicalScribeJob",
 	"AWS::Transcribe::MedicalTranscriptionJob",
+	"AWS::Transcribe::TranscriptionJob",
 	"AWS::UserNotifications::ManagedNotificationConfiguration",
+	"AWS::UserNotifications::NotificationEvent",
 	"AWS::WAF::ByteMatchSet",
 	"AWS::WAF::IPSet",
 	"AWS::WAF::Rule",
@@ -21837,7 +22797,9 @@ const NON_PROVISIONABLE_TYPES = /* @__PURE__ */ new Set([
 	"AWS::WAFRegional::SqlInjectionMatchSet",
 	"AWS::WAFRegional::WebACL",
 	"AWS::WAFRegional::WebACLAssociation",
-	"AWS::WAFRegional::XssMatchSet"
+	"AWS::WAFRegional::XssMatchSet",
+	"AWS::Wisdom::Session",
+	"AWS::WorkSpaces::WorkSpaceApplication"
 ]);
 
 //#endregion
@@ -22346,7 +23308,7 @@ var CloudControlProvider = class {
 		const indeterminateGuard = await this.confirmDeleteTargetIdentity(logicalId, resourceType, physicalId, context);
 		if (context?.removeProtection === true && resourceType === "AWS::AutoScaling::AutoScalingGroup") {
 			this.logger.debug(`Delegating protected AutoScalingGroup ${logicalId} delete to the SDK ASGProvider (Cloud Control cannot force-delete a protected ASG)`);
-			const { ASGProvider } = await import("./asg-provider-BocQJsjl.js").then((n) => n.n);
+			const { ASGProvider } = await import("./asg-provider-uaOnRUMe.js").then((n) => n.n);
 			return withIndeterminateGuard(await new ASGProvider().delete(logicalId, physicalId, resourceType, _properties, context), indeterminateGuard);
 		}
 		const isProtectedEc2Instance = context?.removeProtection === true && resourceType === "AWS::EC2::Instance";
@@ -29274,6 +30236,7 @@ const STATEFUL_TYPES = /* @__PURE__ */ new Set([
 	"AWS::Cognito::UserPool",
 	"AWS::SecretsManager::Secret",
 	"AWS::SSM::Parameter",
+	"AWS::CloudHSM::Cluster",
 	"AWS::KMS::Key",
 	"AWS::KMS::ReplicaKey",
 	"AWS::CodeCommit::Repository",
@@ -29294,6 +30257,9 @@ const STATEFUL_TYPES = /* @__PURE__ */ new Set([
 	"AWS::RedshiftServerless::Snapshot",
 	"AWS::NeptuneGraph::Graph",
 	"AWS::NeptuneGraph::GraphSnapshot",
+	"AWS::RDS::DBSnapshot",
+	"AWS::RDS::ClusterSnapshot",
+	"AWS::DynamoDB::Backup",
 	"AWS::MemoryDB::Cluster",
 	"AWS::MemoryDB::MultiRegionCluster",
 	"AWS::ElastiCache::ServerlessCache",
@@ -29319,6 +30285,7 @@ const STATEFUL_TYPES = /* @__PURE__ */ new Set([
 	"AWS::S3Outposts::Bucket",
 	"AWS::HealthImaging::Datastore",
 	"AWS::HealthLake::FHIRDatastore",
+	"AWS::FSx::Volume",
 	"AWS::SES::MailManagerArchive",
 	"AWS::WorkspacesInstances::Volume",
 	"AWS::IoTAnalytics::Channel",
@@ -29341,6 +30308,7 @@ const STATEFUL_TYPES = /* @__PURE__ */ new Set([
 	"AWS::Connect::DataTable",
 	"AWS::AppConfig::ConfigurationProfile",
 	"AWS::AIOps::InvestigationGroup",
+	"AWS::IoTSiteWise::Workspace",
 	"AWS::Rbin::Rule",
 	"AWS::SMSVOICE::PhoneNumber",
 	"AWS::SMSVOICE::SenderId"
@@ -29429,7 +30397,7 @@ function isStatefulRecreateTargetForReplace(resourceType, recordedProperties) {
 function renderStatefulReason(reason) {
 	switch (reason) {
 		case "always": return "destroy loses all data in the resource";
-		case "has-objects": return "S3 bucket is non-empty";
+		case "has-objects": return "S3 bucket is not provably empty";
 		case "has-retention": return "log group retains data (RetentionInDays > 0)";
 		case "has-log-events": return "log group is not provably empty";
 		case null: return "(not stateful)";
@@ -34099,42 +35067,64 @@ var DeployEngine = class {
 							expectedRegion: this.stackRegion
 						})), logicalId, void 0, void 0, updateProvider);
 					} catch (updateError) {
-						const msg = updateError instanceof Error ? updateError.message : String(updateError);
-						const ccUnsupported = msg.includes("UnsupportedActionException") || msg.includes("does not support UPDATE");
+						const ccUnsupported = isUpdateUnsupportedError(updateError, logicalId);
 						const replaceOptIn = updateError instanceof ResourceUpdateNotSupportedError && this.options.replace === true;
 						if (ccUnsupported || replaceOptIn) {
-							const statefulReason = isStatefulRecreateTargetForReplace(resourceType, currentProps);
-							if (statefulReason && this.options.forceStatefulRecreation !== true) {
-								const retainNote = updateReplacePolicy === "Retain" ? " Note: UpdateReplacePolicy: Retain does NOT protect this path — the replacement deletes the old resource regardless." : "";
-								throw markNonRetryable(new CdkdError((replaceOptIn ? `--replace would DELETE + CREATE the stateful resource ${logicalId} (${resourceType}) — ${renderStatefulReason(statefulReason)}. Re-run with --force-stateful-recreation to confirm the data loss, or change the resource definition to avoid the immutable-property change.` : `${logicalId} (${resourceType}) cannot be updated in place by the provisioning layer it routes through, so applying this change would DELETE + CREATE it — but it is a stateful resource: ${renderStatefulReason(statefulReason)}. Re-run with --force-stateful-recreation to confirm the data loss, or change the resource definition to avoid the update.`) + retainNote, "STATEFUL_REPLACE_BLOCKED", updateError instanceof Error ? updateError : void 0));
-							}
-							this.logger.info(`UPDATE not supported for ${logicalId} (${resourceType}), replacing (DELETE → CREATE)`);
-							const fallbackFinalSnapshotId = await this.prepareFinalSnapshotForDelete(logicalId, resourceType, currentResource, template?.Resources?.[logicalId]?.UpdateReplacePolicy ?? currentResource.updateReplacePolicy);
-							let fallbackDeleteResult = void 0;
-							try {
-								fallbackDeleteResult = await updateProvider.delete(logicalId, currentResource.physicalId, resourceType, currentProps, {
-									expectedRegion: this.stackRegion,
-									forceDataDelete: this.options.forceStatefulRecreation === true,
-									...fallbackFinalSnapshotId !== void 0 && { finalSnapshotIdentifier: fallbackFinalSnapshotId }
-								});
-							} catch (deleteError) {
-								const deleteMsg = deleteError instanceof Error ? deleteError.message : String(deleteError);
-								if (deleteMsg.includes("does not exist") || deleteMsg.includes("not found") || deleteMsg.includes("NotFound")) this.logger.debug(`Old resource ${logicalId} already gone, proceeding with CREATE`);
-								else throw deleteError;
+							const retainOldOnReplace = updateReplacePolicy === "Retain";
+							const statefulReason = retainOldOnReplace ? null : isStatefulRecreateTargetForReplace(resourceType, currentProps);
+							if (statefulReason && this.options.forceStatefulRecreation !== true) throw markNonRetryable(new CdkdError(replaceOptIn ? `--replace would DELETE + CREATE the stateful resource ${logicalId} (${resourceType}) — ${renderStatefulReason(statefulReason)}. Re-run with --force-stateful-recreation to confirm the data loss, or change the resource definition to avoid the immutable-property change.` : `${logicalId} (${resourceType}) cannot be updated in place by the provisioning layer it routes through, so applying this change would DELETE + CREATE it — but it is a stateful resource: ${renderStatefulReason(statefulReason)}. Re-run with --force-stateful-recreation to confirm the data loss, or change the resource definition to avoid the update.`, "STATEFUL_REPLACE_BLOCKED", updateError instanceof Error ? updateError : void 0));
+							this.logger.info(retainOldOnReplace ? `UPDATE not supported for ${logicalId} (${resourceType}), replacing (CREATE only — UpdateReplacePolicy: Retain keeps the old resource)` : `UPDATE not supported for ${logicalId} (${resourceType}), replacing (DELETE → CREATE)`);
+							if (!retainOldOnReplace) {
+								const fallbackFinalSnapshotId = await this.prepareFinalSnapshotForDelete(logicalId, resourceType, currentResource, template?.Resources?.[logicalId]?.UpdateReplacePolicy ?? currentResource.updateReplacePolicy);
+								let fallbackDeleteResult = void 0;
+								try {
+									fallbackDeleteResult = await updateProvider.delete(logicalId, currentResource.physicalId, resourceType, currentProps, {
+										expectedRegion: this.stackRegion,
+										forceDataDelete: this.options.forceStatefulRecreation === true,
+										...fallbackFinalSnapshotId !== void 0 && { finalSnapshotIdentifier: fallbackFinalSnapshotId }
+									});
+								} catch (deleteError) {
+									const deleteMsg = deleteError instanceof Error ? deleteError.message : String(deleteError);
+									if (deleteMsg.includes("does not exist") || deleteMsg.includes("not found") || deleteMsg.includes("NotFound")) this.logger.debug(`Old resource ${logicalId} already gone, proceeding with CREATE`);
+									else throw deleteError;
+								}
+								const fallbackSkipReason = deleteSkipReason(fallbackDeleteResult);
+								if (fallbackSkipReason !== void 0) throw new Error(deleteSkippedMessage(logicalId, currentResource.physicalId, fallbackSkipReason, "during the UPDATE-not-supported replacement"));
 							}
-							const fallbackSkipReason = deleteSkipReason(fallbackDeleteResult);
-							if (fallbackSkipReason !== void 0) throw new Error(deleteSkippedMessage(logicalId, currentResource.physicalId, fallbackSkipReason, "during the UPDATE-not-supported replacement"));
 							const replDecision = this.providerRegistry.getProviderFor({
 								resourceType,
 								properties: resolvedProps
 							});
 							const replProvider = replDecision.provider;
 							const replProps = replDecision.provisionedBy === "cc-api" ? this.preparePropertiesForCcApi(resourceType, resolvedProps, logicalId) : resolvedProps;
-							const createResult = await this.withRetry(() => withCurrentResourceSecrets(updateSecrets, () => replProvider.create(logicalId, resourceType, replProps, { maskSecrets: createSecretMasker(updateSecrets) })), logicalId, void 0, void 0, replProvider);
+							let retainedSurvivorReason;
+							let createResult;
+							try {
+								createResult = await this.withRetry(() => withCurrentResourceSecrets(updateSecrets, () => replProvider.create(logicalId, resourceType, replProps, { maskSecrets: createSecretMasker(updateSecrets) })), logicalId, void 0, void 0, replProvider);
+							} catch (createError) {
+								if (!retainOldOnReplace) throw createError;
+								if (!isNameCollisionError(createError instanceof Error ? createError.message : String(createError))) throw createError;
+								const nameOrigin = this.replacementNameOrigin(logicalId, currentResource.physicalId);
+								throw markNonRetryable(new CdkdError(`${logicalId} (${resourceType}) requires replacement because the provisioning layer cannot update it in place — but its physical name is still held by the existing resource AND UpdateReplacePolicy: Retain pins that resource in place. ${nameOrigin.descriptor}. ${nameOrigin.remedy} — with Retain, the old resource keeps the name, so a same-name replacement can never proceed. Removing UpdateReplacePolicy: Retain lets cdkd delete the old resource first, which destroys it and any data it holds.`, "NAMED_REPLACEMENT_COLLISION", createError instanceof Error ? createError : void 0));
+							}
+							if (retainOldOnReplace) {
+								if (createResult.physicalId === currentResource.physicalId) {
+									const idempotentNameOrigin = this.replacementNameOrigin(logicalId, currentResource.physicalId);
+									throw markNonRetryable(new CdkdError(`${logicalId} (${resourceType}) requires replacement, but its Create API is name-idempotent: the create returned the existing resource (${currentResource.physicalId}) instead of creating a new one, and UpdateReplacePolicy: Retain pins that resource in place, so the new properties were not applied. ${idempotentNameOrigin.descriptor}. ${idempotentNameOrigin.remedy} — with Retain, the old resource keeps the name, so a same-name replacement can never proceed.`, "NAMED_REPLACEMENT_IDEMPOTENT_CREATE"));
+								}
+								this.logger.warn(`  ⚠ ${logicalId} has UpdateReplacePolicy: Retain — the old physical resource (${currentResource.physicalId}) is RETAINED and is no longer tracked by cdkd: it keeps running and incurring cost, and \`cdkd destroy\` will not remove it. Delete it yourself once you no longer need its data.`);
+								retainedSurvivorReason = `UpdateReplacePolicy: Retain kept the old ${resourceType} (${currentResource.physicalId}), now untracked by cdkd`;
+							}
 							const replacementResult = {
 								physicalId: createResult.physicalId,
 								wasReplaced: true,
-								...createResult.attributes && { attributes: createResult.attributes }
+								...createResult.attributes && { attributes: createResult.attributes },
+								...createResult.noEchoAttributes === true && { noEchoAttributes: true },
+								...createResult.noEchoAttributeNames && { noEchoAttributeNames: createResult.noEchoAttributeNames },
+								...retainedSurvivorReason !== void 0 ? {
+									outcome: "partial",
+									reason: retainedSurvivorReason
+								} : { outcome: "updated" }
 							};
 							if (createResult.effectiveProperties) replacementResult.effectiveProperties = createResult.effectiveProperties;
 							result = replacementResult;
@@ -34280,8 +35270,12 @@ var DeployEngine = class {
 	* connect the message to their code at all.
 	*
 	* `descriptor` names WHERE the name came from; `remedy` is the accurate
-	* first option. Both callers append the shared `--replace` alternative,
-	* which is identical in either case.
+	* first option. What each caller appends after it differs: the two
+	* property-driven create-first sites append the shared `--replace`
+	* alternative, while the update-failure fallback's two `Retain` refusals
+	* (issue #2518) append the Retain clause instead — under `Retain` no flag
+	* frees the name, so offering `--replace` there would send the user to a
+	* flag that changes nothing.
 	*
 	* Classification is best-effort by construction (see
 	* {@link looksLikeCdkdGeneratedName}) and falls back to the pre-#1636
@@ -34607,5 +35601,5 @@ var DeployEngine = class {
 };
 
 //#endregion
-export { beginCommandInterruptScope as $, resolveAutoAssetStorage as $n, isTransientServerError as $r, maskSecretsInError as $t, formatResourceLine as A, ensureAssetStorage as An, DependencyError as Ar, requireConfigString as At, isExportAliasCollision as B, dockerSpawnEnvWithSensitive as Bn, ResourceTimeoutError as Br, INTRINSIC_KEYS as Bt, unsupportedFinalSnapshotError as C, loadPublishableAssetManifest as Cn, getAwsClients as Cr, coerceCfnBoolean as Ct, isStatefulRecreateTargetForReplace as D, AssetModeResolver as Dn, CdkdError as Dr, replayWarn as Dt, MULTI_REGION_RECREATE_BLOCKED_TYPES as E, stripControlChars as En, AssetError as Er, readConfigString as Et, red as F, validateAssetBucketName as Fn, LocalStartServiceError as Fr, s3BucketDualStackDomainName as Ft, collectInlinePolicyNamesManagedBySiblings as G, runDockerStreaming as Gn, SynthesisError as Gr, STATE_SOURCED_CROSS_GENERATION_RULES as Gt, stateKeySecretExposure as H, getDockerCmd as Hn, StackHasActiveImportsError as Hr, withRetry as Ht, yellow as I, validateContainerRepoName as In, LockError as Ir, s3BucketRegionalDomainName as It, findActionableSilentDrops as J, Synthesizer as Jn, normalizeAwsError as Jr, carriesSecretMask as Jt, clearOnUpdateRemoval as K, AssetManifestLoader as Kn, formatError as Kr, STATE_SOURCED_READBACK_RULES as Kt, collectDeclaredOutputNames as L, buildDenyExternalAccessPolicy as Ln, NestedStackChildDirectDestroyError as Lr, s3BucketWebsiteUrl as Lt, cyan as M, isCrossRegionRedirect as Mn, DynamicReferenceRegionAmbiguousError as Mr, producerRegionsFromState as Mt, gray as N, parseBootstrapMarker as Nn, IntrinsicResolutionRefusalError as Nr, s3BucketArn as Nt, isStatefulRecreateTargetSync as O, BOOTSTRAP_MARKER_PREFIX as On, ConfigError as Or, requireConfigArray as Ot, green as P, readBootstrapMarkerBody as Pn, LocalInvokeBuildError as Pr, s3BucketDomainName as Pt, maskerOrIdentity as Q, resolveApp as Qn, isThrottlingError as Qr, isSingleDynamicReferenceToken as Qt, collectPublishedOutputNames as R, describeAwsFailure as Rn, PartialFailureError as Rr, applyRoleArnIfSet as Rt, refusesFinalSnapshot as S, createAssetRedirectResolver as Sn, AwsClients as Sr, assertRegionMatch as St, extractDeploymentEventError as T, escapeRegExp$1 as Tn, setAwsClients as Tr, configStringRefusal as Tt, getCurrentResourceSecrets as U, partitionSensitiveEnv as Un, StackTerminationProtectionError as Ur, DagBuilder as Ut, secretBearingStateKeyWarning as V, formatDockerLoginError as Vn, ResourceUpdateNotSupportedError as Vr, describeTypeWithThrottleRetry as Vt, IAMRoleProvider as W, runDockerForeground as Wn, StateError as Wr, TemplateParser as Wt, createMaskedRetryLogger as X, getDefaultStateBucketName as Xn, isMarkedNonRetryable as Xr, dynamicReferenceTokens as Xt, findSilentDropProperties as Y, synthesisStatusMessage as Yn, withErrorHandling as Yr, createSecretMasker as Yt, maskDeep as Z, getLegacyStateBucketName as Zn, isRetryableTransientError as Zr, errorCauseChain as Zt, PRE_DELETE_SNAPSHOT_TYPES as _, shouldRetainResource as _n, derivePartitionAndUrlSuffix as _r, parameterTypeMayLoseSecretIdentity as _t, DeploymentEventsStore as a, LockManager as an, stateBucketExistenceConfirmed as ar, slowCcOperationTimeoutMs as at, createPreDeleteFinalSnapshot as b, WorkGraph as bn, clearBucketRegionCache as br, normalizeAwsTagsToCfn as bt, replayFailedOperations as c, UNRENDERABLE as cn, CFN_TEMPLATE_URL_LIMIT as cr, deleteSkipReason as ct, updatePartialReason as d, forceQuitRecoveryClause as dn, uploadCfnTemplate as dr, IntrinsicFunctionResolver as dt, markNonRetryable as ei, maskSecretsInText as en, resolveCaptureObservedState as er, endCommandInterruptScope as et, withResourceDeadline as f, CUSTOM_RESOURCE_RESPONSE_PREFIX as fn, CUSTOM_RESOURCE_RESPONSE_OBJECT_DESCRIPTION as fr, carriesDynamicReference as ft, ATOMIC_FINAL_SNAPSHOT_TYPES as g, importableOutputs as gn, canonicalizeRegion as gr, isUnboundTemplateParameter as gt, computeImplicitDeleteEdges as h, importableOutputKeys as hn, PARTITION_TABLE as hr, getAccountInfo as ht, DeploymentEventsReader as i, scrubResourceRecord as in, resolveUseCdkBootstrapAssets as ir, CloudControlProvider as it, bold as j, getBootstrapMarkerKey as jn, DeployCancelledError as jr, classifyReplaySecretRegion as jt, renderStatefulReason as k, assertAssetBucketRegion as kn, CrossAccountSecretRefusalError as kr, requireConfigObject as kt, replayRollback as l, buildForceUnlockCommand as ln, MIGRATE_TMP_PREFIX as lr, disableInstanceApiTermination as lt, IMPLICIT_DELETE_DEPENDENCIES as m, exportNamesCarriedFrom as mn, expectedOwnerParam as mr, coerceParameterTypedValue as mt, DEFAULT_RESOURCE_WARN_AFTER_MS as n, retryClassificationText as ni, recoverMaskedOutput as nn, resolveStateBucketWithDefault as nr, isInterruptedWaitError as nt, planFailedOps as o, S3StateBackend as on, warnDeprecatedNoPrefixCliFlag as or, UNSPECIFIED_SKIP_REASON as ot, maskingRetryLogger as p, DEFAULT_STATE_PREFIX as pn, displaySafe as pr, cfnRefValueFromPhysicalId as pt, ProviderRegistry as q, getDockerImageBySourceHash as qn, isCdkdError as qr, TEMPLATE_SOURCED_RULES as qt, DeployEngine as r, __exportAll as ri, redactSecretsForState as rn, resolveStateBucketWithDefaultAndSource as rr, startInterruptWatch as rt, planRollback as s, rebuildClientForBucketRegion as sn, CFN_TEMPLATE_BODY_LIMIT as sr, deleteIndeterminateGuards as st, DEFAULT_RESOURCE_TIMEOUT_MS as t, markRedactedCause as ti, recordMaskOnlyValue as tn, resolveSkipPrefix as tr, interruptWatchListenerCount as tt, updatePartialMessage as u, buildLockContentionMessage as un, findLargeInlineResources as ur, isTerminationProtectionPropagationError as ut, buildFinalSnapshotIdentifier as v, AssetPublisher as vn, AssemblyReader as vr, refStateLookupFromResource as vt, makeCanonicalizePropertiesFn as w, rewriteTemplateAssetReferences as wn, resetAwsClients as wr, configBooleanRefusal as wt, isFinalSnapshotError as x, buildAssetRedirectMap as xn, resolveBucketRegion as xr, resolveExplicitPhysicalId as xt, ccRoutedFinalSnapshotError as y, stringifyValue as yn, processStackMessages as yr, WAFv2WebACLProvider as yt, exportAliasCollisionScrubWarning as z, buildDockerImage as zn, ProvisioningError as zr, DiffCalculator as zt };
-//# sourceMappingURL=deploy-engine-D0RCEQ6D.js.map
+export { beginCommandInterruptScope as $, synthesisStatusMessage as $n, withErrorHandling as $r, maskSecretsInError as $t, formatResourceLine as A, ensureAssetStorage as An, AssetError as Ar, requireConfigString as At, isExportAliasCollision as B, describeDockerCapturedOutput as Bn, LockError as Br, INTRINSIC_KEYS as Bt, unsupportedFinalSnapshotError as C, loadPublishableAssetManifest as Cn, processStackMessages as Cr, coerceCfnBoolean as Ct, isStatefulRecreateTargetForReplace as D, AssetModeResolver as Dn, getAwsClients as Dr, replayWarn as Dt, MULTI_REGION_RECREATE_BLOCKED_TYPES as E, stripControlChars as En, AwsClients as Er, readConfigString as Et, red as F, validateAssetBucketName as Fn, DeployCancelledError as Fr, s3BucketDualStackDomainName as Ft, collectInlinePolicyNamesManagedBySiblings as G, getDockerCmd as Gn, ResourceUpdateNotSupportedError as Gr, STATE_SOURCED_CROSS_GENERATION_RULES as Gt, stateKeySecretExposure as H, describeDockerFailure as Hn, PartialFailureError as Hr, withRetry as Ht, yellow as I, validateContainerRepoName as In, DynamicReferenceRegionAmbiguousError as Ir, s3BucketRegionalDomainName as It, findActionableSilentDrops as J, runDockerForeground as Jn, StateError as Jr, carriesSecretMask as Jt, clearOnUpdateRemoval as K, partitionSensitiveEnv as Kn, StackHasActiveImportsError as Kr, STATE_SOURCED_READBACK_RULES as Kt, collectDeclaredOutputNames as L, buildDenyExternalAccessPolicy as Ln, IntrinsicResolutionRefusalError as Lr, s3BucketWebsiteUrl as Lt, cyan as M, isCrossRegionRedirect as Mn, ConfigError as Mr, producerRegionsFromState as Mt, gray as N, parseBootstrapMarker as Nn, CrossAccountSecretRefusalError as Nr, s3BucketArn as Nt, isStatefulRecreateTargetSync as O, BOOTSTRAP_MARKER_PREFIX as On, resetAwsClients as Or, requireConfigArray as Ot, green as P, readBootstrapMarkerBody as Pn, DependencyError as Pr, s3BucketDomainName as Pt, maskerOrIdentity as Q, Synthesizer as Qn, normalizeAwsError as Qr, isSingleDynamicReferenceToken as Qt, collectPublishedOutputNames as R, describeAwsFailure as Rn, LocalInvokeBuildError as Rr, applyRoleArnIfSet as Rt, refusesFinalSnapshot as S, createAssetRedirectResolver as Sn, AssemblyReader as Sr, assertRegionMatch as St, extractDeploymentEventError as T, escapeRegExp$1 as Tn, resolveBucketRegion as Tr, configStringRefusal as Tt, getCurrentResourceSecrets as U, dockerSpawnEnvWithSensitive as Un, ProvisioningError as Ur, DagBuilder as Ut, secretBearingStateKeyWarning as V, describeDockerExecFailure as Vn, NestedStackChildDirectDestroyError as Vr, describeTypeWithThrottleRetry as Vt, IAMRoleProvider as W, formatDockerLoginError as Wn, ResourceTimeoutError as Wr, TemplateParser as Wt, createMaskedRetryLogger as X, AssetManifestLoader as Xn, formatError as Xr, dynamicReferenceTokens as Xt, findSilentDropProperties as Y, runDockerStreaming as Yn, SynthesisError as Yr, createSecretMasker as Yt, maskDeep as Z, getDockerImageBySourceHash as Zn, isCdkdError as Zr, errorCauseChain as Zt, PRE_DELETE_SNAPSHOT_TYPES as _, shouldRetainResource as _n, displaySafe as _r, parameterTypeMayLoseSecretIdentity as _t, DeploymentEventsStore as a, markRedactedCause as ai, LockManager as an, resolveSkipPrefix as ar, slowCcOperationTimeoutMs as at, createPreDeleteFinalSnapshot as b, WorkGraph as bn, canonicalizeRegion as br, normalizeAwsTagsToCfn as bt, replayFailedOperations as c, UNRENDERABLE as cn, resolveUseCdkBootstrapAssets as cr, deleteSkipReason as ct, updatePartialReason as d, forceQuitRecoveryClause as dn, CFN_TEMPLATE_BODY_LIMIT as dr, IntrinsicFunctionResolver as dt, isMarkedNonRetryable as ei, maskSecretsInText as en, getDefaultStateBucketName as er, endCommandInterruptScope as et, withResourceDeadline as f, CUSTOM_RESOURCE_RESPONSE_PREFIX as fn, CFN_TEMPLATE_URL_LIMIT as fr, carriesDynamicReference as ft, ATOMIC_FINAL_SNAPSHOT_TYPES as g, importableOutputs as gn, CUSTOM_RESOURCE_RESPONSE_OBJECT_DESCRIPTION as gr, isUnboundTemplateParameter as gt, computeImplicitDeleteEdges as h, importableOutputKeys as hn, uploadCfnTemplate as hr, getAccountInfo as ht, DeploymentEventsReader as i, markNonRetryable as ii, scrubResourceRecord as in, resolveCaptureObservedState as ir, CloudControlProvider as it, bold as j, getBootstrapMarkerKey as jn, CdkdError as jr, classifyReplaySecretRegion as jt, renderStatefulReason as k, assertAssetBucketRegion as kn, setAwsClients as kr, requireConfigObject as kt, replayRollback as l, buildForceUnlockCommand as ln, stateBucketExistenceConfirmed as lr, disableInstanceApiTermination as lt, IMPLICIT_DELETE_DEPENDENCIES as m, exportNamesCarriedFrom as mn, findLargeInlineResources as mr, coerceParameterTypedValue as mt, DEFAULT_RESOURCE_WARN_AFTER_MS as n, isThrottlingError as ni, recoverMaskedOutput as nn, resolveApp as nr, isInterruptedWaitError as nt, planFailedOps as o, retryClassificationText as oi, S3StateBackend as on, resolveStateBucketWithDefault as or, UNSPECIFIED_SKIP_REASON as ot, maskingRetryLogger as p, DEFAULT_STATE_PREFIX as pn, MIGRATE_TMP_PREFIX as pr, cfnRefValueFromPhysicalId as pt, ProviderRegistry as q, redactDockerArgvValues as qn, StackTerminationProtectionError as qr, TEMPLATE_SOURCED_RULES as qt, DeployEngine as r, isTransientServerError as ri, redactSecretsForState as rn, resolveAutoAssetStorage as rr, startInterruptWatch as rt, planRollback as s, __exportAll as si, rebuildClientForBucketRegion as sn, resolveStateBucketWithDefaultAndSource as sr, deleteIndeterminateGuards as st, DEFAULT_RESOURCE_TIMEOUT_MS as t, isRetryableTransientError as ti, recordMaskOnlyValue as tn, getLegacyStateBucketName as tr, interruptWatchListenerCount as tt, updatePartialMessage as u, buildLockContentionMessage as un, warnDeprecatedNoPrefixCliFlag as ur, isTerminationProtectionPropagationError as ut, buildFinalSnapshotIdentifier as v, AssetPublisher as vn, expectedOwnerParam as vr, refStateLookupFromResource as vt, makeCanonicalizePropertiesFn as w, rewriteTemplateAssetReferences as wn, clearBucketRegionCache as wr, configBooleanRefusal as wt, isFinalSnapshotError as x, buildAssetRedirectMap as xn, derivePartitionAndUrlSuffix as xr, resolveExplicitPhysicalId as xt, ccRoutedFinalSnapshotError as y, stringifyValue as yn, PARTITION_TABLE as yr, WAFv2WebACLProvider as yt, exportAliasCollisionScrubWarning as z, buildDockerImage as zn, LocalStartServiceError as zr, DiffCalculator as zt };
+//# sourceMappingURL=deploy-engine--rkIGhow.js.map