cdk-local 0.68.0 → 0.70.0

package/dist/{local-list-BFtuOXLq.js → local-list-C-wXKogn.js}

@@ -1,8 +1,8 @@
 import { a as runDockerStreaming, c as getEmbedConfig, i as runDockerForeground, n as formatDockerLoginError, o as spawnStreaming, r as getDockerCmd, s as getLogger, u as setEmbedConfig } from "./docker-cmd-voNPrcRh.js";
 import { cpSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import * as path from "node:path";
-import { dirname, isAbsolute, join, normalize, resolve, sep } from "node:path";
+import * as path$1 from "node:path";
+import path, { dirname, isAbsolute, join, normalize, resolve, sep } from "node:path";
 import { Command, Option } from "commander";
 import { AssumeRoleCommand, GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
 import { MultiSelectPrompt } from "@clack/core";
@@ -7834,8 +7834,8 @@ function getContainerAwsCredentialsPath() {
 async function writeProfileCredentialsFile(profileName, creds) {
 	if (profileName === "") throw new Error("writeProfileCredentialsFile: profile name must not be empty.");
 	if (/[\r\n[\]]/.test(profileName)) throw new Error(`writeProfileCredentialsFile: profile name '${profileName}' contains a forbidden character (any of CR, LF, '[', ']' would corrupt the INI file or the docker -e env var).`);
-	const dir = await mkdtemp(path.join(tmpdir(), `${getEmbedConfig().productName}-profile-creds-`));
-	const hostPath = path.join(dir, "credentials");
+	const dir = await mkdtemp(path$1.join(tmpdir(), `${getEmbedConfig().productName}-profile-creds-`));
+	const hostPath = path$1.join(dir, "credentials");
 	const lines = [
 		`[${profileName}]`,
 		`aws_access_key_id = ${creds.accessKeyId}`,
@@ -8177,7 +8177,7 @@ function materializeLambdaLayers$1(layers) {
 		containerPath: "/opt",
 		readOnly: true
 	} };
-	const tmpDir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-invoke-layers-`));
+	const tmpDir = mkdtempSync(path$1.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-invoke-layers-`));
 	for (const layer of layers) cpSync(layer.assetPath, tmpDir, {
 		recursive: true,
 		force: true
@@ -8385,9 +8385,9 @@ function materializeInlineCode$2(handler, source, fileExtension) {
 	const lastDot = handler.lastIndexOf(".");
 	if (lastDot <= 0) throw new Error(`Handler '${handler}' is malformed: expected '<modulePath>.<exportName>'.`);
 	const modulePath = handler.substring(0, lastDot);
-	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-invoke-`));
-	const filePath = path.join(dir, `${modulePath}${fileExtension}`);
-	mkdirSync(path.dirname(filePath), { recursive: true });
+	const dir = mkdtempSync(path$1.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-invoke-`));
+	const filePath = path$1.join(dir, `${modulePath}${fileExtension}`);
+	mkdirSync(path$1.dirname(filePath), { recursive: true });
 	writeFileSync(filePath, source, "utf-8");
 	return dir;
 }
@@ -16510,15 +16510,19 @@ function createFileWatcher(options) {
 		...options.ignored && { ignored: options.ignored }
 	});
 	let timer = null;
+	let pending = /* @__PURE__ */ new Set();
 	let closed = false;
-	const fire = () => {
+	const fire = (path) => {
 		if (closed) return;
+		pending.add(path);
 		if (timer) clearTimeout(timer);
 		timer = setTimeout(() => {
 			timer = null;
 			if (closed) return;
+			const changed = Array.from(pending);
+			pending = /* @__PURE__ */ new Set();
 			try {
-				options.onChange();
+				options.onChange(changed);
 			} catch (err) {
 				logger.warn(`onChange callback threw: ${err instanceof Error ? err.message : String(err)}`);
 			}
@@ -16527,7 +16531,7 @@ function createFileWatcher(options) {
 	};
 	const onEvent = (path) => {
 		if (options.shouldTrigger && !options.shouldTrigger(path)) return;
-		fire();
+		fire(path);
 	};
 	watcher.on("add", onEvent);
 	watcher.on("change", onEvent);
@@ -17040,8 +17044,8 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 */
 function createWatchPredicates(args) {
 	const { watchRoot, output, watchConfig } = args;
-	const toRel = (abs) => path.relative(watchRoot, abs).split(path.sep).join("/");
-	const outputRel = toRel(path.resolve(watchRoot, output));
+	const toRel = (abs) => path$1.relative(watchRoot, abs).split(path$1.sep).join("/");
+	const outputRel = toRel(path$1.resolve(watchRoot, output));
 	const excludePatterns = [
 		...outputRel !== "" && !outputRel.startsWith("..") ? [outputRel] : [],
 		"node_modules",
@@ -17546,7 +17550,7 @@ async function resolveContainerImageForStartApi(lambda, skipPull, profile) {
 async function resolveLocalBuildPlan(lambda) {
 	const manifestPath = lambda.stack.assetManifestPath;
 	if (!manifestPath) return void 0;
-	const cdkOutDir = path.dirname(manifestPath);
+	const cdkOutDir = path$1.dirname(manifestPath);
 	const manifest = await new AssetManifestLoader().loadManifest(cdkOutDir, lambda.stack.stackName);
 	if (!manifest) return void 0;
 	const entry = getDockerImageBySourceHash(manifest, lambda.imageUri);
@@ -17603,7 +17607,7 @@ async function materializeLambdaLayers(layers, layerTmpDirs, layerRoleArn) {
 		});
 	}
 	if (flat.length === 1) return flat[0].assetPath;
-	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-layers-`));
+	const dir = mkdtempSync(path$1.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-layers-`));
 	for (const layer of flat) cpSync(layer.assetPath, dir, {
 		recursive: true,
 		force: true
@@ -17742,8 +17746,8 @@ function resolveImageLambda(args) {
 function resolveAssetCodePath(stack, logicalId, resource) {
 	const assetPath = resource.Metadata?.["aws:asset:path"];
 	if (typeof assetPath !== "string" || assetPath.length === 0) throw new Error(`Lambda '${logicalId}' has no Metadata['aws:asset:path']. ${getEmbedConfig().cliName} start-api needs this hint to find the local asset directory. Re-synthesize the app and retry.`);
-	const cdkOutDir = stack.assetManifestPath ? path.dirname(stack.assetManifestPath) : process.cwd();
-	return path.isAbsolute(assetPath) ? assetPath : path.resolve(cdkOutDir, assetPath);
+	const cdkOutDir = stack.assetManifestPath ? path$1.dirname(stack.assetManifestPath) : process.cwd();
+	return path$1.isAbsolute(assetPath) ? assetPath : path$1.resolve(cdkOutDir, assetPath);
 }
 /**
 * Print the discovered route table to stdout. Format mirrors the spec
@@ -17798,10 +17802,10 @@ function materializeInlineCode$1(handler, source, fileExtension, tmpDirsOut) {
 	const lastDot = handler.lastIndexOf(".");
 	if (lastDot <= 0) throw new Error(`Handler '${handler}' is malformed: expected '<modulePath>.<exportName>'.`);
 	const modulePath = handler.substring(0, lastDot);
-	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-`));
+	const dir = mkdtempSync(path$1.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-`));
 	tmpDirsOut.add(dir);
-	const filePath = path.join(dir, `${modulePath}${fileExtension}`);
-	mkdirSync(path.dirname(filePath), { recursive: true });
+	const filePath = path$1.join(dir, `${modulePath}${fileExtension}`);
+	mkdirSync(path$1.dirname(filePath), { recursive: true });
 	writeFileSync(filePath, source, "utf-8");
 	return dir;
 }
@@ -20883,6 +20887,22 @@ var EcsServiceRunnerError = class EcsServiceRunnerError extends Error {
 		Object.setPrototypeOf(this, EcsServiceRunnerError.prototype);
 	}
 };
+/**
+* Phase 4 (#214) — completion-log suffix the soft-reload primitive
+* emits AFTER `Soft-reloaded replica r<i> (gen <g>): ` to confirm
+* the docker restart + TCP-ready probe + Cloud Map / front-door
+* re-publish round trip is done.
+*
+* Exported so integ fixtures + unit tests can grep against the
+* canonical text instead of hand-copying the wording — a future
+* refactor that rewords this line stays detectable via the symbol
+* import instead of silently breaking every test's regex.
+*
+* Per-repo memory (#218 / test reviewer N4): log-line text is part
+* of the public contract for `--watch` integ scripts, so it earns a
+* constant.
+*/
+const SOFT_RELOAD_COMPLETION_LOG_SUFFIX = "restart + TCP-ready probe complete; Cloud Map + front-door re-published.";
 function createServiceRunState() {
 	return {
 		replicas: [],
@@ -21137,6 +21157,27 @@ async function bootReplica(service, options, instance) {
 	await runEcsTask(service.task, perReplicaTaskOptions, instance.state);
 	if (options.discovery) await publishReplicaToCloudMap(service, instance, options.discovery, ownerKeyPrefix);
 	if (options.frontDoor) await publishReplicaToFrontDoor(service, instance, options.frontDoor, options.taskOptions.containerHost, ownerKeyPrefix);
+	instance.lastDeployedAssetHash = pickEssentialAssetHash(service);
+}
+/**
+* Phase 4 follow-up (#218) — extract the CDK asset hash from a
+* resolved service's first essential container (with the same
+* fallback the watcher uses: first essential, else first container).
+* Returns `undefined` when the image isn't a CDK asset OR carries
+* no hash. Pure helper so the boot + rolling + soft-reload paths
+* share one source of truth for "what's running right now".
+*
+* Exported for unit tests; not part of the semver-covered public
+* surface.
+*
+* @internal
+*/
+function pickEssentialAssetHash(service) {
+	const essential = service.task.containers.find((c) => c.essential) ?? service.task.containers[0];
+	if (!essential) return void 0;
+	const image = essential.image;
+	if (image?.kind !== "cdk-asset") return void 0;
+	return image.assetHash;
 }
 /**
 * After the replica's main container is up, discover its docker
@@ -21404,6 +21445,202 @@ async function rollServiceReplica(args) {
 	logger.info(`Rolling replica ${shadow.index} (gen ${shadow.generation}): swap complete; old retired.`);
 }
 /**
+* Phase 4 of issue #214 — bind-mount source fast path. `docker cp` the
+* post-synth asset source directory into each essential container of
+* the live replica, then `docker restart` it. Skips `docker build`,
+* skips a shadow boot, and keeps the container's network IP / Cloud
+* Map / front-door pool registrations intact (the registrations key
+* off the docker-assigned IP and the published host port; `docker
+* restart` preserves both via the container's stable network
+* namespace), so NO registry swap is needed.
+*
+* Sequence (per replica, sequenced by the rolling loop one at a time
+* so peer services + the ALB front-door always have at least N-1 live
+* endpoints across the reload — same zero-connection-refusal guarantee
+* the Phase 2/3 rebuild pathway makes):
+*   1. Locate the live replica by {@link oldReplicaIndex}; reject when
+*      shutting down (the next save can roll a clean boot instead).
+*   2. Pre-restart DRAIN: drop the replica's Cloud Map handles + every
+*      front-door pool entry under its owner key. Both registries are
+*      synchronous Map mutations; once these complete, peer wget +
+*      front-door `next()` calls route to the surviving replicas. The
+*      handle / owner-key snapshots are kept on `instance.*` so the
+*      symmetric re-register step can pick them up (Cloud Map handles
+*      are rebuilt fresh via `publishReplicaToCloudMap`; the docker
+*      network IP is preserved across `docker restart` so the new
+*      handles point at the SAME endpoint).
+*   3. Set {@link ServiceReplicaInstance.softReloadInProgress} = true
+*      so the watcher's `waitForExitImpl` post-exit branch defers to
+*      the in-flight restart instead of re-bootstrapping the replica
+*      from scratch.
+*   4. For each essential container in the replica's started set:
+*      a. Resolve the container's image WORKDIR via `docker inspect`
+*         (default `/` when unset — matches Docker's runtime default
+*         for a Dockerfile with no `WORKDIR`).
+*      b. `docker cp <sourceDirToCopy>/. <containerId>:<workdir>/`
+*         — copy the synthesized asset directory's contents into the
+*         container at the WORKDIR. Trailing `/.` is critical: it
+*         copies the SOURCE DIRECTORY'S CONTENTS, not the directory
+*         itself, mirroring `cp -r src/. dst/`.
+*      c. `docker restart <containerId>` — cycle PID 1. Image,
+*         network namespace, and host-port publish are preserved.
+*   5. {@link waitForReplicaTcpReady} confirms the essential
+*      container's first port accepts a TCP connection.
+*   6. Post-TCP-ready RE-REGISTER: re-publish Cloud Map handles +
+*      front-door pool entry under the SAME per-replica owner key
+*      prefix used at initial boot, so the registrations remain
+*      idempotent across multiple `--watch` reloads. After this
+*      step, peers + the front-door route to the replica again.
+*   7. Clear `softReloadInProgress` in a `finally` so the watcher
+*      always exits its defer-loop, even on a docker error.
+*
+* Failure modes:
+*   - `docker inspect` / `docker cp` / `docker restart` errors:
+*     surfaced to the caller via a throw. The replica may be in an
+*     inconsistent state (drained from registries + partial cp + a
+*     possibly-crashed PID 1). The caller (`reloadAllServices`) logs
+*     the failure and continues with the remaining replicas; the
+*     drained state is intentionally NOT re-registered on error so
+*     peers + the front-door stop routing to a broken replica until
+*     the next clean save (or `^C` and re-run).
+*   - TCP probe timeout: best-effort warn (mirrors
+*     {@link rollServiceReplica}); the registrations are re-published
+*     anyway because the container IS up — just slow to bind. The
+*     dying-old-handles-AND-fresh-app-not-yet-listening worst case
+*     would otherwise leave the replica drained forever.
+*
+* Out of scope for the v1 primitive (deferred follow-ups):
+*   - Per-container WORKDIR caching across multiple essential
+*     containers in the same task. The `docker inspect` call is
+*     ~10ms; not worth the cache invalidation surface for a path
+*     fired ~once per save.
+*   - SIGHUP / `docker exec`-driven in-process reload. Image-specific
+*     (uvicorn / nodemon / etc.). `docker restart` is the universal
+*     primitive; signal-based reload is a future opt-in if the
+*     per-restart latency proves prohibitive.
+*
+* @internal — wired only by the emulator's reload pathway.
+*/
+async function softReloadReplica(args) {
+	const { controller, oldReplicaIndex, newService, sourceDirToCopy } = args;
+	const logger = getLogger().child("ecs-service");
+	const instance = controller.runState.replicas[oldReplicaIndex];
+	if (!instance) throw new EcsServiceRunnerError(`softReloadReplica: no replica at index ${oldReplicaIndex} (replicas=${controller.runState.replicas.length}).`);
+	if (instance.shuttingDown) {
+		logger.warn(`Soft-reload of replica r${instance.index} (gen ${instance.generation}): retired by its own watcher mid-reload. Skipping; save again to re-boot it from scratch.`);
+		return;
+	}
+	const essentialContainers = newService.task.containers.filter((c) => c.essential);
+	const containersToCycle = essentialContainers.length > 0 ? essentialContainers : newService.task.containers.length > 0 ? [newService.task.containers[0]] : [];
+	if (containersToCycle.length === 0) throw new EcsServiceRunnerError(`softReloadReplica: service '${newService.serviceLogicalId}' has no containers to cycle.`);
+	const startedById = new Map(instance.state.startedContainers.map((c) => [c.name, c.id]));
+	const targets = [];
+	for (const container of containersToCycle) {
+		const id = startedById.get(container.name);
+		if (!id) throw new EcsServiceRunnerError(`softReloadReplica: replica r${instance.index} has no started container named '${container.name}' (started: ${[...startedById.keys()].join(", ") || "none"}).`);
+		targets.push({
+			name: container.name,
+			id
+		});
+	}
+	const controllerOptions = controller.options;
+	if (controllerOptions.discovery) {
+		for (const handle of instance.cloudMapHandles) try {
+			controllerOptions.discovery.registry.unregister(handle);
+		} catch {}
+		instance.cloudMapHandles = [];
+	}
+	unregisterReplicaFromFrontDoor(instance, controllerOptions.frontDoor);
+	instance.softReloadInProgress = true;
+	instance.softReloadGeneration = (instance.softReloadGeneration ?? 0) + 1;
+	try {
+		logger.info(`Soft-reloading replica r${instance.index} (gen ${instance.generation}): docker cp ${sourceDirToCopy} -> ${targets.length} essential container(s); restart.`);
+		for (const target of targets) {
+			let workdir;
+			try {
+				workdir = await dockerInspectWorkdirImpl(target.id) || "/";
+			} catch (err) {
+				throw new EcsServiceRunnerError(`softReloadReplica: docker inspect of container '${target.name}' (${target.id}) failed: ${err instanceof Error ? err.message : String(err)}. This replica is unregistered from Cloud Map + the front-door pool until the next save triggers another reload.`);
+			}
+			const workdirDest = workdir.endsWith("/") ? workdir : `${workdir}/`;
+			try {
+				await dockerCpImpl(`${sourceDirToCopy}/.`, `${target.id}:${workdirDest}`);
+			} catch (err) {
+				throw new EcsServiceRunnerError(`softReloadReplica: docker cp into '${target.name}' (${target.id}:${workdir}) failed: ${err instanceof Error ? err.message : String(err)}. This replica is unregistered from Cloud Map + the front-door pool until the next save triggers another reload.`);
+			}
+			try {
+				await dockerRestartImpl(target.id);
+			} catch (err) {
+				throw new EcsServiceRunnerError(`softReloadReplica: docker restart of '${target.name}' (${target.id}) failed: ${err instanceof Error ? err.message : String(err)}. This replica is unregistered from Cloud Map + the front-door pool until the next save triggers another reload.`);
+			}
+		}
+		await waitForReplicaTcpReady(newService, instance, {
+			timeoutMs: shadowReadyTimeoutMs,
+			intervalMs: shadowReadyIntervalMs,
+			label: `Soft-reloaded replica r${instance.index} (gen ${instance.generation})`
+		});
+		const ownerKeyGenSuffix = instance.generation > 0 ? `:g${instance.generation}` : "";
+		const ownerKeyPrefix = `${newService.serviceLogicalId}:r${instance.index}${ownerKeyGenSuffix}`;
+		if (controllerOptions.discovery) await publishReplicaToCloudMap(newService, instance, controllerOptions.discovery, ownerKeyPrefix);
+		if (controllerOptions.frontDoor) await publishReplicaToFrontDoor(newService, instance, controllerOptions.frontDoor, controllerOptions.taskOptions.containerHost, ownerKeyPrefix);
+		instance.lastDeployedAssetHash = pickEssentialAssetHash(newService);
+		logger.info(`Soft-reloaded replica r${instance.index} (gen ${instance.generation}): ${SOFT_RELOAD_COMPLETION_LOG_SUFFIX}`);
+	} finally {
+		instance.softReloadInProgress = false;
+	}
+}
+/**
+* Production `docker inspect --format {{.Config.WorkingDir}} <id>`
+* impl. Returns the container's runtime WORKDIR; empty string when
+* the Dockerfile didn't set one (caller treats empty as `/`, matching
+* Docker's runtime default).
+*
+* Extracted as a test-overridable function so the soft-reload
+* primitive's unit tests can assert the WORKDIR resolution branch
+* without standing up a real container.
+*/
+const defaultDockerInspectWorkdirImpl = async (containerId) => {
+	const { execFile } = await import("node:child_process");
+	const { promisify } = await import("node:util");
+	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	const { stdout } = await promisify(execFile)(getDockerCmd(), [
+		"inspect",
+		"--format",
+		"{{.Config.WorkingDir}}",
+		containerId
+	]);
+	return stdout.trim();
+};
+let dockerInspectWorkdirImpl = defaultDockerInspectWorkdirImpl;
+/**
+* Production `docker cp <src> <containerId>:<dst>` impl. The source
+* path's trailing `/.` ensures CONTENTS of the directory are copied
+* (not the directory itself); the caller is responsible for that
+* convention.
+*/
+const defaultDockerCpImpl = async (src, dst) => {
+	const { execFile } = await import("node:child_process");
+	const { promisify } = await import("node:util");
+	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	await promisify(execFile)(getDockerCmd(), [
+		"cp",
+		src,
+		dst
+	], { maxBuffer: 64 * 1024 * 1024 });
+};
+let dockerCpImpl = defaultDockerCpImpl;
+/**
+* Production `docker restart <id>` impl. Synchronous in docker's
+* sense — blocks until the container is up again (or fails).
+*/
+const defaultDockerRestartImpl = async (containerId) => {
+	const { execFile } = await import("node:child_process");
+	const { promisify } = await import("node:util");
+	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	await promisify(execFile)(getDockerCmd(), ["restart", containerId]);
+};
+let dockerRestartImpl = defaultDockerRestartImpl;
+/**
 * Phase 2 of issue #214 — disconnect every container of the dying
 * replica from the shared service network BEFORE `cleanupEcsRun`'s
 * `docker stop → docker rm` sequence. Docker's embedded DNS strips an
@@ -21470,13 +21707,14 @@ let dockerNetworkDisconnectImpl = defaultDockerNetworkDisconnectImpl;
 * injectable via {@link __setTcpProbeImpl} so the rolling-primitive
 * unit test can avoid any real TCP socket.
 */
-async function waitForReplicaTcpReady(service, shadow, opts) {
+async function waitForReplicaTcpReady(service, replica, opts) {
 	const logger = getLogger().child("ecs-service");
-	const networkName = shadow.state.network?.networkName;
+	const label = opts.label ?? `Shadow replica r${replica.index} (gen ${replica.generation})`;
+	const networkName = replica.state.network?.networkName;
 	if (!networkName) return;
 	const essential = service.task.containers.find((c) => c.essential) ?? service.task.containers[0];
 	if (!essential || essential.portMappings.length === 0) return;
-	const started = shadow.state.startedContainers.find((c) => c.name === essential.name);
+	const started = replica.state.startedContainers.find((c) => c.name === essential.name);
 	if (!started) return;
 	let ip;
 	try {
@@ -21484,7 +21722,7 @@ async function waitForReplicaTcpReady(service, shadow, opts) {
 		if (!resolved) return;
 		ip = resolved;
 	} catch (err) {
-		logger.warn(`Shadow replica r${shadow.index} (gen ${shadow.generation}): TCP-ready probe could not resolve docker IP: ${err instanceof Error ? err.message : String(err)}. Proceeding with swap.`);
+		logger.warn(`${label}: TCP-ready probe could not resolve docker IP: ${err instanceof Error ? err.message : String(err)}. Proceeding.`);
 		return;
 	}
 	const port = essential.portMappings[0].containerPort;
@@ -21493,14 +21731,14 @@ async function waitForReplicaTcpReady(service, shadow, opts) {
 	while (Date.now() < deadline) {
 		try {
 			await tcpProbeImpl(ip, port);
-			logger.debug(`Shadow replica r${shadow.index} (gen ${shadow.generation}): TCP probe ${ip}:${port} accepted; proceeding with swap.`);
+			logger.debug(`${label}: TCP probe ${ip}:${port} accepted.`);
 			return;
 		} catch (err) {
 			lastErr = err instanceof Error ? err.message : String(err);
 		}
 		await sleep(opts.intervalMs);
 	}
-	logger.warn(`Shadow replica r${shadow.index} (gen ${shadow.generation}): TCP probe ${ip}:${port} did not accept within ${opts.timeoutMs}ms (last: ${lastErr ?? "n/a"}). Swapping anyway — the new image is the user intent. Initial requests after the swap may 502 until the app finishes binding.`);
+	logger.warn(`${label}: TCP probe ${ip}:${port} did not accept within ${opts.timeoutMs}ms (last: ${lastErr ?? "n/a"}). Proceeding anyway — the new source is the user intent. Initial requests may 502 until the app finishes binding.`);
 }
 /**
 * Default TCP-connect probe used by {@link waitForReplicaTcpReady}.
@@ -21541,6 +21779,7 @@ async function watchReplica(service, options, instance, runState) {
 			await sleep(500);
 			continue;
 		}
+		const softReloadGenBeforeWait = instance.softReloadGeneration ?? 0;
 		let exitCode;
 		try {
 			exitCode = await waitForExitImpl(essentialId);
@@ -21549,6 +21788,12 @@ async function watchReplica(service, options, instance, runState) {
 			exitCode = -1;
 		}
 		if (instance.shuttingDown || runState.shuttingDown) return;
+		const softReloadHappenedMidWait = (instance.softReloadGeneration ?? 0) !== softReloadGenBeforeWait;
+		if (instance.softReloadInProgress || softReloadHappenedMidWait) {
+			while (instance.softReloadInProgress && !instance.shuttingDown && !runState.shuttingDown) await sleep(100);
+			if (instance.shuttingDown || runState.shuttingDown) return;
+			continue;
+		}
 		logger.warn(`Replica ${instance.index} essential container exited with code ${exitCode} (restartCount=${instance.restartCount}).`);
 		const willRestart = shouldRestart(exitCode, options.restartPolicy);
 		if (!willRestart || instance.restartCount === 0) await printExitedContainerLogs(instance.index, essentialId, logger);
@@ -21664,6 +21909,152 @@ function sleep(ms) {
 	return sleepImpl(ms);
 }
 
+//#endregion
+//#region src/local/source-change-classifier.ts
+/**
+* Dependency-manifest basenames recognized by the classifier. A change
+* to any of these forces a rebuild because the running container's
+* pre-built dependency layer is no longer in sync with the source.
+*
+* Coverage: the package managers commonly used inside a Lambda /
+* container image — Node (pnpm / npm / yarn), Python (pip / poetry /
+* pipenv), Ruby (bundler), Go (modules), Rust (cargo), Java / Kotlin
+* (Maven, Gradle). Adding a new ecosystem? Append its lockfile +
+* manifest here and add a classifier test row.
+*/
+const REBUILD_TRIGGER_BASENAMES = new Set([
+	"package.json",
+	"package-lock.json",
+	"pnpm-lock.yaml",
+	"yarn.lock",
+	"npm-shrinkwrap.json",
+	"requirements.txt",
+	"requirements-dev.txt",
+	"pyproject.toml",
+	"poetry.lock",
+	"Pipfile",
+	"Pipfile.lock",
+	"uv.lock",
+	"Gemfile",
+	"Gemfile.lock",
+	"go.mod",
+	"go.sum",
+	"Cargo.toml",
+	"Cargo.lock",
+	"pom.xml",
+	"build.gradle",
+	"build.gradle.kts",
+	"settings.gradle",
+	"settings.gradle.kts",
+	"Makefile",
+	"CMakeLists.txt"
+]);
+/**
+* Compiled-language source extensions that require a build step
+* inside `docker build` (typically a `RUN go build` / `cargo build` /
+* `mvn package` etc.). A copy of the source alone would leave the
+* running binary stale, so the user's intent must be a rebuild.
+*
+* Interpreted-language runtimes (Node — `.js` / `.mjs` / `.cjs` /
+* `.ts` when transpiled at runtime, Python — `.py`, Ruby — `.rb`,
+* shell — `.sh`) read source at process start, so a `docker cp` +
+* `docker restart` cycle picks them up. Those extensions are
+* NOT in this set.
+*/
+const COMPILED_LANGUAGE_EXTENSIONS = new Set([
+	".go",
+	".rs",
+	".java",
+	".kt",
+	".kts",
+	".scala",
+	".cs",
+	".swift",
+	".fs",
+	".fsx",
+	".c",
+	".cc",
+	".cpp",
+	".cxx",
+	".h",
+	".hpp",
+	".zig",
+	".ml",
+	".mli",
+	".elm",
+	".hs",
+	".dart"
+]);
+/**
+* Classify a single watcher firing into rebuild vs soft-reload. Pure
+* + synchronous. The caller (emulator's reload pathway) invokes this
+* once per target per firing AFTER `cdk synth` has run and the new
+* asset manifest is on disk.
+*
+* Branching:
+*   1. No asset context (image isn't a CDK asset, or asset lookup
+*      failed) → `rebuild`.
+*   2. The asset hash didn't change between old and new synths
+*      (`oldAssetHash === newAssetHash`, or `oldAssetHash` missing)
+*      → `rebuild`. Load-bearing guard for "user edited a CDK
+*      construct file (e.g. `lib/stack.ts`) that flipped the task
+*      spec but didn't touch the asset content". Soft-reload would
+*      `docker cp` identical files and `docker restart` the
+*      container with the OLD task spec (env / memory / mounts /
+*      added sidecars are set at `docker create` time, not on
+*      restart) — the user's intent would silently NOT apply.
+*      Forcing rebuild keeps Phase 1-3 semantics exactly for this
+*      case: the rolling primitive boots a shadow with the new task
+*      spec, the user sees their construct edit take effect.
+*   3. No changed paths (the watcher fired on a debounce flush with
+*      an empty pending set — shouldn't happen in practice, but
+*      defensive) → `rebuild`.
+*   4. Any changed path's basename matches the Dockerfile or a
+*      dependency manifest → `rebuild`.
+*   5. Any changed path's extension is a compiled-language source →
+*      `rebuild`.
+*   6. Else → `soft-reload`.
+*/
+function classifySourceChange(changedPaths, ctx) {
+	if (!ctx) return {
+		kind: "rebuild",
+		reason: "target image is not a CDK docker-image asset"
+	};
+	if (!ctx.oldAssetHash || ctx.oldAssetHash === ctx.newAssetHash) return {
+		kind: "rebuild",
+		reason: "asset hash unchanged across the synth (CDK construct edit or unrelated file) — task-spec changes need a fresh `docker create`, which only the rebuild path runs"
+	};
+	if (changedPaths.length === 0) return {
+		kind: "rebuild",
+		reason: "no changed paths reported (defensive default)"
+	};
+	for (const p of changedPaths) {
+		const basename = path.basename(p);
+		if (basename === ctx.dockerFile) return {
+			kind: "rebuild",
+			reason: `Dockerfile edit (${basename})`
+		};
+		if (basename.startsWith("Dockerfile.")) return {
+			kind: "rebuild",
+			reason: `Dockerfile.* edit (${basename})`
+		};
+		if (REBUILD_TRIGGER_BASENAMES.has(basename)) return {
+			kind: "rebuild",
+			reason: `dependency manifest edit (${basename})`
+		};
+		const ext = path.extname(p).toLowerCase();
+		if (COMPILED_LANGUAGE_EXTENSIONS.has(ext)) return {
+			kind: "rebuild",
+			reason: `compiled-language source edit (${basename}) — soft-reload would leave the built binary stale`
+		};
+	}
+	return {
+		kind: "soft-reload",
+		reason: `${changedPaths.length} source-only path(s) — skipping rebuild`,
+		newAssetSourceDir: ctx.newAssetSourceDir
+	};
+}
+
 //#endregion
 //#region src/local/cloud-map-registry.ts
 /**
@@ -22379,9 +22770,51 @@ function escapeRealmQuotes(realm) {
 }
 /** Reply 404 — an ALB listener with no matching rule and no default action. */
 function reply404(req, res, opts) {
-	writeError(res, 404, `No listener rule matched '${req.url ?? "/"}' on ${opts.label}, and the listener has no default action forwarding to a local target.`);
+	writeError(res, 404, buildNoRuleMatched404Body(req, opts));
 	return Promise.resolve();
 }
+/**
+* Build the no-rule-matched 404 body. When the call site supplied a
+* {@link StartFrontDoorServerOptions.rulesSummary}, the body lists every
+* ALB condition field that WAS evaluated (method, host, path) plus every
+* configured rule's priority + conditions + action target — so a user
+* whose request missed on, say, the Host header can spot the mismatch
+* without inspecting the synthesized template. Header conditions are
+* NOT spelled out in the evaluated section (too noisy) but ARE listed
+* in each rule's condition row when the rule constrains them. Without a
+* summary the body falls back to the original path-only shape (preserves
+* the behavior for direct callers that wire the proxy with just a
+* `selectPool` / `selectTarget`).
+*/
+function buildNoRuleMatched404Body(req, opts) {
+	const requestPath = req.url ?? "/";
+	const summary = opts.rulesSummary;
+	if (!summary) return `No listener rule matched '${requestPath}' on ${opts.label}, and the listener has no default action forwarding to a local target.`;
+	const rawHost = req.headers.host;
+	const hostValue = Array.isArray(rawHost) ? rawHost[0] : rawHost;
+	const lines = [];
+	lines.push(`No listener rule matched the request on ${opts.label}, and the listener has no default action forwarding to a local target.`);
+	lines.push("");
+	lines.push("  Evaluated:");
+	lines.push(`    Method:  ${req.method ?? "(unknown)"}`);
+	lines.push(`    Host:    ${hostValue ?? "(no Host header)"}`);
+	lines.push(`    Path:    ${requestPath}`);
+	lines.push("");
+	if (summary.length === 0) lines.push("  Listener has 0 rule(s).");
+	else {
+		lines.push(`  Listener has ${summary.length} rule(s):`);
+		const ordered = [...summary].sort((a, b) => a.priority - b.priority);
+		for (const rule of ordered) {
+			const conditions = rule.conditions.length === 0 ? "(no condition)" : rule.conditions.map(formatRuleConditionSummary).join(" AND ");
+			lines.push(`    [priority=${rule.priority}] ${conditions}  -> ${rule.action}`);
+		}
+	}
+	return lines.join("\n");
+}
+/** Format one condition row of a {@link FrontDoorRuleSummary} for the 404 body. */
+function formatRuleConditionSummary(c) {
+	return `${c.field} in [${c.values.join(", ")}]`;
+}
 function handlePoolRequest(req, res, pool, opts) {
 	return new Promise((resolve) => {
 		const endpoint = pool.next();
@@ -23319,9 +23752,9 @@ function materializeInlineCode(handler, source, fileExtension) {
 	const lastDot = handler.lastIndexOf(".");
 	if (lastDot <= 0) throw new Error(`Handler '${handler}' is malformed: expected '<modulePath>.<exportName>'.`);
 	const modulePath = handler.substring(0, lastDot);
-	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-alb-lambda-`));
-	const filePath = path.join(dir, `${modulePath}${fileExtension}`);
-	mkdirSync(path.dirname(filePath), { recursive: true });
+	const dir = mkdtempSync(path$1.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-alb-lambda-`));
+	const filePath = path$1.join(dir, `${modulePath}${fileExtension}`);
+	mkdirSync(path$1.dirname(filePath), { recursive: true });
 	writeFileSync(filePath, source, "utf-8");
 	return dir;
 }
@@ -23353,7 +23786,7 @@ async function resolveContainerImagePlan(lambda, opts) {
 	let imageRef;
 	let localBuilt = false;
 	if (manifestPath) {
-		const cdkOutDir = path.dirname(manifestPath);
+		const cdkOutDir = path$1.dirname(manifestPath);
 		const manifest = await new AssetManifestLoader().loadManifest(cdkOutDir, lambda.stack.stackName);
 		const entry = manifest ? getDockerImageBySourceHash(manifest, lambda.imageUri) : void 0;
 		if (entry) {
@@ -23719,8 +24152,8 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 				paths: [watchRoot],
 				ignored,
 				shouldTrigger,
-				onChange: () => {
-					logger.info("Detected source change; reloading service(s)...");
+				onChange: (changedPaths) => {
+					logger.info(`Detected source change (${changedPaths.length} path(s)); reloading service(s)...`);
 					reloadChain = reloadChain.then(() => reloadAllServices({
 						perTarget,
 						synthesizer,
@@ -23734,6 +24167,7 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 						extraStateProviders,
 						profileCredsFile,
 						frontDoorByService,
+						changedPaths,
 						logger
 					})).catch((err) => {
 						logger.error(`reloadAllServices threw: ${err instanceof Error ? err.message : String(err)}`);
@@ -23752,11 +24186,22 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 	}
 }
 /**
-* Phase 2 of issue #214 — multi-replica rolling reload cycle for
-* `cdkl start-service --watch`. Mirrors start-api's `reloadAllServers`
-* shape but per-ECS-service, replacing Phase 1's "tear single replica
-* down, boot fresh" sequence with a per-replica rolling loop so the
-* service stays available end-to-end:
+* Phase 2 + Phase 4 of issue #214 — multi-replica reload cycle for
+* `cdkl start-service --watch` (Phase 2) and `cdkl start-alb --watch`
+* (Phase 3 wires the same loop). Mirrors start-api's `reloadAllServers`
+* shape but per-ECS-service. Per-target verdict from
+* {@link classifySourceChange} (Phase 4) picks the per-replica action:
+*
+*   - `'soft-reload'` → {@link softReloadReplica} runs `docker cp`
+*     + `docker restart` against the live replica. No `docker build`,
+*     no shadow boot, no Cloud Map / front-door pool swap — the
+*     container's IP + host port are preserved across the restart, so
+*     existing registrations stay valid. Fast path (~sub-second per
+*     replica for typical interpreted-language handlers).
+*   - `'rebuild'` → {@link rollServiceReplica}, the Phase 1-3 path,
+*     replacing Phase 1's "tear single replica down, boot fresh"
+*     sequence with a per-replica rolling loop so the service stays
+*     available end-to-end:
 *
 *   1. Re-runs `synthesizer.synthesize(synthOpts)` once (failure → warn
 *      + keep every replica serving).
@@ -23791,7 +24236,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, logger } = args;
+	const { perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, changedPaths, logger } = args;
 	let stacks;
 	try {
 		({stacks} = await synthesizer.synthesize(synthOpts));
@@ -23808,6 +24253,8 @@ async function reloadAllServices(args) {
 		cloudMapIndexByStack.set(stack.stackName, index);
 		for (const w of index.warnings) logger.warn(w);
 	}
+	const cdkOutDir = options.output;
+	const assetLoader = new AssetManifestLoader();
 	for (const pt of perTarget) {
 		const newBoot = newBootByTarget.get(pt.boot.target);
 		if (!newBoot) {
@@ -23819,6 +24266,27 @@ async function reloadAllServices(args) {
 			logger.warn(`Reload: target '${pt.boot.target}' has no live controller (previous boot likely failed); skipping roll. \`^C\` and re-run start-service to recover.`);
 			continue;
 		}
+		let verdict = {
+			kind: "rebuild",
+			reason: "classifier not consulted"
+		};
+		try {
+			verdict = classifySourceChange(changedPaths, await loadAssetContextForTarget({
+				target: newBoot.target,
+				controller,
+				stacks,
+				cdkOutDir,
+				assetLoader,
+				logger
+			}));
+			logger.info(`Reload of '${newBoot.target}': verdict=${verdict.kind} (${verdict.reason}).`);
+		} catch (err) {
+			logger.warn(`Reload of '${newBoot.target}': classifier context unavailable (${err instanceof Error ? err.message : String(err)}); falling back to rebuild.`);
+			verdict = {
+				kind: "rebuild",
+				reason: "classifier context unavailable; falling back to rebuild"
+			};
+		}
 		await rollOneTarget({
 			controller,
 			newBoot,
@@ -23830,12 +24298,73 @@ async function reloadAllServices(args) {
 			profileCredsFile,
 			frontDoorPools: frontDoorByService.get(newBoot.target),
 			suppressLoadBalancerWarning: strategy.suppressLoadBalancerWarning === true,
+			verdict,
 			logger
 		});
 	}
 	logger.info("Reload complete.");
 }
 /**
+* Phase 4 of issue #214 — load the per-target asset context the
+* source-change classifier consumes. Resolves the target's docker-image
+* asset hash via the freshly-synthed `<stackName>.assets.json` and
+* derives the staged source directory + Dockerfile basename.
+*
+* Returns `undefined` (and logs at debug) when:
+*   - The target's image isn't a CDK docker-image asset (ECR / public
+*     registry pin). The classifier treats `undefined` as `rebuild`
+*     because there's no local source tree to copy.
+*   - The asset manifest can't be loaded (stack not synthed yet, file
+*     missing). Same treatment — defensive default to `rebuild`.
+*   - The asset hash isn't in the manifest's `dockerImages`. Same.
+*
+* Throws on a malformed manifest (parse failure surfaced via
+* {@link AssetManifestLoader}) so the caller can fall back to rebuild
+* with a warn line that explains why the classifier couldn't run.
+*/
+/**
+* @internal — exported for unit tests of the fall-through branches
+* (the 6 `return undefined` paths + the catch arm on
+* `resolveEcsServiceTarget` throw). Not part of the semver-covered
+* public surface; the only legitimate caller is `reloadAllServices`
+* inside this file.
+*/
+async function loadAssetContextForTarget(args) {
+	const { target, controller, stacks, cdkOutDir, assetLoader, logger } = args;
+	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+	if (!candidate) return void 0;
+	let newService;
+	try {
+		newService = resolveEcsServiceTarget(target, stacks, void 0, { suppressLoadBalancerWarning: true });
+	} catch (err) {
+		logger.debug(`loadAssetContextForTarget: target '${target}' could not be re-resolved against the new stacks: ${err instanceof Error ? err.message : String(err)}. Classifier will see no asset context (rebuild).`);
+		return;
+	}
+	const essential = newService.task.containers.find((c) => c.essential) ?? newService.task.containers[0];
+	if (!essential) return void 0;
+	if (essential.image.kind !== "cdk-asset" || !essential.image.assetHash) return;
+	const newAssetHash = essential.image.assetHash;
+	const manifest = await assetLoader.loadManifest(cdkOutDir, candidate.stackName);
+	if (!manifest) return void 0;
+	const newDockerImage = manifest.dockerImages?.[newAssetHash];
+	if (!newDockerImage) return void 0;
+	if (!newDockerImage.source.directory) return;
+	const newAssetSourceDir = path.resolve(cdkOutDir, newDockerImage.source.directory);
+	let oldAssetHash;
+	const liveReplica = controller.runState.replicas.find((r) => !r.shuttingDown);
+	if (liveReplica?.lastDeployedAssetHash !== void 0) oldAssetHash = liveReplica.lastDeployedAssetHash;
+	else {
+		const oldEssential = controller.service.task.containers.find((c) => c.essential) ?? controller.service.task.containers[0];
+		if (oldEssential?.image.kind === "cdk-asset") oldAssetHash = oldEssential.image.assetHash;
+	}
+	return {
+		...oldAssetHash !== void 0 && { oldAssetHash },
+		newAssetHash,
+		newAssetSourceDir,
+		dockerFile: path.basename(newDockerImage.source.dockerFile ?? "Dockerfile")
+	};
+}
+/**
 * Phase 2 of issue #214 — roll every replica of one target through the
 * new task descriptor sequentially. Extracted from {@link reloadAllServices}
 * so the per-target try/catch logic (synth-failure / resolve-failure /
@@ -23846,7 +24375,7 @@ async function reloadAllServices(args) {
 * even when the resolve / roll throws.
 */
 async function rollOneTarget(args) {
-	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, logger } = args;
+	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, verdict, logger } = args;
 	const candidate = pickCandidateStack(parseEcsTarget(newBoot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 	try {
@@ -23865,7 +24394,8 @@ async function rollOneTarget(args) {
 			return;
 		}
 		if (newService.desiredCount !== oldReplicas.length) logger.warn(`Reload of '${newBoot.target}': service DesiredCount=${newService.desiredCount} does not match the ${oldReplicas.length} live replica(s); rolling existing replicas only — scale changes during --watch are not yet supported. \`^C\` and re-run start-service to apply the new replica count.`);
-		logger.info(`Reload of '${newBoot.target}': rolling ${oldReplicas.length} replica(s) one at a time (start new shadow → swap registrations → stop old).`);
+		if (verdict.kind === "soft-reload") logger.info(`Reload of '${newBoot.target}': soft-reloading ${oldReplicas.length} replica(s) one at a time (docker cp source → docker restart → TCP-ready probe; no rebuild).`);
+		else logger.info(`Reload of '${newBoot.target}': rolling ${oldReplicas.length} replica(s) one at a time (start new shadow → swap registrations → stop old).`);
 		for (const oldInstance of oldReplicas) {
 			const idx = controller.runState.replicas.indexOf(oldInstance);
 			if (idx === -1) {
@@ -23873,7 +24403,13 @@ async function rollOneTarget(args) {
 				continue;
 			}
 			try {
-				await rollServiceReplica({
+				if (verdict.kind === "soft-reload") await softReloadReplica({
+					controller,
+					oldReplicaIndex: idx,
+					newService,
+					sourceDirToCopy: verdict.newAssetSourceDir
+				});
+				else await rollServiceReplica({
 					controller,
 					oldReplicaIndex: idx,
 					newService,
@@ -24116,6 +24652,7 @@ async function buildFrontDoor(plan, options, logger) {
 			const tls = listener.protocol === "HTTPS" && wantTls ? tlsMaterials : void 0;
 			const forwardedProto = listener.protocol === "HTTPS" ? "https" : "http";
 			const degradedHttps = listener.protocol === "HTTPS" && !wantTls;
+			const rulesSummary = listener.rules.map(buildRuleSummary);
 			const server = await startFrontDoorServer({
 				route,
 				port: listener.hostPort,
@@ -24123,6 +24660,7 @@ async function buildFrontDoor(plan, options, logger) {
 				listenerPort: listener.listenerPort,
 				label: `listener port ${listener.listenerPort}`,
 				forwardedProto,
+				rulesSummary,
 				...tls ? { tls } : {}
 			});
 			servers.push(server);
@@ -24187,6 +24725,66 @@ function describeTarget(t) {
 function describeTargetShort(t) {
 	return t.kind === "lambda" ? `Lambda ${t.lambda.logicalId}` : t.serviceTarget;
 }
+/**
+* Build the per-rule summary the front-door surfaces in its no-rule-matched
+* 404 body (issue #228). One condition row per constrained ALB field, plus a
+* pre-formatted action target. Distinct from {@link describeConditions} /
+* {@link describeAction} (which produce a single-line boot-banner string) —
+* the 404 body needs the rule decomposed into its constituent fields so the
+* formatter can render `field in [values]` rows.
+*/
+function buildRuleSummary(rule) {
+	const conditions = [];
+	if (rule.pathPatterns.length > 0) conditions.push({
+		field: "path-pattern",
+		values: rule.pathPatterns
+	});
+	if (rule.hostPatterns.length > 0) conditions.push({
+		field: "host-header",
+		values: rule.hostPatterns
+	});
+	for (const h of rule.httpHeaderConditions) conditions.push({
+		field: "http-header",
+		values: [`${h.name}: ${h.values.join(", ")}`]
+	});
+	if (rule.httpRequestMethods.length > 0) conditions.push({
+		field: "http-request-method",
+		values: rule.httpRequestMethods
+	});
+	if (rule.queryStringConditions.length > 0) conditions.push({
+		field: "query-string",
+		values: rule.queryStringConditions.map(describeQueryStringCondition)
+	});
+	if (rule.sourceIpCidrs.length > 0) conditions.push({
+		field: "source-ip",
+		values: rule.sourceIpCidrs
+	});
+	return {
+		priority: rule.priority,
+		conditions,
+		action: describeRuleActionForSummary(rule.action)
+	};
+}
+/**
+* Describe a planned action for the no-rule-matched 404 body (issue #228).
+* Uses the `<ECS: ...>` / `<Lambda: ...>` shape the issue body proposes so a
+* user can read each rule's target at a glance.
+*/
+function describeRuleActionForSummary(action) {
+	if (action.kind === "redirect") return `redirect ${action.statusCode}`;
+	if (action.kind === "fixed-response") return `fixed-response ${action.statusCode}`;
+	if (action.targets.length === 1) return `forward to ${describeForwardTargetForSummary(action.targets[0])}`;
+	return `forward weighted [${action.targets.map((t) => `${describeForwardTargetForSummary(t)}@${t.weight}`).join(", ")}]`;
+}
+/**
+* One forward target named the way the 404 body shows it: `<ECS: Service>` or
+* `<Lambda: LogicalId>` — distinct from the boot-banner format (which also
+* prints the container / port / round-robin hint) so the 404 body stays
+* scannable.
+*/
+function describeForwardTargetForSummary(t) {
+	return t.kind === "lambda" ? `<Lambda: ${t.lambda.logicalId}>` : `<ECS: ${t.serviceTarget}>`;
+}
 async function resolvePlaceholderAccount(arn, region) {
 	if (!arn.includes("${AWS::AccountId}")) return arn;
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
@@ -24458,7 +25056,7 @@ function createLocalStartServiceCommand(opts = {}) {
 * for that contract to live.
 */
 function addStartServiceSpecificOptions(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 rolling deploy when the CDK source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). Each replica is rolled one at a time — 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 — 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));
+	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));
 }
 
 //#endregion
@@ -25311,7 +25909,7 @@ function createLocalStartAlbCommand(opts = {}) {
 * clusters. Chainable: returns `cmd`.
 */
 function addAlbSpecificOptions(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 rolling deploy 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). Each replica is rolled one at a time — 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 — 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));
+	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));
 }
 
 //#endregion
@@ -25407,5 +26005,5 @@ function addListSpecificOptions(cmd) {
 }
 
 //#endregion
-export { buildHttpApiV2Event as $, resolveRuntimeFileExtension as $t, createWatchPredicates as A, AGENTCORE_HTTP_PROTOCOL as An, A2A_PATH as At, readMtlsMaterialsFromDisk as B, LocalInvokeBuildError as Bn, invokeAgentCore as Bt, getContainerNetworkIp as C, discoverWebSocketApisOrThrow as Cn, applyCorsResponseHeaders as Ct, createLocalInvokeAgentCoreCommand as D, resolveLambdaArnIntrinsic as Dn, matchPreflight as Dt, addInvokeAgentCoreSpecificOptions as E, pickRefLogicalId as En, isFunctionUrlOacFronted as Et, buildStageMap as F, resolveAgentCoreTarget as Fn, mcpInvokeOnce as Ft, buildMethodArn as G, computeCodeImageTag as Gt, resolveSelectionExpression as H, downloadAndExtractS3Bundle as Ht, availableApiIdentifiers as I, derivePseudoParametersFromRegion as In, parseSseForJsonRpc as It, invokeRequestAuthorizer as J, addInvokeSpecificOptions as Jt, computeRequestIdentityHash as K, renderCodeDockerfile as Kt, filterRoutesByApiIdentifier as L, formatStateRemedy as Ln, AGENTCORE_SIGV4_SERVICE as Lt, createAuthorizerCache as M, AGENTCORE_RUNTIME_TYPE as Mn, MCP_CONTAINER_PORT as Mt, createFileWatcher as N, AgentCoreResolutionError as Nn, MCP_PATH as Nt, addStartApiSpecificOptions as O, AGENTCORE_A2A_PROTOCOL as On, invokeAgentCoreWs as Ot, attachStageContext as P, pickAgentCoreCandidateStack as Pn, MCP_PROTOCOL_VERSION as Pt, applyAuthorizerOverlay as Q, resolveRuntimeCodeMountPath as Qt, filterRoutesByApiIdentifiers as R, substituteImagePlaceholders as Rn, signAgentCoreInvocation as Rt, CloudMapRegistry as S, discoverWebSocketApis as Sn, attachAuthorizers as St, createLocalRunTaskCommand as T, discoverRoutes as Tn, buildCorsConfigFromCloudFrontChain as Tt, resolveServiceIntegrationParameters as U, SUPPORTED_CODE_RUNTIMES as Ut, startApiServer as V, waitForAgentCorePing as Vt, defaultCredentialsLoader as W, buildAgentCoreCodeImage as Wt, matchRoute as X, architectureToPlatform as Xt, invokeTokenAuthorizer as Y, createLocalInvokeCommand as Yt, translateLambdaResponse as Z, buildContainerImage as Zt, parseMaxTasks as _, resolveSsmParameters as _n, buildJwksUrlFromIssuer as _t, albStrategy as a, substituteEnvVarsFromStateAsync as an, VtlEvaluationError as at, runEcsServiceEmulator as b, countTargets as bn, verifyJwtAuthorizer as bt, resolveAlbTarget as c, LocalStateSourceError as cn, bufferToBody as ct, addStartServiceSpecificOptions as d, rejectExplicitCfnStackWithMultipleStacks as dn, handleConnectionsRequest as dt, resolveRuntimeImage as en, buildRestV1Event as et, createLocalStartServiceCommand as f, resolveCfnFallbackRegion as fn, parseConnectionsPath as ft, buildEcsImageResolutionContext as g, collectSsmParameterRefs as gn, buildCognitoJwksUrl as gt, addCommonEcsServiceOptions as h, CfnLocalStateProvider as hn, buildMessageEvent as ht, addAlbSpecificOptions as i, substituteEnvVarsFromState as in, tryParseStatus as it, resolveApiTargetSubset as j, AGENTCORE_MCP_PROTOCOL as jn, a2aInvokeOnce as jt, createLocalStartApiCommand as k, AGENTCORE_AGUI_PROTOCOL as kn, A2A_CONTAINER_PORT as kt, isApplicationLoadBalancer as l, createLocalStateProvider as ln, ConnectionRegistry as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, resolveCfnStackName as mn, buildDisconnectEvent as mt, createLocalListCommand as n, substituteAgainstState as nn, pickResponseTemplate as nt, createLocalStartAlbCommand as o, resolveEnvVars as on, HOST_GATEWAY_MIN_VERSION as ot, serviceStrategy as p, resolveCfnRegion as pn, buildConnectEvent as pt, evaluateCachedLambdaPolicy as q, toCmdArgv as qt, formatTargetListing as r, substituteAgainstStateAsync as rn, selectIntegrationResponse as rt, parseLbPortOverrides as s, materializeLayerFromArn as sn, probeHostGatewaySupport as st, addListSpecificOptions as t, EcsTaskResolutionError as tn, evaluateResponseParameters as tt, resolveAlbFrontDoor as u, isCfnFlagPresent as un, buildMgmtEndpointEnvUrl as ut, parseRestartPolicy as v, resolveWatchConfig as vn, createJwksCache as vt, addRunTaskSpecificOptions as w, parseSelectionExpressionPath as wn, buildCorsConfigByApiId as wt, buildCloudMapIndex as x, listTargets as xn, verifyJwtViaDiscovery as xt, resolveSharedSidecarCredentials as y, resolveSingleTarget as yn, verifyCognitoJwt as yt, groupRoutesByServer as z, tryResolveImageFnJoin as zn, AGENTCORE_SESSION_ID_HEADER as zt };
-//# sourceMappingURL=local-list-BFtuOXLq.js.map
+export { translateLambdaResponse as $, buildContainerImage as $t, addStartApiSpecificOptions as A, AGENTCORE_A2A_PROTOCOL as An, invokeAgentCoreWs as At, filterRoutesByApiIdentifiers as B, substituteImagePlaceholders as Bn, signAgentCoreInvocation as Bt, classifySourceChange as C, listTargets as Cn, verifyJwtViaDiscovery as Ct, createLocalRunTaskCommand as D, discoverRoutes as Dn, buildCorsConfigFromCloudFrontChain as Dt, addRunTaskSpecificOptions as E, parseSelectionExpressionPath as En, buildCorsConfigByApiId as Et, createFileWatcher as F, AgentCoreResolutionError as Fn, MCP_PATH as Ft, resolveServiceIntegrationParameters as G, SUPPORTED_CODE_RUNTIMES as Gt, readMtlsMaterialsFromDisk as H, LocalInvokeBuildError as Hn, invokeAgentCore as Ht, attachStageContext as I, pickAgentCoreCandidateStack as In, MCP_PROTOCOL_VERSION as It, computeRequestIdentityHash as J, renderCodeDockerfile as Jt, defaultCredentialsLoader as K, buildAgentCoreCodeImage as Kt, buildStageMap as L, resolveAgentCoreTarget as Ln, mcpInvokeOnce as Lt, createWatchPredicates as M, AGENTCORE_HTTP_PROTOCOL as Mn, A2A_PATH as Mt, resolveApiTargetSubset as N, AGENTCORE_MCP_PROTOCOL as Nn, a2aInvokeOnce as Nt, addInvokeAgentCoreSpecificOptions as O, pickRefLogicalId as On, isFunctionUrlOacFronted as Ot, createAuthorizerCache as P, AGENTCORE_RUNTIME_TYPE as Pn, MCP_CONTAINER_PORT as Pt, matchRoute as Q, architectureToPlatform as Qt, availableApiIdentifiers as R, derivePseudoParametersFromRegion as Rn, parseSseForJsonRpc as Rt, CloudMapRegistry as S, countTargets as Sn, verifyJwtAuthorizer as St, getContainerNetworkIp as T, discoverWebSocketApisOrThrow as Tn, applyCorsResponseHeaders as Tt, startApiServer as U, waitForAgentCorePing as Ut, groupRoutesByServer as V, tryResolveImageFnJoin as Vn, AGENTCORE_SESSION_ID_HEADER as Vt, resolveSelectionExpression as W, downloadAndExtractS3Bundle as Wt, invokeRequestAuthorizer as X, addInvokeSpecificOptions as Xt, evaluateCachedLambdaPolicy as Y, toCmdArgv as Yt, invokeTokenAuthorizer as Z, createLocalInvokeCommand as Zt, parseMaxTasks as _, CfnLocalStateProvider as _n, buildMessageEvent as _t, albStrategy as a, substituteAgainstStateAsync as an, selectIntegrationResponse as at, runEcsServiceEmulator as b, resolveWatchConfig as bn, createJwksCache as bt, resolveAlbTarget as c, resolveEnvVars as cn, HOST_GATEWAY_MIN_VERSION as ct, addStartServiceSpecificOptions as d, createLocalStateProvider as dn, ConnectionRegistry as dt, resolveRuntimeCodeMountPath as en, applyAuthorizerOverlay as et, createLocalStartServiceCommand as f, isCfnFlagPresent as fn, buildMgmtEndpointEnvUrl as ft, buildEcsImageResolutionContext as g, resolveCfnStackName as gn, buildDisconnectEvent as gt, addCommonEcsServiceOptions as h, resolveCfnRegion as hn, buildConnectEvent as ht, addAlbSpecificOptions as i, substituteAgainstState as in, pickResponseTemplate as it, createLocalStartApiCommand as j, AGENTCORE_AGUI_PROTOCOL as jn, A2A_CONTAINER_PORT as jt, createLocalInvokeAgentCoreCommand as k, resolveLambdaArnIntrinsic as kn, matchPreflight as kt, isApplicationLoadBalancer as l, materializeLayerFromArn as ln, probeHostGatewaySupport as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, resolveCfnFallbackRegion as mn, parseConnectionsPath as mt, createLocalListCommand as n, resolveRuntimeImage as nn, buildRestV1Event as nt, createLocalStartAlbCommand as o, substituteEnvVarsFromState as on, tryParseStatus as ot, serviceStrategy as p, rejectExplicitCfnStackWithMultipleStacks as pn, handleConnectionsRequest as pt, buildMethodArn as q, computeCodeImageTag as qt, formatTargetListing as r, EcsTaskResolutionError as rn, evaluateResponseParameters as rt, parseLbPortOverrides as s, substituteEnvVarsFromStateAsync as sn, VtlEvaluationError as st, addListSpecificOptions as t, resolveRuntimeFileExtension as tn, buildHttpApiV2Event as tt, resolveAlbFrontDoor as u, LocalStateSourceError as un, bufferToBody as ut, parseRestartPolicy as v, collectSsmParameterRefs as vn, buildCognitoJwksUrl as vt, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as w, discoverWebSocketApis as wn, attachAuthorizers as wt, buildCloudMapIndex as x, resolveSingleTarget as xn, verifyCognitoJwt as xt, resolveSharedSidecarCredentials as y, resolveSsmParameters as yn, buildJwksUrlFromIssuer as yt, filterRoutesByApiIdentifier as z, formatStateRemedy as zn, AGENTCORE_SIGV4_SERVICE as zt };
+//# sourceMappingURL=local-list-C-wXKogn.js.map