cdk-local 0.71.2 → 0.73.0

package/dist/{local-list-BS463YYd.js → local-list-Ch0RglJl.js}

@@ -6,7 +6,7 @@ import path, { dirname, isAbsolute, join, normalize, resolve, sep } from "node:p
 import { Command, Option } from "commander";
 import { AssumeRoleCommand, GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
 import { MultiSelectPrompt } from "@clack/core";
-import { S_BAR, S_BAR_END, S_BAR_START, S_CHECKBOX_ACTIVE, S_CHECKBOX_INACTIVE, S_CHECKBOX_SELECTED, confirm, isCancel, select } from "@clack/prompts";
+import { S_BAR, S_BAR_END, S_BAR_START, S_CHECKBOX_ACTIVE, S_CHECKBOX_INACTIVE, S_CHECKBOX_SELECTED, confirm, isCancel, multiselect, select, text } from "@clack/prompts";
 import { AssetManifestArtifact } from "@aws-cdk/cloud-assembly-api";
 import { BaseCredentials, CdkAppMultiContext, NonInteractiveIoHost, Toolkit } from "@aws-cdk/toolkit-lib";
 import { CloudFormationClient, DescribeStacksCommand, ListExportsCommand, ListStackResourcesCommand } from "@aws-sdk/client-cloudformation";
@@ -20055,6 +20055,12 @@ function sleep$1(ms) {
 async function prepareImages(task, out, options) {
 	const logger = getLogger().child("ecs-runner");
 	for (const container of task.containers) {
+		const overrideTag = options.imageOverrideByContainer?.get(container.name);
+		if (overrideTag !== void 0) {
+			out.set(container.name, overrideTag);
+			logger.debug(`Container '${container.name}' image=${overrideTag} (--image-override)`);
+			continue;
+		}
 		const image = await prepareOneImage(task, container, options);
 		out.set(container.name, image);
 		logger.debug(`Container '${container.name}' image=${image}`);
@@ -24242,6 +24248,516 @@ function describePinnedImageUri(service) {
 	if (image.kind === "cdk-asset") return void 0;
 	return image.uri;
 }
+/**
+* Issue #242 / N1 — dedupe pinned-target detection across the two
+* sites that need it during a `cdkl start-service` / `cdkl start-alb`
+* boot:
+*
+*   1. The `--image-override` engine's pre-boot resolution
+*      ({@link resolveImageOverrides}) — needs the pinned set + per-
+*      target deployed-registry URI labels so the picker + boot-prompt
+*      hint can name the image the user is overriding.
+*   2. The post-boot WARN loop in `runEcsServiceEmulator` — surfaces a
+*      per-target WARN naming the deployed-registry URI for every
+*      pinned target the override engine did NOT cover.
+*
+* Before this helper both sites re-walked `isLocalCdkAssetImage` +
+* `describePinnedImageUri` independently. The semantic computation is
+* identical — given a `ResolvedEcsService`, decide pinned vs local-
+* asset and (for pinned targets) surface the URI label. Hoisting the
+* walk here keeps the two call sites in lock-step and gives both a
+* single test surface.
+*
+* Returns one entry per pinned target in the input's iteration order.
+* Targets whose representative image is a local CDK asset are
+* filtered out — the caller never sees them.
+*/
+function listPinnedTargets(resolvedServices) {
+	const out = [];
+	for (const { target, service } of resolvedServices) {
+		if (isLocalCdkAssetImage(service)) continue;
+		const label = describePinnedImageUri(service);
+		out.push({
+			target,
+			...label !== void 0 && { label }
+		});
+	}
+	return out;
+}
+
+//#endregion
+//#region src/local/image-override-engine.ts
+/**
+* Errors surfaced by the engine. Used so the emulator can render a
+* consistent error class to the user (the global error handler maps
+* `CdkLocalError` subclasses to a clean stack-trace-free message).
+*/
+var ImageOverrideError = class ImageOverrideError extends CdkLocalError {
+	constructor(message, cause) {
+		super(message, "IMAGE_OVERRIDE_ERROR", cause);
+		this.name = "ImageOverrideError";
+		Object.setPrototypeOf(this, ImageOverrideError.prototype);
+	}
+};
+/**
+* Parse the raw `--image-override` / `--image-build-arg` /
+* `--image-build-secret` / `--image-target` flag arrays Commander
+* surfaces into the structured {@link RawImageOverrideFlags} shape.
+* Pure (no docker / filesystem calls); throws
+* {@link ImageOverrideError} on a malformed token so the emulator can
+* surface a clean error before any container is touched.
+*
+* - `--image-override <svc>=<dockerfile>` -> `explicit.set(svc, dockerfile)`
+* - `--image-override <dockerfile>` (no `=`) -> `pickerPaths.push(...)`
+* - `--image-build-arg KEY=VAL` -> `globals.buildArgs.set('KEY', 'VAL')`
+* - `--image-build-arg <svc>:KEY=VAL` -> `perService(svc).buildArgs.set('KEY', 'VAL')` (issue #240)
+* - `--image-build-secret id=src` -> `globals.buildSecrets.set('id', 'src')`
+* - `--image-build-secret <svc>:id=src` -> `perService(svc).buildSecrets.set('id', 'src')` (issue #240)
+* - `--image-target <stage>` -> `globals.targetStage = '<stage>'`
+* - `--image-target <svc>=<stage>` -> `perService(svc).targetStage = '<stage>'` (issue #240)
+*
+* Per-service syntax convention (issue #240):
+* - Flags whose payload already contains `=` (build-arg, build-secret)
+*   use `:` to separate the service prefix from the `<key>=<value>`
+*   payload — `<svc>:KEY=VAL`. The FIRST `:` before the FIRST `=` (if
+*   any) is treated as the prefix delimiter.
+* - Flags whose payload is a single token (target) use `=` to separate
+*   the service prefix from the stage — `<svc>=stage`. Matches the
+*   `--image-override <svc>=<dockerfile>` convention.
+* - Per-service entries override the global entry per-key when both
+*   forms set the same key on the same target. Globals still apply to
+*   every OTHER overridden target.
+*
+* Collision detection: a service target named more than once in
+* `--image-override <svc>=...` is an error (last-write-wins would
+* silently drop the earlier mapping; explicit error is clearer).
+* Repeated per-service `--image-build-arg <svc>:KEY=...` entries on
+* the same `<svc>:KEY` pair are last-write-wins (the same shape the
+* global form already uses for repeated `KEY=...` entries — both
+* forms behave identically inside their respective bucket).
+*
+* Empty-value semantics:
+* - `--image-build-arg KEY=` (empty value) is ACCEPTED. The empty
+*   string is forwarded verbatim to `docker build --build-arg KEY=`,
+*   which docker itself accepts (the canonical way to unset a
+*   Dockerfile `ARG`'s default). `KEY=` (empty key) is rejected.
+*   Per-service form `<svc>:KEY=` is similarly accepted (same empty-
+*   value semantics applied to the per-service entry).
+* - `--image-target ""` (empty value) is REJECTED — an empty
+*   `--target` is meaningless to `docker build` (`--target` is a
+*   single stage name, not a list). Per-service `<svc>=` is similarly
+*   rejected (empty stage).
+* - `--image-override <svc>=` and `--image-override =<dockerfile>`
+*   are REJECTED — both halves must be non-empty.
+* - `--image-build-secret id=` and `--image-build-secret =src` are
+*   REJECTED — both halves must be non-empty. Per-service form
+*   `<svc>:id=` and `<svc>:=src` are similarly rejected.
+*/
+function parseImageOverrideFlags(input) {
+	const explicit = /* @__PURE__ */ new Map();
+	const pickerPaths = [];
+	const perService = /* @__PURE__ */ new Map();
+	const getPerSvc = (svc) => {
+		let entry = perService.get(svc);
+		if (!entry) {
+			entry = {
+				buildArgs: /* @__PURE__ */ new Map(),
+				buildSecrets: /* @__PURE__ */ new Map()
+			};
+			perService.set(svc, entry);
+		}
+		return entry;
+	};
+	const splitPerServicePrefix = (raw) => {
+		const colon = raw.indexOf(":");
+		const eq = raw.indexOf("=");
+		if (colon < 0) return null;
+		if (eq >= 0 && eq < colon) return null;
+		const svc = raw.slice(0, colon).trim();
+		if (!svc) return null;
+		return {
+			svc,
+			rest: raw.slice(colon + 1)
+		};
+	};
+	for (const raw of input.imageOverride ?? []) {
+		const eq = raw.indexOf("=");
+		if (eq < 0) {
+			if (!raw) throw new ImageOverrideError("Invalid --image-override value: empty string. Pass <service>=<dockerfile> or just <dockerfile>.");
+			pickerPaths.push(raw);
+			continue;
+		}
+		const svc = raw.slice(0, eq).trim();
+		const dockerfile = raw.slice(eq + 1).trim();
+		if (!svc) throw new ImageOverrideError(`Invalid --image-override value "${raw}": left side (service target) is empty.`);
+		if (!dockerfile) throw new ImageOverrideError(`Invalid --image-override value "${raw}": right side (Dockerfile path) is empty.`);
+		if (explicit.has(svc)) throw new ImageOverrideError(`Duplicate --image-override for service '${svc}': already mapped to '${explicit.get(svc)}'. Pass each service target at most once in explicit form.`);
+		explicit.set(svc, dockerfile);
+	}
+	const buildArgs = /* @__PURE__ */ new Map();
+	for (const raw of input.imageBuildArg ?? []) {
+		const prefix = splitPerServicePrefix(raw);
+		if (prefix) {
+			const eq = prefix.rest.indexOf("=");
+			if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": expected <service>:KEY=VAL.`);
+			const key = prefix.rest.slice(0, eq).trim();
+			const value = prefix.rest.slice(eq + 1);
+			if (!key) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": empty key (after service prefix).`);
+			getPerSvc(prefix.svc).buildArgs.set(key, value);
+			continue;
+		}
+		const eq = raw.indexOf("=");
+		if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": expected KEY=VAL.`);
+		const key = raw.slice(0, eq).trim();
+		const value = raw.slice(eq + 1);
+		if (!key) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": empty key.`);
+		buildArgs.set(key, value);
+	}
+	const buildSecrets = /* @__PURE__ */ new Map();
+	for (const raw of input.imageBuildSecret ?? []) {
+		const prefix = splitPerServicePrefix(raw);
+		if (prefix) {
+			const eq = prefix.rest.indexOf("=");
+			if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": expected <service>:id=src (e.g. AppService:npmrc=./.npmrc).`);
+			const id = prefix.rest.slice(0, eq).trim();
+			const src = prefix.rest.slice(eq + 1).trim();
+			if (!id || !src) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": id and src must both be non-empty (after service prefix).`);
+			const absSrcPS = isAbsolute(src) ? src : resolve(process.cwd(), src);
+			getPerSvc(prefix.svc).buildSecrets.set(id, absSrcPS);
+			continue;
+		}
+		const eq = raw.indexOf("=");
+		if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": expected id=src (e.g. npmrc=./.npmrc).`);
+		const id = raw.slice(0, eq).trim();
+		const src = raw.slice(eq + 1).trim();
+		if (!id || !src) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": id and src must both be non-empty.`);
+		const absSrc = isAbsolute(src) ? src : resolve(process.cwd(), src);
+		buildSecrets.set(id, absSrc);
+	}
+	const globals = {
+		buildArgs,
+		buildSecrets
+	};
+	const imageTargetList = input.imageTarget === void 0 ? [] : Array.isArray(input.imageTarget) ? input.imageTarget : [input.imageTarget];
+	for (const raw of imageTargetList) {
+		if (raw === void 0 || raw === null) continue;
+		if (!raw) throw new ImageOverrideError("Invalid --image-target value: empty string.");
+		const eq = raw.indexOf("=");
+		if (eq < 0) {
+			globals.targetStage = raw.trim();
+			continue;
+		}
+		const svc = raw.slice(0, eq).trim();
+		const stage = raw.slice(eq + 1).trim();
+		if (!svc) throw new ImageOverrideError(`Invalid --image-target value "${raw}": left side (service target) is empty.`);
+		if (!stage) throw new ImageOverrideError(`Invalid --image-target value "${raw}": right side (stage) is empty.`);
+		getPerSvc(svc).targetStage = stage;
+	}
+	return {
+		explicit,
+		pickerPaths,
+		globals,
+		perService
+	};
+}
+/**
+* Resolve `--image-override` flag inputs (raw) + a list of pinned
+* service targets into the final {@link ImageOverrideMap}. Walks four
+* stages:
+*
+*   1. Apply every explicit `<svc>=<dockerfile>` mapping. A service in
+*      `explicit` but NOT in `pinnedTargets` is a no-op warning
+*      (logged at warn) — the user named a non-pinned target, which
+*      probably indicates a typo or a CDK app change; we don't fail.
+*   2. For each picker-form Dockerfile path, fire a multi-select against
+*      the still-uncovered pinned targets. A single picker-form path
+*      may bind to multiple targets (one Dockerfile shared across N
+*      services); already-bound targets are excluded from later pickers.
+*      Skipped when not in a TTY OR `noInteractive` is true — those
+*      contexts emit a warning and skip the picker path (treated as
+*      "no override for any target").
+*   3. Optional boot prompt: when `interactiveBootPrompt` is true AND
+*      we're in a TTY, walk each remaining uncovered pinned target
+*      and ask "Override with a local build? [path / N]" via clack's
+*      `text` prompt. A non-empty answer is treated as an additional
+*      explicit mapping; `N` / empty / Esc skips the target.
+*
+* Returns the resolved override map. Throws
+* {@link ImageOverrideError} on a malformed picker response or a
+* Dockerfile path that doesn't exist (caught up-front before any
+* docker build runs).
+*/
+async function resolveImageOverrides(args) {
+	const logger = getLogger();
+	const { rawFlags, pinnedTargets, noInteractive } = args;
+	const cwd = args.cwd ?? process.cwd();
+	const pinnedSet = new Set(pinnedTargets);
+	const labels = args.pinnedLabels ?? /* @__PURE__ */ new Map();
+	const out = /* @__PURE__ */ new Map();
+	for (const [svc, dockerfileRaw] of rawFlags.explicit.entries()) {
+		if (!pinnedSet.has(svc)) {
+			logger.warn(`--image-override: service '${svc}' is not in the pinned-target set (no deployed-registry pin detected for it). Mapping ignored.`);
+			continue;
+		}
+		out.set(svc, makeEntryFromPath(dockerfileRaw, svc, rawFlags, cwd));
+	}
+	if (rawFlags.pickerPaths.length > 0) if (!(isInteractive() && noInteractive !== true)) logger.warn("--image-override <dockerfile> (picker form) requires an interactive TTY and --no-interactive-overrides not to be set. Skipping picker-form mapping(s).");
+	else for (const dockerfileRaw of rawFlags.pickerPaths) {
+		const uncovered = pinnedTargets.filter((t) => !out.has(t));
+		if (uncovered.length === 0) {
+			logger.warn(`--image-override ${dockerfileRaw}: no uncovered pinned targets left to bind to. Skipped.`);
+			continue;
+		}
+		const options = uncovered.map((t) => ({
+			value: t,
+			label: t,
+			...labels.get(t) ? { hint: labels.get(t) } : {}
+		}));
+		const picked = await multiselect({
+			message: `Pick the pinned target(s) to bind to '${dockerfileRaw}' (space to toggle, enter to confirm; empty cancels):`,
+			options,
+			required: false
+		});
+		if (isCancel(picked)) throw new ImageOverrideError("Image-override picker cancelled. Re-run without picker-form or with --no-interactive-overrides.");
+		const chosen = picked ?? [];
+		if (chosen.length === 0) {
+			logger.warn(`--image-override ${dockerfileRaw}: empty selection. Skipped.`);
+			continue;
+		}
+		for (const t of chosen) out.set(t, makeEntryFromPath(dockerfileRaw, t, rawFlags, cwd));
+	}
+	if (args.interactiveBootPrompt === true && isInteractive() && noInteractive !== true) for (const target of pinnedTargets) {
+		if (out.has(target)) continue;
+		const label = labels.get(target);
+		const answer = await text({
+			message: `Detected pinned image on '${target}'` + (label ? ` (${label})` : "") + ". Override with a local build? [path / N]:",
+			placeholder: ""
+		});
+		if (isCancel(answer)) throw new ImageOverrideError("Image-override boot prompt cancelled. Re-run with --no-interactive-overrides to suppress, or pass --image-override explicitly.");
+		const value = (answer ?? "").trim();
+		if (!value) continue;
+		const lower = value.toLowerCase();
+		if (lower === "n" || lower === "no") continue;
+		out.set(target, makeEntryFromPath(value, target, rawFlags, cwd));
+	}
+	return out;
+}
+/**
+* Issue #240 — produce the EFFECTIVE per-target build inputs by layering
+* a per-service overlay on top of the global baseline. Per-service
+* entries override the global per-key (and per-service `targetStage`
+* overrides the global `targetStage`).
+*
+* The returned Maps are fresh copies — the caller may mutate the
+* resulting {@link ImageOverrideEntry}'s Maps without bleeding back
+* into the shared global Maps inside {@link RawImageOverrideFlags}.
+* Per-service entries are merged AFTER globals so a key shared between
+* the two ends up with the per-service value (Map's `set` overwrites
+* on duplicate key).
+*/
+function mergeForService(serviceTarget, globals, perService) {
+	const buildArgs = new Map(globals.buildArgs);
+	const buildSecrets = new Map(globals.buildSecrets);
+	let targetStage = globals.targetStage;
+	const overlay = perService.get(serviceTarget);
+	if (overlay) {
+		for (const [k, v] of overlay.buildArgs.entries()) buildArgs.set(k, v);
+		for (const [k, v] of overlay.buildSecrets.entries()) buildSecrets.set(k, v);
+		if (overlay.targetStage !== void 0) targetStage = overlay.targetStage;
+	}
+	return {
+		buildArgs,
+		buildSecrets,
+		...targetStage !== void 0 && { targetStage }
+	};
+}
+/**
+* Promote a per-target Dockerfile path + raw flags into a full
+* {@link ImageOverrideEntry}. Resolves the path against `cwd`, asserts
+* the Dockerfile exists and is a regular file (so the user sees
+* "file not found" up-front rather than mid-`docker build`), and
+* derives the build context as the Dockerfile's parent directory
+* (the v1 simplification — custom contexts are tracked separately).
+*
+* Issue #240 — `serviceTarget` is now part of the entry-construction
+* input so the global + per-service merge runs per target.
+*/
+function makeEntryFromPath(raw, serviceTarget, rawFlags, cwd) {
+	const abs = isAbsolute(raw) ? raw : resolve(cwd, raw);
+	if (!existsSync(abs)) throw new ImageOverrideError(`--image-override: Dockerfile '${raw}' does not exist (resolved to '${abs}').`);
+	if (!statSync(abs).isFile()) throw new ImageOverrideError(`--image-override: '${raw}' is not a regular file (resolved to '${abs}').`);
+	const merged = mergeForService(serviceTarget, rawFlags.globals, rawFlags.perService);
+	return {
+		dockerfile: abs,
+		contextDir: dirname(abs),
+		buildArgs: merged.buildArgs,
+		buildSecrets: merged.buildSecrets,
+		...merged.targetStage !== void 0 && { targetStage: merged.targetStage }
+	};
+}
+/**
+* Deterministic local-only image tag for one override entry. Fingerprints
+* the Dockerfile path + its CONTENTS (sha256 of the bytes) + service
+* target + build args / secrets / stage. Including the Dockerfile bytes
+* means an edit to the Dockerfile flips the tag — the rebuild rolling
+* primitive then boots a new container under the bumped tag instead of
+* reusing the old build's cached layers under a stale tag. Two
+* back-to-back runs against an unchanged Dockerfile + flags still hit
+* the same tag so docker's layer cache works.
+*
+* Tag shape: `<resourceNamePrefix>-override-<svcSlug>-<hash>:local`.
+* `:local` is intentionally NOT `:latest` so a `docker pull` on it fails
+* fast (these images are local-build-only by design).
+*
+* Throws on a missing Dockerfile — the caller has already asserted
+* existence in {@link makeEntryFromPath}, so a throw here is a
+* programming error (or the Dockerfile vanished between resolve and
+* build, which is a race the user wants to know about).
+*/
+function buildImageOverrideTag(serviceTarget, entry) {
+	const hash = createHash("sha256");
+	hash.update("dockerfile=");
+	hash.update(entry.dockerfile);
+	hash.update("\0dockerfile-bytes-sha256=");
+	const dockerfileBytesDigest = createHash("sha256").update(readFileSync(entry.dockerfile)).digest("hex");
+	hash.update(dockerfileBytesDigest);
+	hash.update("\0target=");
+	hash.update(serviceTarget);
+	hash.update("\0stage=");
+	hash.update(entry.targetStage ?? "");
+	hash.update("\0args={");
+	for (const [k, v] of entry.buildArgs.entries()) {
+		hash.update(k);
+		hash.update("=");
+		hash.update(v);
+		hash.update(";");
+	}
+	hash.update("}\0secrets={");
+	for (const [k, v] of entry.buildSecrets.entries()) {
+		hash.update(k);
+		hash.update("=");
+		hash.update(v);
+		hash.update(";");
+	}
+	hash.update("}");
+	const svcSlug = serviceTarget.replace(/[^A-Za-z0-9]+/g, "-").slice(0, 24).toLowerCase();
+	return `${getEmbedConfig().resourceNamePrefix}-override-${svcSlug}-${hash.digest("hex").slice(0, 16)}:local`;
+}
+/**
+* Build every overridden image via `docker build`. Returns a per-target
+* `serviceTarget -> localTag` map the emulator threads into each
+* runner's `imageOverrideByContainer` (mutating the resolved service's
+* representative container's image to this tag).
+*
+* Each build runs sequentially (parallelism is left to docker's own
+* BuildKit cache — most overrides share a base image, so a sequential
+* order maximizes cache reuse). On any failure the function rejects
+* with {@link ImageOverrideError}; the emulator surfaces this before
+* any container is started.
+*
+* Partial-failure rollback (issue #242 / N3): when build N (1-indexed)
+* fails, the 1..(N-1) successfully built local-only tags from THIS run
+* are best-effort `docker image rm`'d before re-throwing. Not a leak
+* (the tags are deterministic per
+* {@link buildImageOverrideTag} so a re-run collides safely with any
+* leftover), but the cleanup keeps the local Docker daemon tidy after
+* a failed boot — disk-pressure scenarios that occasionally surface
+* on dev laptops never accumulate orphan override images across a
+* day of iterations. Cleanup failures are logged at `debug` (another
+* container could be using the image, the image could already have
+* been removed by a parallel `docker system prune`, etc.) and the
+* loop continues so one un-removable tag doesn't shadow the others.
+* The originating {@link ImageOverrideError} is always the thrown
+* value — a cleanup-step error never replaces it.
+*/
+async function runImageOverrideBuilds(overrides) {
+	const logger = getLogger();
+	const out = /* @__PURE__ */ new Map();
+	const builtTags = [];
+	for (const [target, entry] of overrides.entries()) {
+		const tag = buildImageOverrideTag(target, entry);
+		const args = [
+			"build",
+			"--tag",
+			tag,
+			"--file",
+			entry.dockerfile
+		];
+		for (const [k, v] of entry.buildArgs.entries()) args.push("--build-arg", `${k}=${v}`);
+		for (const [id, src] of entry.buildSecrets.entries()) args.push("--secret", `id=${id},src=${src}`);
+		if (entry.targetStage !== void 0) args.push("--target", entry.targetStage);
+		args.push(".");
+		logger.info(`Building override image for '${target}' from '${entry.dockerfile}' (tag=${tag})...`);
+		try {
+			await runDockerStreaming(args, {
+				cwd: entry.contextDir,
+				env: { BUILDX_NO_DEFAULT_ATTESTATIONS: "1" }
+			});
+		} catch (err) {
+			const e = err;
+			const wrapped = new ImageOverrideError(`docker build failed for --image-override '${target}' (Dockerfile=${entry.dockerfile}): ` + (e.stderr?.trim() || e.message || String(err)));
+			for (const priorTag of builtTags) try {
+				await runDockerStreaming([
+					"image",
+					"rm",
+					priorTag
+				], {});
+			} catch (rmErr) {
+				logger.debug(`Image-override rollback: \`docker image rm ${priorTag}\` failed: ${rmErr instanceof Error ? rmErr.message : String(rmErr)}.`);
+			}
+			throw wrapped;
+		}
+		out.set(target, tag);
+		builtTags.push(tag);
+	}
+	return out;
+}
+/**
+* Issue #240 — orphan validation. A per-service build-input flag
+* (`--image-build-arg <svc>:KEY=VAL`, `--image-build-secret
+* <svc>:id=src`, or `--image-target <svc>=stage`) names a service that
+* MUST appear in the resolved override map — otherwise the per-service
+* value silently gets discarded because no `docker build` runs for
+* that service.
+*
+* Called AFTER {@link resolveImageOverrides} (Stage 3 boot prompt
+* complete) so a service the user added via the prompt counts as
+* covered. A still-orphan per-service flag at this point means the
+* user typo'd the service name OR forgot a corresponding
+* `--image-override <svc>=<dockerfile>` mapping (and either chose `N`
+* in the boot prompt or ran with `--no-interactive-overrides`).
+*
+* Throws {@link LocalStartServiceError} naming every offending
+* `<flag>` + `<service>` pair so the user can fix all in one go
+* (matches the `enforceStrictOverrides` pattern). Mutates nothing.
+*
+* Host-side use case: cdkd and other shim hosts that wrap the engine
+* re-export this via `cdk-local/internal` and call it right after
+* their own `resolveImageOverrides` invocation to inherit the same
+* orphan-detection semantics.
+*
+* @param rawFlags Output of {@link parseImageOverrideFlags}.
+* @param resolvedOverrides Output of {@link resolveImageOverrides}
+*   (after the boot prompt has run).
+*/
+function enforceImageOverrideOrphans(rawFlags, resolvedOverrides) {
+	if (rawFlags.perService.size === 0) return;
+	const offenders = [];
+	for (const [svc, overlay] of rawFlags.perService.entries()) {
+		if (resolvedOverrides.has(svc)) continue;
+		if (overlay.buildArgs.size > 0) {
+			const keys = Array.from(overlay.buildArgs.keys()).join(", ");
+			offenders.push(`--image-build-arg ${svc}:${keys} references a service with no --image-override mapping.`);
+		}
+		if (overlay.buildSecrets.size > 0) {
+			const ids = Array.from(overlay.buildSecrets.keys()).join(", ");
+			offenders.push(`--image-build-secret ${svc}:${ids} references a service with no --image-override mapping.`);
+		}
+		if (overlay.targetStage !== void 0) offenders.push(`--image-target ${svc}=${overlay.targetStage} references a service with no --image-override mapping.`);
+	}
+	if (offenders.length === 0) return;
+	throw new LocalStartServiceError(`Per-service image-override flag(s) target a service with no --image-override coverage. Add the matching --image-override <service>=<dockerfile>, drop the per-service flag, or fix the service name:\n  ${offenders.join("\n  ")}`);
+}
 
 //#endregion
 //#region src/cli/commands/ecs-service-emulator.ts
@@ -24379,23 +24895,33 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		};
 		process.on("SIGINT", sigintHandler);
 		process.on("SIGTERM", sigintHandler);
-		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.boot, pt.runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService.get(pt.boot.target), strategy.suppressLoadBalancerWarning === true);
+		const imageOverrideTags = await resolveAndBuildImageOverrides({
+			perTarget: perTarget.map((pt) => pt.boot.target),
+			stacks,
+			options,
+			extraStateProviders,
+			logger
+		});
+		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.boot, pt.runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService.get(pt.boot.target), strategy.suppressLoadBalancerWarning === true, imageOverrideTags.get(pt.boot.target));
 		if (perTarget.length > 0) {
 			const summary = perTarget.map((pt) => `${pt.controller.service.serviceName} (${pt.controller.activeReplicaCount()} replica(s))`).join(", ");
 			logger.info(`Service(s) running: ${summary}.`);
 		} else logger.info(`Service(s) running: ${frontDoorLambdaRunners.length} Lambda target(s) behind the ALB front-door.`);
 		logEndpointsBanner(perTarget, frontDoorServers, logger);
 		logger.info("Press ^C to shut down.");
-		const watchActive = options.watch === true && strategy.supportsWatch === true;
-		if (watchActive) for (const pt of perTarget) {
-			const service = pt.controller?.service;
-			if (!service) continue;
-			if (isLocalCdkAssetImage(service)) continue;
-			const pinnedUri = describePinnedImageUri(service);
-			const uriDisplay = pinnedUri ? `\`${pinnedUri}\`` : "a deployed registry";
-			logger.warn(`'${pt.boot.target}': \`--watch\` will not pick up local source changes — running image is pinned to a deployed registry (${uriDisplay}). To iterate on local source, drop \`--from-cfn-stack\` and switch the CDK app to \`ContainerImage.fromAsset(...)\`.`);
-		}
-		if (watchActive) {
+		const uncoveredPinnedTargets = [];
+		const pinnedEntries = listPinnedTargets(perTarget.filter((pt) => pt.controller?.service).map((pt) => ({
+			target: pt.boot.target,
+			service: pt.controller.service
+		})));
+		for (const entry of pinnedEntries) {
+			if (imageOverrideTags.has(entry.target)) continue;
+			const uriDisplay = entry.label ? `\`${entry.label}\`` : "a deployed registry";
+			logger.warn(`'${entry.target}': running image is pinned to a deployed registry (${uriDisplay}). To iterate on local source, either pass \`--image-override <dockerfile>\` (or \`<service>=<dockerfile>\`) to substitute a local build, or drop \`--from-cfn-stack\` and switch the CDK app to \`ContainerImage.fromAsset(...)\`.`);
+			uncoveredPinnedTargets.push(entry.target);
+		}
+		enforceStrictOverrides(options.strictOverrides === true, uncoveredPinnedTargets);
+		if (options.watch === true && strategy.supportsWatch === true) {
 			const watchRoot = process.cwd();
 			const { ignored, shouldTrigger, excludePatterns } = createWatchPredicates({
 				watchRoot,
@@ -24422,6 +24948,7 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 						profileCredsFile,
 						frontDoorByService,
 						changedPaths,
+						imageOverrideTags,
 						logger
 					})).catch((err) => {
 						logger.error(`reloadAllServices threw: ${err instanceof Error ? err.message : String(err)}`);
@@ -24490,7 +25017,7 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 * via the logger so the user can fix the source + save again.
 */
 async function reloadAllServices(args) {
-	const { perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, changedPaths, logger } = args;
+	const { perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, changedPaths, imageOverrideTags, logger } = args;
 	let stacks;
 	try {
 		({stacks} = await synthesizer.synthesize(synthOpts));
@@ -24541,7 +25068,7 @@ async function reloadAllServices(args) {
 				reason: "classifier context unavailable; falling back to rebuild"
 			};
 		}
-		if (verdict.kind === "rebuild" && verdict.reason === "target image is not a CDK docker-image asset" && !isLocalCdkAssetImage(controller.service)) {
+		if (verdict.kind === "rebuild" && verdict.reason === "target image is not a CDK docker-image asset" && !isLocalCdkAssetImage(controller.service) && !imageOverrideTags.has(newBoot.target)) {
 			logger.info(`Reload skipped for '${newBoot.target}' (no-op): image pinned to deployed registry; no local rebuild possible.`);
 			continue;
 		}
@@ -24557,6 +25084,7 @@ async function reloadAllServices(args) {
 			frontDoorPools: frontDoorByService.get(newBoot.target),
 			suppressLoadBalancerWarning: strategy.suppressLoadBalancerWarning === true,
 			verdict,
+			...imageOverrideTags.get(newBoot.target) !== void 0 && { imageOverrideTag: imageOverrideTags.get(newBoot.target) },
 			logger
 		});
 	}
@@ -24633,13 +25161,16 @@ async function loadAssetContextForTarget(args) {
 * even when the resolve / roll throws.
 */
 async function rollOneTarget(args) {
-	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, verdict, logger } = args;
+	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, verdict, imageOverrideTag, logger } = args;
 	const candidate = pickCandidateStack(parseEcsTarget(newBoot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 	try {
 		let resolved;
 		try {
-			resolved = await resolveServiceAndRunnerOpts(newBoot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, { quiet: true });
+			resolved = await resolveServiceAndRunnerOpts(newBoot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, {
+				quiet: true,
+				...imageOverrideTag !== void 0 && { imageOverrideTag }
+			});
 		} catch (err) {
 			const reason = err instanceof Error ? err.message : String(err);
 			logger.error(`Reload of '${newBoot.target}' was rejected: ${reason}. Existing replica(s) keep serving.`);
@@ -24682,17 +25213,17 @@ async function rollOneTarget(args) {
 		if (stateProvider) stateProvider.dispose();
 	}
 }
-async function bootOneTarget(boot, runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning) {
+async function bootOneTarget(boot, runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag) {
 	const candidate = pickCandidateStack(parseEcsTarget(boot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 	try {
-		return await runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning);
+		return await runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag);
 	} finally {
 		if (stateProvider) stateProvider.dispose();
 	}
 }
-async function runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning) {
-	const { service, runnerOpts } = await resolveServiceAndRunnerOpts(boot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning);
+async function runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag) {
+	const { service, runnerOpts } = await resolveServiceAndRunnerOpts(boot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag !== void 0 ? { imageOverrideTag } : {});
 	return startEcsService(service, runnerOpts, runState);
 }
 /**
@@ -24775,6 +25306,10 @@ async function resolveServiceAndRunnerOpts(boot, stacks, options, discovery, ski
 		containerPath: profileCredsFile.containerPath,
 		profileName: profileCredsFile.profileName
 	};
+	if (opts.imageOverrideTag !== void 0) {
+		const essential = service.task.containers.find((c) => c.essential) ?? service.task.containers[0];
+		if (essential) taskOpts.imageOverrideByContainer = new Map([[essential.name, opts.imageOverrideTag]]);
+	}
 	return {
 		service,
 		runnerOpts: {
@@ -25230,6 +25765,86 @@ async function resolveSharedSidecarCredentials(options) {
 	if (options.profile) return resolveProfileCredentials(options.profile);
 }
 /**
+* Issue #238 — boot-time `--image-override` resolution + build pass.
+* Walks every booted service target's representative container image
+* to identify the pinned set (ECR / public-registry pin — the same
+* anchor `isLocalCdkAssetImage` uses), feeds the pinned set + raw
+* `--image-override` / `--image-build-arg` / `--image-build-secret` /
+* `--image-target` / `--no-interactive-overrides` flag values into
+* the engine ({@link resolveImageOverrides}), then `docker build`s
+* every covered Dockerfile via {@link runImageOverrideBuilds} and
+* returns the per-target local-tag map the boot path threads into
+* each runner.
+*
+* Sequential by design — most overrides share a base image, and the
+* engine's deterministic tag plus BuildKit's layer cache make
+* sequential builds nearly as fast as a parallel fan-out while
+* keeping the build log readable. Throws on a parser / picker /
+* build failure; the outer try/finally tears down what was set up.
+*
+* The boot prompt is fired only when STDIN+STDOUT are TTYs AND
+* `--no-interactive-overrides` is unset; non-TTY contexts silently
+* skip the prompt and rely on whatever the explicit flags resolved.
+*/
+async function resolveAndBuildImageOverrides(args) {
+	const { perTarget, stacks, options, extraStateProviders, logger } = args;
+	const resolvedForPeek = [];
+	for (const target of perTarget) {
+		const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+		const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
+		let imageContext;
+		let service;
+		try {
+			imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
+			service = resolveEcsServiceTarget(target, stacks, imageContext, { suppressLoadBalancerWarning: true });
+		} catch (err) {
+			logger.debug(`--image-override peek failed for '${target}': ${err instanceof Error ? err.message : String(err)}.`);
+			continue;
+		} finally {
+			if (stateProvider) stateProvider.dispose();
+		}
+		if (!service) continue;
+		resolvedForPeek.push({
+			target,
+			service
+		});
+	}
+	const pinnedEntries = listPinnedTargets(resolvedForPeek);
+	const pinnedTargets = pinnedEntries.map((e) => e.target);
+	const pinnedLabels = /* @__PURE__ */ new Map();
+	for (const entry of pinnedEntries) if (entry.label !== void 0) pinnedLabels.set(entry.target, entry.label);
+	const rawFlags = parseImageOverrideFlags({
+		...options.imageOverride && { imageOverride: options.imageOverride },
+		...options.imageBuildArg && { imageBuildArg: options.imageBuildArg },
+		...options.imageBuildSecret && { imageBuildSecret: options.imageBuildSecret },
+		...options.imageTarget && { imageTarget: options.imageTarget }
+	});
+	if (pinnedTargets.length === 0 && rawFlags.explicit.size === 0 && rawFlags.pickerPaths.length === 0 && rawFlags.perService.size === 0) return /* @__PURE__ */ new Map();
+	const overrides = await resolveImageOverrides({
+		rawFlags,
+		pinnedTargets,
+		pinnedLabels,
+		interactiveBootPrompt: true,
+		noInteractive: options.interactiveOverrides === false
+	});
+	enforceImageOverrideOrphans(rawFlags, overrides);
+	if (overrides.size === 0) return /* @__PURE__ */ new Map();
+	return runImageOverrideBuilds(overrides);
+}
+/**
+* Issue #238 — `--strict-overrides` guard. Extracted so the boot path's
+* fail-fast behavior can be exercised under a unit test without booting
+* the full emulator. Throws {@link LocalStartServiceError} when `strict`
+* is true AND at least one pinned target remains uncovered; otherwise a
+* no-op. The error message names every uncovered target so the user can
+* pass the corresponding `--image-override` mapping.
+*/
+function enforceStrictOverrides(strict, uncoveredPinnedTargets) {
+	if (!strict) return;
+	if (uncoveredPinnedTargets.length === 0) return;
+	throw new LocalStartServiceError(`--strict-overrides set, but ${uncoveredPinnedTargets.length} pinned target(s) remain uncovered: ${uncoveredPinnedTargets.join(", ")}. Pass --image-override <service>=<dockerfile> for each, drop --strict-overrides, or drop --from-cfn-stack to iterate on local CDK assets.`);
+}
+/**
 * Add the CLI options shared by both ECS-service commands (`start-service` and
 * `start-alb`) to a command. The command-specific argument / description and
 * the one unique option (`--host-port` vs `--lb-port`) are added by each
@@ -25245,6 +25860,25 @@ function addCommonEcsServiceOptions(cmd) {
 	cmd.addOption(deprecatedRegionOption);
 	return cmd;
 }
+/**
+* Issue #238 — register the `--image-override` flag family shared by
+* `cdkl start-service` and `cdkl start-alb`. Both commands accept the
+* same six flags; this helper keeps the wording in one place so a
+* future copy edit lands in both surfaces simultaneously.
+*
+* `--image-override` is repeatable (accumulator); `--image-build-arg`
+* and `--image-build-secret` are repeatable too; `--image-target` is a
+* single string (the global multi-stage target); `--no-interactive-overrides`
+* and `--strict-overrides` are booleans. The engine in
+* {@link runEcsServiceEmulator}'s boot path consumes them.
+*
+* Shared between `cdkl start-service` and `cdkl start-alb` and exposed
+* via `cdk-local/internal` so host CLIs (e.g. cdkd) that wrap the same
+* factories inherit the flag set without duplication.
+*/
+function addImageOverrideOptions(cmd) {
+	return cmd.addOption(new Option("--image-override <service=dockerfile or dockerfile...>", "Replace a service target's deployed-registry image with a local `docker build` of the supplied Dockerfile (repeatable). Two forms: <service>=<dockerfile> binds the service explicitly; a bare <dockerfile> opens a multi-select picker against the still-uncovered pinned targets (one Dockerfile across N services). Mix freely. Lets `--from-cfn-stack` still reach real AWS state while you iterate locally on the application container.")).addOption(new Option("--image-build-arg <KEY=VAL...>", "Global `docker build --build-arg KEY=VAL` pair applied to every --image-override build (repeatable). Lets a CDK Dockerfile that branches on an ARG (env target, base image tag, package mirror) honor that ARG locally without editing the Dockerfile.")).addOption(new Option("--image-build-secret <id=src...>", "Global `docker build --secret id=<id>,src=<src>` entry applied to every --image-override build (repeatable). Enables `RUN --mount=type=secret,id=<id>` in the Dockerfile — the standard private-registry / npm-token recipe (e.g. `--image-build-secret npmrc=./.npmrc`).")).addOption(new Option("--image-target <stage or svc=stage...>", "Repeatable. Bare `<stage>` is a global --target for every --image-override build; `<service>=<stage>` (issue #240) scopes the --target to one overridden target so a monorepo with different multi-stage Dockerfiles per service can stop each at its own intermediate stage. Per-service form overrides the global on the named target.")).addOption(new Option("--no-interactive-overrides", "Suppress the interactive boot prompt that walks each pinned target asking for a Dockerfile path, and the multi-select prompt fired by `--image-override <dockerfile>` (picker form). Useful for CI / scripted invocations.")).addOption(new Option("--strict-overrides", "Fail fast at boot when any pinned target remains uncovered after `--image-override` + the boot prompt resolve. Off by default; the boot WARN per uncovered pinned target still fires regardless.").default(false));
+}
 
 //#endregion
 //#region src/cli/commands/local-start-service.ts
@@ -25315,6 +25949,7 @@ function createLocalStartServiceCommand(opts = {}) {
 * for that contract to live.
 */
 function addStartServiceSpecificOptions(cmd) {
+	addImageOverrideOptions(cmd);
 	return cmd.addOption(new Option("--host-port <containerPort=hostPort...>", "Publish a container port on a specific host port (e.g. 80=8080); repeatable. Default: host port == container port. Use this on macOS to map a privileged container port (< 1024) to a non-privileged host port and avoid the Docker Desktop admin-password prompt. (Single-replica services only — multi-replica services do not publish host ports.)")).addOption(new Option("--watch", "Hot-reload: re-synth + per-replica reload when the CDK source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). A per-firing classifier picks the per-replica primitive: source-only edits on interpreted-language handlers (Node/Python/Ruby/shell) take a bind-mount FAST PATH (`docker cp` the new source into each replica + `docker restart`; no rebuild). Dockerfile / dependency manifest / compiled-language source / ambiguous edits fall through to the rebuild rolling primitive — boot a shadow under a bumped generation suffix, wait for its container port to accept a TCP connection, atomically swap Service-Connect / Cloud Map registrations, then retire the old container. Either path rolls one replica at a time, so peer services see zero connection refusals across the reload even on multi-replica services. Off by default; existing replica(s) keep serving when synth fails mid-reload.").default(false));
 }
 
@@ -26168,6 +26803,7 @@ function createLocalStartAlbCommand(opts = {}) {
 * clusters. Chainable: returns `cmd`.
 */
 function addAlbSpecificOptions(cmd) {
+	addImageOverrideOptions(cmd);
 	return cmd.addOption(new Option("--lb-port <listenerPort=hostPort...>", "Bind the local front-door on a specific host port (e.g. 80=8080); repeatable. Default: host port == ALB listener port. Use this on macOS to remap a privileged listener port (< 1024) to a non-privileged host port.")).addOption(new Option("--tls", "Terminate TLS locally for cloud-HTTPS listeners. Default: a cloud-HTTPS listener is served over plain HTTP locally (X-Forwarded-Proto: https is preserved so the upstream app still sees the deployed listener protocol). Implied by --tls-cert / --tls-key. Use this when local-dev cookies need Secure / SameSite=None, when the upstream app inspects TLS metadata, or for mTLS / SNI testing — otherwise plain HTTP is friendlier (no self-signed cert warnings in curl / browser).")).addOption(new Option("--tls-cert <path>", "PEM-encoded server certificate for HTTPS front-door listeners. Implies --tls. Must be set together with --tls-key. Pass --tls alone (without --tls-cert / --tls-key) to auto-generate a self-signed cert (cached under $XDG_CACHE_HOME/cdk-local/alb-https/, default ~/.cache/cdk-local/alb-https/); requires openssl on PATH. The deployed Listener Certificates[] are NOT fetched (ACM private keys are not retrievable by design). The auto-generated cert lists DNS:localhost,IP:127.0.0.1 as SubjectAltName, so a client validating a non-loopback --container-host will fail the SAN check — pass --tls-cert / --tls-key with a SAN covering that host instead.")).addOption(new Option("--tls-key <path>", "PEM-encoded server private key matching --tls-cert. Implies --tls. Must be set together with --tls-cert.")).addOption(new Option("--no-verify-auth", "Disable local enforcement of authenticate-cognito / authenticate-oidc actions. Every request is served as if the auth check passed. Useful for local dev where you do not want to mint a Bearer token at all.")).addOption(new Option("--bearer-token <jwt>", "Default Bearer JWT injected as Authorization: Bearer <jwt> when the inbound request has none. Verified against the same JWKS / OIDC discovery URL the deployed ALB would (signature + iss + aud + exp). Local-dev convenience; cookie pass-through (AWSELBAuthSessionCookie-*) also works.")).addOption(new Option("--watch", "Hot-reload: re-synth + per-replica reload of every ECS service behind the ALB when the CDK source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). A per-firing classifier picks the per-replica primitive: source-only edits on interpreted-language handlers (Node/Python/Ruby/shell) take a bind-mount FAST PATH (`docker cp` the new source into each replica + `docker restart`; no rebuild, front-door pool entry unchanged since the IP/port are preserved). Dockerfile / dependency manifest / compiled-language source / ambiguous edits fall through to the rebuild rolling primitive — boot a shadow under a bumped generation suffix, wait for its container port to accept a TCP connection, atomically register it in the front-door pool, then drop the old entry and retire the old container. Either path rolls one replica at a time, so a continuous external request stream against the listener port sees zero connection refusals across the reload. The host front-door (TLS, JWKS cache, Lambda-target containers, listener sockets) stays up across the reload. Lambda target groups behind the ALB are a no-op on reload (the warm RIE container keeps its boot-time image). Off by default; existing replica(s) keep serving when synth fails mid-reload.").default(false));
 }
 
@@ -26264,5 +26900,5 @@ function addListSpecificOptions(cmd) {
 }
 
 //#endregion
-export { invokeRequestAuthorizer as $, addInvokeSpecificOptions as $t, attachContainerLogStreamer as A, discoverRoutes as An, buildCorsConfigFromCloudFrontChain as At, buildStageMap as B, resolveAgentCoreTarget as Bn, mcpInvokeOnce as Bt, buildCloudMapIndex as C, resolveWatchConfig as Cn, createJwksCache as Ct, getContainerNetworkIp as D, discoverWebSocketApis as Dn, attachAuthorizers as Dt, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as E, listTargets as En, verifyJwtViaDiscovery as Et, createWatchPredicates as F, AGENTCORE_HTTP_PROTOCOL as Fn, A2A_PATH as Ft, readMtlsMaterialsFromDisk as G, LocalInvokeBuildError as Gn, invokeAgentCore as Gt, filterRoutesByApiIdentifier as H, formatStateRemedy as Hn, AGENTCORE_SIGV4_SERVICE as Ht, resolveApiTargetSubset as I, AGENTCORE_MCP_PROTOCOL as In, a2aInvokeOnce as It, resolveServiceIntegrationParameters as J, SUPPORTED_CODE_RUNTIMES as Jt, startApiServer as K, waitForAgentCorePing as Kt, createAuthorizerCache as L, AGENTCORE_RUNTIME_TYPE as Ln, MCP_CONTAINER_PORT as Lt, createLocalInvokeAgentCoreCommand as M, resolveLambdaArnIntrinsic as Mn, matchPreflight as Mt, addStartApiSpecificOptions as N, AGENTCORE_A2A_PROTOCOL as Nn, invokeAgentCoreWs as Nt, addRunTaskSpecificOptions as O, discoverWebSocketApisOrThrow as On, applyCorsResponseHeaders as Ot, createLocalStartApiCommand as P, AGENTCORE_AGUI_PROTOCOL as Pn, A2A_CONTAINER_PORT as Pt, evaluateCachedLambdaPolicy as Q, toCmdArgv as Qt, createFileWatcher as R, AgentCoreResolutionError as Rn, MCP_PATH as Rt, isLocalCdkAssetImage as S, resolveSsmParameters as Sn, buildJwksUrlFromIssuer as St, classifySourceChange as T, countTargets as Tn, verifyJwtAuthorizer as Tt, filterRoutesByApiIdentifiers as U, substituteImagePlaceholders as Un, signAgentCoreInvocation as Ut, availableApiIdentifiers as V, derivePseudoParametersFromRegion as Vn, parseSseForJsonRpc as Vt, groupRoutesByServer as W, tryResolveImageFnJoin as Wn, AGENTCORE_SESSION_ID_HEADER as Wt, buildMethodArn as X, computeCodeImageTag as Xt, defaultCredentialsLoader as Y, buildAgentCoreCodeImage as Yt, computeRequestIdentityHash as Z, renderCodeDockerfile as Zt, parseMaxTasks as _, resolveCfnFallbackRegion as _n, parseConnectionsPath as _t, albStrategy as a, resolveRuntimeImage as an, buildRestV1Event as at, runEcsServiceEmulator as b, CfnLocalStateProvider as bn, buildMessageEvent as bt, resolveAlbTarget as c, substituteAgainstStateAsync as cn, selectIntegrationResponse as ct, addStartServiceSpecificOptions as d, resolveEnvVars as dn, HOST_GATEWAY_MIN_VERSION as dt, createLocalInvokeCommand as en, invokeTokenAuthorizer as et, createLocalStartServiceCommand as f, materializeLayerFromArn as fn, probeHostGatewaySupport as ft, buildEcsImageResolutionContext as g, rejectExplicitCfnStackWithMultipleStacks as gn, handleConnectionsRequest as gt, addCommonEcsServiceOptions as h, isCfnFlagPresent as hn, buildMgmtEndpointEnvUrl as ht, addAlbSpecificOptions as i, resolveRuntimeFileExtension as in, buildHttpApiV2Event as it, addInvokeAgentCoreSpecificOptions as j, pickRefLogicalId as jn, isFunctionUrlOacFronted as jt, createLocalRunTaskCommand as k, parseSelectionExpressionPath as kn, buildCorsConfigByApiId as kt, isApplicationLoadBalancer as l, substituteEnvVarsFromState as ln, tryParseStatus as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, createLocalStateProvider as mn, ConnectionRegistry as mt, createLocalListCommand as n, buildContainerImage as nn, translateLambdaResponse as nt, createLocalStartAlbCommand as o, EcsTaskResolutionError as on, evaluateResponseParameters as ot, serviceStrategy as p, LocalStateSourceError as pn, bufferToBody as pt, resolveSelectionExpression as q, downloadAndExtractS3Bundle as qt, formatTargetListing as r, resolveRuntimeCodeMountPath as rn, applyAuthorizerOverlay as rt, parseLbPortOverrides as s, substituteAgainstState as sn, pickResponseTemplate as st, addListSpecificOptions as t, architectureToPlatform as tn, matchRoute as tt, resolveAlbFrontDoor as u, substituteEnvVarsFromStateAsync as un, VtlEvaluationError as ut, parseRestartPolicy as v, resolveCfnRegion as vn, buildConnectEvent as vt, CloudMapRegistry as w, resolveSingleTarget as wn, verifyCognitoJwt as wt, describePinnedImageUri as x, collectSsmParameterRefs as xn, buildCognitoJwksUrl as xt, resolveSharedSidecarCredentials as y, resolveCfnStackName as yn, buildDisconnectEvent as yt, attachStageContext as z, pickAgentCoreCandidateStack as zn, MCP_PROTOCOL_VERSION as zt };
-//# sourceMappingURL=local-list-BS463YYd.js.map
+export { groupRoutesByServer as $, tryResolveImageFnJoin as $n, AGENTCORE_SESSION_ID_HEADER as $t, isLocalCdkAssetImage as A, collectSsmParameterRefs as An, buildCognitoJwksUrl as At, addInvokeAgentCoreSpecificOptions as B, pickRefLogicalId as Bn, isFunctionUrlOacFronted as Bt, buildImageOverrideTag as C, createLocalStateProvider as Cn, ConnectionRegistry as Ct, resolveImageOverrides as D, resolveCfnRegion as Dn, buildConnectEvent as Dt, parseImageOverrideFlags as E, resolveCfnFallbackRegion as En, parseConnectionsPath as Et, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as F, listTargets as Fn, verifyJwtViaDiscovery as Ft, resolveApiTargetSubset as G, AGENTCORE_MCP_PROTOCOL as Gn, a2aInvokeOnce as Gt, addStartApiSpecificOptions as H, AGENTCORE_A2A_PROTOCOL as Hn, invokeAgentCoreWs as Ht, getContainerNetworkIp as I, discoverWebSocketApis as In, attachAuthorizers as It, attachStageContext as J, pickAgentCoreCandidateStack as Jn, MCP_PROTOCOL_VERSION as Jt, createAuthorizerCache as K, AGENTCORE_RUNTIME_TYPE as Kn, MCP_CONTAINER_PORT as Kt, addRunTaskSpecificOptions as L, discoverWebSocketApisOrThrow as Ln, applyCorsResponseHeaders as Lt, buildCloudMapIndex as M, resolveWatchConfig as Mn, createJwksCache as Mt, CloudMapRegistry as N, resolveSingleTarget as Nn, verifyCognitoJwt as Nt, runImageOverrideBuilds as O, resolveCfnStackName as On, buildDisconnectEvent as Ot, classifySourceChange as P, countTargets as Pn, verifyJwtAuthorizer as Pt, filterRoutesByApiIdentifiers as Q, substituteImagePlaceholders as Qn, signAgentCoreInvocation as Qt, createLocalRunTaskCommand as R, parseSelectionExpressionPath as Rn, buildCorsConfigByApiId as Rt, ImageOverrideError as S, LocalStateSourceError as Sn, bufferToBody as St, mergeForService as T, rejectExplicitCfnStackWithMultipleStacks as Tn, handleConnectionsRequest as Tt, createLocalStartApiCommand as U, AGENTCORE_AGUI_PROTOCOL as Un, A2A_CONTAINER_PORT as Ut, createLocalInvokeAgentCoreCommand as V, resolveLambdaArnIntrinsic as Vn, matchPreflight as Vt, createWatchPredicates as W, AGENTCORE_HTTP_PROTOCOL as Wn, A2A_PATH as Wt, availableApiIdentifiers as X, derivePseudoParametersFromRegion as Xn, parseSseForJsonRpc as Xt, buildStageMap as Y, resolveAgentCoreTarget as Yn, mcpInvokeOnce as Yt, filterRoutesByApiIdentifier as Z, formatStateRemedy as Zn, AGENTCORE_SIGV4_SERVICE as Zt, buildEcsImageResolutionContext as _, substituteAgainstStateAsync as _n, selectIntegrationResponse as _t, albStrategy as a, computeCodeImageTag as an, buildMethodArn as at, resolveSharedSidecarCredentials as b, resolveEnvVars as bn, HOST_GATEWAY_MIN_VERSION as bt, resolveAlbTarget as c, addInvokeSpecificOptions as cn, invokeRequestAuthorizer as ct, addStartServiceSpecificOptions as d, buildContainerImage as dn, translateLambdaResponse as dt, invokeAgentCore as en, LocalInvokeBuildError as er, readMtlsMaterialsFromDisk as et, createLocalStartServiceCommand as f, resolveRuntimeCodeMountPath as fn, applyAuthorizerOverlay as ft, addImageOverrideOptions as g, substituteAgainstState as gn, pickResponseTemplate as gt, addCommonEcsServiceOptions as h, EcsTaskResolutionError as hn, evaluateResponseParameters as ht, addAlbSpecificOptions as i, buildAgentCoreCodeImage as in, defaultCredentialsLoader as it, listPinnedTargets as j, resolveSsmParameters as jn, buildJwksUrlFromIssuer as jt, describePinnedImageUri as k, CfnLocalStateProvider as kn, buildMessageEvent as kt, isApplicationLoadBalancer as l, createLocalInvokeCommand as ln, invokeTokenAuthorizer as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, resolveRuntimeImage as mn, buildRestV1Event as mt, createLocalListCommand as n, downloadAndExtractS3Bundle as nn, resolveSelectionExpression as nt, createLocalStartAlbCommand as o, renderCodeDockerfile as on, computeRequestIdentityHash as ot, serviceStrategy as p, resolveRuntimeFileExtension as pn, buildHttpApiV2Event as pt, createFileWatcher as q, AgentCoreResolutionError as qn, MCP_PATH as qt, formatTargetListing as r, SUPPORTED_CODE_RUNTIMES as rn, resolveServiceIntegrationParameters as rt, parseLbPortOverrides as s, toCmdArgv as sn, evaluateCachedLambdaPolicy as st, addListSpecificOptions as t, waitForAgentCorePing as tn, startApiServer as tt, resolveAlbFrontDoor as u, architectureToPlatform as un, matchRoute as ut, parseMaxTasks as v, substituteEnvVarsFromState as vn, tryParseStatus as vt, enforceImageOverrideOrphans as w, isCfnFlagPresent as wn, buildMgmtEndpointEnvUrl as wt, runEcsServiceEmulator as x, materializeLayerFromArn as xn, probeHostGatewaySupport as xt, parseRestartPolicy as y, substituteEnvVarsFromStateAsync as yn, VtlEvaluationError as yt, attachContainerLogStreamer as z, discoverRoutes as zn, buildCorsConfigFromCloudFrontChain as zt };
+//# sourceMappingURL=local-list-Ch0RglJl.js.map