cdk-local 0.162.1 → 0.163.1

package/dist/{local-studio-D8eIrFzx.js → local-studio-CFf6tO1e.js}

@@ -1,7 +1,7 @@
 import { a as displayIdent, c as getEmbedConfig, i as STACK_REF_MAX_CODE_POINTS, o as displayStackName, s as displayToolOutput, t as getLogger, u as setEmbedConfig } from "./logger-Co5XVwco.js";
-import { C as effectiveLoopbackPorts, G as isWildcardHostname, H as proxyAwareFetch, J as hostFromAuthority, K as formatAuthority, P as resolveHostDefaultCredentials, W as isLoopbackHostname, b as awsEmulatorEnvName, d as workloadStsClientConfig, l as warnWorkloadCredentialsStripped, n as accountLookupStsClientConfig, q as formatHostForAuthority, r as applyWorkloadEnvCredentials, u as workloadClientConfig, v as activateWorkloadAwsWiring, w as getActiveWorkloadAwsWiring, y as applyWorkloadAwsWiringToEnv, z as buildProxyClientConfig } from "./workload-identity-ITM3p2Ed.js";
+import { $ as buildProxyClientConfig, C as effectiveLoopbackPorts, F as resolveHostDefaultCredentials, G as createMixedModeStateProvider, Q as awsEndpointOverrideClientConfig, at as isWildcardHostname, b as awsEmulatorEnvName, ct as hostFromAuthority, d as workloadStsClientConfig, it as isLoopbackHostname, l as warnWorkloadCredentialsStripped, n as accountLookupStsClientConfig, nt as proxyAwareFetch, ot as formatAuthority, r as applyWorkloadEnvCredentials, st as formatHostForAuthority, u as workloadClientConfig, v as activateWorkloadAwsWiring, w as getActiveWorkloadAwsWiring, y as applyWorkloadAwsWiringToEnv } from "./workload-identity-D5zkhVcF.js";
 import { c as clampErrorName, d as flattenToOneLine, f as isAwsServiceException, l as describeAwsFailureForWarn, m as stringifyThrown, o as renderAssemblyPathEscape, p as sanitizeServiceExceptionMessage, r as displayUntrustedValue, s as resolveAssemblyPath, t as absoluteAssemblyPathEscape, u as describeCredentialLoadFailure } from "./assembly-path-R96uhMm1.js";
-import { $ as buildStsClientConfig, A as buildDockerImage, B as InteractiveTtyRequiredError, D as isImageInLocalCache, E as warnIfEmulatedPlatform, F as derivePseudoParametersFromRegion, G as withErrorHandling, H as LocalStartServiceError, I as formatStateRemedy, J as applyRoleArnIfSet, K as defineOwnKey, L as substituteImagePlaceholders, M as describeExitWithoutArgv, N as parseEcrRegistryHost, O as parseEcrUri, P as derivePartitionAndUrlSuffix, Q as refusedRoleArnMessage, R as tryResolveImageFnJoin, T as buildContainerImage, U as RouteDiscoveryError, V as LocalInvokeBuildError, W as TargetSelectionCancelledError, X as describeRejectedRoleArn, Y as assumeRoleCredentials, Z as isIamRoleArn, a as describeRefusedSensitiveEnvKeys, c as execEnvForSecrets, d as rememberForwardedPorts, et as resolveProfileCredentials, f as removeContainer, h as streamLogs, i as attachLoopbackForwarder, j as resolveAssetSourcePath, k as pullEcrImage, l as pickFreePort, m as startNamespaceOwnerForwarder, n as SENSITIVE_ENV_KEYS, p as runDetached, q as AssumeRoleFailure, r as appendEnvFlags, s as ensureDockerAvailable, t as DockerRunnerError, u as pullImage, w as architectureToPlatform, z as CdkLocalError } from "./docker-runner-CLlVjU7l.js";
+import { $ as buildStsClientConfig, A as buildDockerImage, B as InteractiveTtyRequiredError, D as isImageInLocalCache, E as warnIfEmulatedPlatform, F as derivePseudoParametersFromRegion, G as withErrorHandling, H as LocalStartServiceError, I as formatStateRemedy, J as applyRoleArnIfSet, K as defineOwnKey, L as substituteImagePlaceholders, M as describeExitWithoutArgv, N as parseEcrRegistryHost, O as parseEcrUri, P as derivePartitionAndUrlSuffix, Q as refusedRoleArnMessage, R as tryResolveImageFnJoin, T as buildContainerImage, U as RouteDiscoveryError, V as LocalInvokeBuildError, W as TargetSelectionCancelledError, X as describeRejectedRoleArn, Y as assumeRoleCredentials, Z as isIamRoleArn, a as describeRefusedSensitiveEnvKeys, c as execEnvForSecrets, d as rememberForwardedPorts, et as resolveProfileCredentials, f as removeContainer, h as streamLogs, i as attachLoopbackForwarder, j as resolveAssetSourcePath, k as pullEcrImage, l as pickFreePort, m as startNamespaceOwnerForwarder, n as SENSITIVE_ENV_KEYS, p as runDetached, q as AssumeRoleFailure, r as appendEnvFlags, s as ensureDockerAvailable, t as DockerRunnerError, u as pullImage, w as architectureToPlatform, z as CdkLocalError } from "./docker-runner-DzPTb4Ai.js";
 import { a as isDockerClientEnvKey, c as runDockerStreaming, i as getDockerCmd, n as finchSecretArgvRefusal, o as isMalformedEnvKey, u as warnFinchArgvExposure } from "./docker-cmd-Cjg3jGYF.js";
 import { chmodSync, cpSync, createWriteStream, existsSync, lstatSync, mkdirSync, mkdtempSync, promises, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { Command, InvalidArgumentError, Option } from "commander";
@@ -2983,7 +2983,7 @@ async function resolveSsmParameters(client, refs, label) {
 //#endregion
 //#region src/local/cfn-local-state-provider.ts
 var CfnLocalStateProvider = class {
-	label = "--from-cfn-stack";
+	label;
 	cfnStackName;
 	region;
 	client;
@@ -2991,18 +2991,25 @@ var CfnLocalStateProvider = class {
 	ssmClient;
 	agentCoreControlClient;
 	clientOptions;
+	endpointOverride;
 	disposed = false;
 	lastLoadError;
 	constructor(opts) {
 		this.cfnStackName = opts.cfnStackName;
 		this.region = opts.region;
 		this.clientOptions = { region: opts.region };
-		if (opts.profile !== void 0) this.clientOptions.profile = opts.profile;
+		this.endpointOverride = opts.endpointOverride;
+		this.label = opts.label ?? "--from-cfn-stack";
+		if (opts.profile !== void 0 && !opts.endpointOverride) this.clientOptions.profile = opts.profile;
+	}
+	overrideClientConfig() {
+		return this.endpointOverride ? awsEndpointOverrideClientConfig(this.endpointOverride) : {};
 	}
 	getClient() {
 		if (this.disposed) throw new Error("CfnLocalStateProvider used after dispose()");
 		if (!this.client) this.client = new CloudFormationClient({
 			...workloadClientConfig({ profile: this.clientOptions.profile }),
+			...this.overrideClientConfig(),
 			region: this.region,
 			...this.clientOptions.profile !== void 0 && { profile: this.clientOptions.profile }
 		});
@@ -3012,6 +3019,7 @@ var CfnLocalStateProvider = class {
 		if (this.disposed) throw new Error("CfnLocalStateProvider used after dispose()");
 		if (!this.lambdaClient) this.lambdaClient = new LambdaClient({
 			...workloadClientConfig({ profile: this.clientOptions.profile }),
+			...this.overrideClientConfig(),
 			region: this.region,
 			...this.clientOptions.profile !== void 0 && { profile: this.clientOptions.profile }
 		});
@@ -3021,6 +3029,7 @@ var CfnLocalStateProvider = class {
 		if (this.disposed) throw new Error("CfnLocalStateProvider used after dispose()");
 		if (!this.agentCoreControlClient) this.agentCoreControlClient = new BedrockAgentCoreControlClient({
 			...workloadClientConfig({ profile: this.clientOptions.profile }),
+			...this.overrideClientConfig(),
 			region: this.region,
 			...this.clientOptions.profile !== void 0 && { profile: this.clientOptions.profile }
 		});
@@ -3030,6 +3039,7 @@ var CfnLocalStateProvider = class {
 		if (this.disposed) throw new Error("CfnLocalStateProvider used after dispose()");
 		if (!this.ssmClient) this.ssmClient = new SSMClient({
 			...workloadClientConfig({ profile: this.clientOptions.profile }),
+			...this.overrideClientConfig(),
 			region: this.region,
 			...this.clientOptions.profile !== void 0 && { profile: this.clientOptions.profile }
 		});
@@ -3292,7 +3302,7 @@ function rejectExplicitCfnStackWithMultipleStacks(options, routedStackCount) {
 	if (typeof options.fromCfnStack !== "string") return;
 	throw new LocalStateSourceError(`--from-cfn-stack <name> cannot be used with multiple routed stacks (got ${routedStackCount}). An explicit CFn stack name applies to one stack only and would silently mismap logical IDs across siblings. Use bare --from-cfn-stack (each stack uses its own name as the CFn stack name) or run one ${getEmbedConfig().binaryName} invocation per stack.`);
 }
-function createLocalStateProvider(options, stackName, synthRegion, extraStateProviders) {
+function createLocalStateProvider(options, stackName, synthRegion, extraStateProviders, behavior = {}) {
 	const cfnStackOpt = options.fromCfnStack;
 	const cfnFlagPresent = isCfnFlagPresent(options);
 	const activeExtras = [];
@@ -3302,11 +3312,27 @@ function createLocalStateProvider(options, stackName, synthRegion, extraStatePro
 	if (cfnFlagPresent && activeExtras.length > 0) throw new LocalStateSourceError(`--from-cfn-stack is mutually exclusive with ${activeExtras.map(toFlagName).join(", ")}. Pick one state source.`);
 	if (activeExtras.length > 1) throw new LocalStateSourceError(`state-source flags are mutually exclusive: ${activeExtras.map(toFlagName).join(", ")}. Pick one.`);
 	if (cfnStackOpt === "") throw new LocalStateSourceError("--from-cfn-stack requires a non-empty stack name when an explicit value is provided. Drop the value to use the resolved stack name, or pass --from-cfn-stack <name>.");
-	if (cfnFlagPresent) return new CfnLocalStateProvider({
-		cfnStackName: resolveCfnStackName(cfnStackOpt, stackName),
-		region: resolveCfnRegion(options, synthRegion),
-		...options.profile !== void 0 && { profile: options.profile }
-	});
+	if (cfnFlagPresent) {
+		const cfnStackName = resolveCfnStackName(cfnStackOpt, stackName);
+		const region = resolveCfnRegion(options, synthRegion);
+		const real = new CfnLocalStateProvider({
+			cfnStackName,
+			region,
+			...options.profile !== void 0 && { profile: options.profile }
+		});
+		const mixed = behavior.realAwsOnly ? void 0 : getActiveWorkloadAwsWiring()?.mixed;
+		if (!mixed) return real;
+		return createMixedModeStateProvider({
+			real,
+			emulator: new CfnLocalStateProvider({
+				cfnStackName,
+				region,
+				endpointOverride: mixed.emulatorClientOverride,
+				label: "--from-cfn-stack (AWS Emulator)"
+			}),
+			emulatedServices: mixed.services
+		});
+	}
 	if (activeExtras.length === 1) {
 		const factory = extraStateProviders[activeExtras[0]];
 		return factory(options);
@@ -10478,6 +10504,97 @@ function createFileWatcher(options) {
 	} };
 }
 
+//#endregion
+//#region src/local/reload-queue.ts
+async function stopWatchReloads(args) {
+	const closing = args.watcher ? args.watcher.close().catch((err) => args.onWatcherCloseError?.(err)) : Promise.resolve();
+	const draining = args.queue ? args.queue.stop() : Promise.resolve();
+	await closing;
+	await draining;
+}
+function createReloadQueue(options) {
+	const abort = new AbortController();
+	let stopped = false;
+	let current;
+	let pending;
+	let started = 0;
+	let finished = 0;
+	const runBatch = async (batch) => {
+		try {
+			await (async () => options.run(batch, abort.signal))();
+		} catch (err) {
+			try {
+				options.onError?.(err);
+			} catch {}
+		}
+	};
+	const start = (paths) => {
+		(async () => {
+			let next = paths;
+			while (next) {
+				started += 1;
+				current = runBatch(next);
+				await current;
+				finished += 1;
+				next = !stopped && pending ? [...pending] : void 0;
+				pending = void 0;
+			}
+			current = void 0;
+		})();
+	};
+	const idle = async () => {
+		const target = started + (pending ? 1 : 0);
+		while (current && finished < target) await current;
+	};
+	return {
+		schedule(changedPaths) {
+			if (stopped) return;
+			if (!current) {
+				start(changedPaths);
+				return;
+			}
+			const wasPending = pending !== void 0;
+			pending ??= /* @__PURE__ */ new Set();
+			for (const p of changedPaths) pending.add(p);
+			if (wasPending) options.onCoalesced?.(pending.size);
+		},
+		async stop() {
+			if (!stopped) {
+				stopped = true;
+				pending = void 0;
+				abort.abort();
+			}
+			await idle();
+		},
+		idle,
+		get stopped() {
+			return stopped;
+		}
+	};
+}
+
+//#endregion
+//#region src/utils/shutdown-signal.ts
+function createShutdownSignalHandler(options) {
+	const exit = options.exit ?? ((code) => process.exit(code));
+	const writeStderr = options.writeStderr ?? ((text) => void process.stderr.write(text));
+	let count = 0;
+	return (signal, exitCode) => {
+		count += 1;
+		if (count === 1) {
+			options.info(options.stoppingMessage(signal));
+			options.cleanup().then(() => exit(exitCode));
+			return;
+		}
+		if (count === 2) {
+			options.warn(`Received ${signal} again; still shutting down — waiting for the cleanup to remove the containers and networks. Send it once more to force-exit (that skips the cleanup).`);
+			return;
+		}
+		writeStderr(`Force-exit on repeated ${signal}; container cleanup skipped. ${options.forceExitHint}\n`);
+		exit(130);
+	};
+}
+
 //#endregion
 //#region src/local/authorizer-cache.ts
 function createAuthorizerCache(opts = {}) {
@@ -10871,7 +10988,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 	}
 	process.stdout.write("^C to stop and clean up containers.\n");
 	let watcher;
-	let reloadChain = Promise.resolve();
+	let reloadQueue;
 	if (options.watch) {
 		const watchRoot = process.cwd();
 		const { ignored, shouldTrigger, excludePatterns } = createWatchPredicates({
@@ -10879,105 +10996,97 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 			output: options.output,
 			watchConfig: resolveWatchConfig()
 		});
+		const queue = createReloadQueue({
+			run: (_changedPaths, signal) => reloadAllServers({
+				synthesizeAndBuild,
+				servers,
+				buildPool,
+				logger,
+				signal
+			}),
+			onError: (err) => logger.warn(`Reload failed: ${err instanceof Error ? err.message : String(err)}`)
+		});
+		reloadQueue = queue;
 		watcher = createFileWatcher({
 			paths: [watchRoot],
 			ignored,
 			shouldTrigger,
-			onChange: () => {
+			onChange: (changedPaths) => {
 				logger.info("Detected source change; reloading...");
-				reloadChain = reloadChain.then(() => reloadAllServers({
-					synthesizeAndBuild,
-					servers,
-					buildPool,
-					logger
-				})).catch(() => void 0);
+				queue.schedule(changedPaths);
 			}
 		});
 		logger.info(`Watching ${watchRoot} for source changes (excluding ${excludePatterns.join(", ")}).`);
 	}
-	let shutdownStarted = false;
-	let firstSignal;
-	let firstExitCode = 0;
-	let forceExitArmed = false;
-	const runCleanup = singleFlight(async () => {
-		logger.info(`Received ${firstSignal}, shutting down...`);
-		if (watcher) try {
-			await watcher.close();
-		} catch (err) {
-			logger.warn(`watcher.close() failed: ${err instanceof Error ? err.message : String(err)}`);
-		}
-		await Promise.allSettled(wsServers.map(async (ws) => {
-			try {
-				await ws.attached.close();
-			} catch (err) {
-				logger.warn(`WebSocket close() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
-			}
-		}));
-		await Promise.allSettled(servers.map(async ({ server, group }) => {
-			try {
-				await server.close();
-			} catch (err) {
-				logger.warn(`server.close() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
-			}
-		}));
-		await Promise.allSettled(wsServers.map(async (ws) => {
-			try {
-				await ws.server.close();
+	const shutdown = createShutdownSignalHandler({
+		cleanup: singleFlight(async () => {
+			await stopWatchReloads({
+				watcher,
+				queue: reloadQueue,
+				onWatcherCloseError: (err) => logger.warn(`watcher.close() failed: ${err instanceof Error ? err.message : String(err)}`)
+			});
+			await Promise.allSettled(wsServers.map(async (ws) => {
+				try {
+					await ws.attached.close();
+				} catch (err) {
+					logger.warn(`WebSocket close() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}));
+			await Promise.allSettled(servers.map(async ({ server, group }) => {
+				try {
+					await server.close();
+				} catch (err) {
+					logger.warn(`server.close() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}));
+			await Promise.allSettled(wsServers.map(async (ws) => {
+				try {
+					await ws.server.close();
+				} catch (err) {
+					logger.warn(`WebSocket server.close() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}));
+			await Promise.allSettled(servers.map(async ({ server, group }) => {
+				try {
+					await server.getServerState().pool.dispose();
+				} catch (err) {
+					logger.warn(`pool.dispose() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}));
+			await Promise.allSettled(wsServers.map(async (ws) => {
+				try {
+					await ws.server.getServerState().pool.dispose();
+				} catch (err) {
+					logger.warn(`WebSocket pool.dispose() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}));
+			for (const dir of inlineTmpDirs) try {
+				rmSync(dir, {
+					recursive: true,
+					force: true
+				});
 			} catch (err) {
-				logger.warn(`WebSocket server.close() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
+				logger.warn(`Failed to remove inline-code tmpdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
 			}
-		}));
-		await Promise.allSettled(servers.map(async ({ server, group }) => {
-			try {
-				await server.getServerState().pool.dispose();
+			for (const dir of layerTmpDirs) try {
+				rmSync(dir, {
+					recursive: true,
+					force: true
+				});
 			} catch (err) {
-				logger.warn(`pool.dispose() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
+				logger.warn(`Failed to remove merged-layers tmpdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
 			}
-		}));
-		await Promise.allSettled(wsServers.map(async (ws) => {
-			try {
-				await ws.server.getServerState().pool.dispose();
+			if (profileCredsFile) try {
+				await profileCredsFile.dispose();
 			} catch (err) {
-				logger.warn(`WebSocket pool.dispose() failed for ${ws.api.apiLogicalId}: ${err instanceof Error ? err.message : String(err)}`);
+				logger.warn(`Failed to remove profile credentials tmpdir ${profileCredsFile.hostPath}: ${err instanceof Error ? err.message : String(err)}`);
 			}
-		}));
-		for (const dir of inlineTmpDirs) try {
-			rmSync(dir, {
-				recursive: true,
-				force: true
-			});
-		} catch (err) {
-			logger.warn(`Failed to remove inline-code tmpdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
-		}
-		for (const dir of layerTmpDirs) try {
-			rmSync(dir, {
-				recursive: true,
-				force: true
-			});
-		} catch (err) {
-			logger.warn(`Failed to remove merged-layers tmpdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
-		}
-		if (profileCredsFile) try {
-			await profileCredsFile.dispose();
-		} catch (err) {
-			logger.warn(`Failed to remove profile credentials tmpdir ${profileCredsFile.hostPath}: ${err instanceof Error ? err.message : String(err)}`);
-		}
+		}),
+		stoppingMessage: (signal) => `Received ${signal}, shutting down...`,
+		forceExitHint: `Orphan containers may remain — run 'docker ps --filter name=${getEmbedConfig().resourceNamePrefix}-' and 'docker rm -f' to clean up.`,
+		info: (m) => logger.info(m),
+		warn: (m) => logger.warn(m)
 	});
-	const shutdown = async (signal, exitCode) => {
-		if (shutdownStarted) {
-			if (!forceExitArmed) {
-				forceExitArmed = true;
-				logger.warn(`Received second ${signal}; force-exiting. Orphan containers may remain — run 'docker ps --filter name=${getEmbedConfig().resourceNamePrefix}-' and 'docker rm -f' to clean up.`);
-				process.exit(130);
-			}
-			return;
-		}
-		shutdownStarted = true;
-		firstSignal = signal;
-		firstExitCode = exitCode;
-		await runCleanup();
-		process.exit(firstExitCode);
-	};
 	process.on("SIGINT", () => {
 		shutdown("SIGINT", 130);
 	});
@@ -11695,7 +11804,7 @@ function warnSsrfRiskyIntegrations(routes, logger) {
 	}
 }
 async function reloadAllServers(args) {
-	const { synthesizeAndBuild, servers, buildPool, logger } = args;
+	const { synthesizeAndBuild, servers, buildPool, logger, signal } = args;
 	let material;
 	try {
 		material = await synthesizeAndBuild();
@@ -11703,6 +11812,10 @@ async function reloadAllServers(args) {
 		logger.warn(`cdk synth failed during reload; keeping previous version. (${err instanceof Error ? err.message : String(err)})`);
 		return;
 	}
+	if (signal?.aborted) {
+		logger.info("Reload cancelled: shutting down.");
+		return;
+	}
 	const newGroups = groupRoutesByServer(material.routes);
 	const newByKey = new Map(newGroups.map((g) => [g.serverKey, g]));
 	const oldKeys = new Set(servers.map((s) => s.group.serverKey));
@@ -13397,9 +13510,12 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 	let containerId;
 	let stopLogs;
 	let sigintHandler;
+	let sigtermHandler;
 	let profileCredsFile;
 	let stateProvider;
+	let stopWatch;
 	const cleanup = singleFlight(async () => {
+		if (stopWatch) await stopWatch();
 		if (stateProvider) try {
 			stateProvider.dispose();
 		} catch (err) {
@@ -13504,10 +13620,17 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 			...sensitiveEnvKeys.size > 0 && { sensitiveEnvKeys }
 		});
 		stopLogs = streamLogs(containerId);
-		sigintHandler = () => {
-			cleanup().then(() => process.exit(130));
-		};
+		const onSignal = createShutdownSignalHandler({
+			cleanup,
+			stoppingMessage: (signal) => `Received ${signal}, removing the agent container...`,
+			forceExitHint: `Run 'docker ps -a --filter name=${getEmbedConfig().resourceNamePrefix}-' to find what is left.`,
+			info: (m) => logger.info(m),
+			warn: (m) => logger.warn(m)
+		});
+		sigintHandler = () => onSignal("SIGINT", 130);
+		sigtermHandler = () => onSignal("SIGTERM", 143);
 		process.on("SIGINT", sigintHandler);
+		process.on("SIGTERM", sigtermHandler);
 		if (isMcp && mcpRequest) {
 			logger.info(`MCP request: ${mcpRequest.method}`);
 			const mcp = await mcpInvokeOnce(containerHost, hostPort, mcpRequest, { requestTimeoutMs: options.timeout });
@@ -13534,7 +13657,10 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 				synthOpts,
 				stacks,
 				...authorization && { authorization },
-				rebuild: async () => {
+				registerStop: (stop) => {
+					stopWatch = stop;
+				},
+				rebuild: async (signal) => {
 					if (stopLogs) {
 						try {
 							stopLogs();
@@ -13555,6 +13681,7 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 					await resolveFromS3BucketIntrinsic(newResolved, stateProvider, newLoaded, newImageContext);
 					const newImage = await resolveAgentCoreImage(newResolved, options, newLoaded, stateProvider);
 					const { env: newEnv, sensitiveEnvKeys: newSensitive } = await buildContainerEnv(newResolved, options, profileCredentials, profileCredsFile, stateProvider, newLoaded, newImageContext);
+					if (signal?.aborted) throw new CdkLocalError("Reload cancelled: shutting down.", "LOCAL_INVOKE_AGENTCORE_WATCH_CANCELLED");
 					const newHostPort = await pickFreePort();
 					const newName = `${getEmbedConfig().resourceNamePrefix}-agentcore-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
 					logger.info(`Reload: starting agent container (image=${newImage}, port=${newHostPort} -> 8080)...`);
@@ -13611,8 +13738,9 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 			emitResult(result);
 		}
 	} finally {
-		if (sigintHandler) process.off("SIGINT", sigintHandler);
 		await cleanup();
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		if (sigtermHandler) process.off("SIGTERM", sigtermHandler);
 	}
 }
 async function resolveInboundAuthorization(resolved, options) {
@@ -14164,7 +14292,7 @@ async function runAgentCoreWatchLoop(args) {
 	const waitForPing = args.__waitForPing ?? waitForAgentCorePing;
 	let currentHostPort = args.hostPort;
 	let currentStacks = args.stacks;
-	let reloadChain = Promise.resolve();
+	let reloadQueue;
 	let currentAbort;
 	let pendingReload = false;
 	let reloadFailed = false;
@@ -14185,8 +14313,8 @@ async function runAgentCoreWatchLoop(args) {
 	});
 	const cdkOutDir = args.options.output;
 	const assetLoader = new AssetManifestLoader();
-	const watcher = watcherFactory((changedPaths) => {
-		reloadChain = reloadChain.then(async () => {
+	reloadQueue = createReloadQueue({
+		run: async (changedPaths, signal) => {
 			let verdict = {
 				kind: "rebuild",
 				reason: "classifier not consulted"
@@ -14221,6 +14349,7 @@ async function runAgentCoreWatchLoop(args) {
 					reason: "classifier context unavailable; falling back to rebuild"
 				};
 			}
+			if (signal.aborted) return;
 			pendingReload = true;
 			logger.warn("cdkl invoke-agentcore --watch: source change detected; closing the active /ws socket so the client can reconnect to the rebuilt container.");
 			currentAbort?.abort();
@@ -14230,20 +14359,32 @@ async function runAgentCoreWatchLoop(args) {
 					currentStacks = newStacks;
 					logger.info("Reload: soft-reloaded the agent container (docker cp + docker restart; container ID + host port preserved).");
 				} else {
-					const { containerId: _newId, hostPort: newHostPort, stacks: newStacks } = await args.rebuild();
+					const { containerId: _newId, hostPort: newHostPort, stacks: newStacks } = await args.rebuild(signal);
 					currentHostPort = newHostPort;
 					currentStacks = newStacks;
 					logger.info(`Reload: rebuilt the agent container.`);
 				}
 			} catch (err) {
+				if (signal.aborted) {
+					logger.info("Reload cancelled: shutting down.");
+					reloadFailed = true;
+					currentAbort?.abort();
+					return;
+				}
 				logger.error(`Reload failed: ${err instanceof Error ? err.message : String(err)}. The previous container may already be torn down; exiting --watch loop. Re-run cdkl invoke-agentcore --watch to recover.`);
 				reloadFailed = true;
 				currentAbort?.abort();
 			}
-		}).catch((err) => {
-			logger.error(`Reload chain threw: ${err instanceof Error ? err.message : String(err)}`);
-		});
+		},
+		onError: (err) => logger.error(`Reload chain threw: ${err instanceof Error ? err.message : String(err)}`)
 	});
+	const queue = reloadQueue;
+	const watcher = watcherFactory((changedPaths) => queue.schedule(changedPaths));
+	args.registerStop?.(() => stopWatchReloads({
+		watcher,
+		queue,
+		onWatcherCloseError: (err) => logger.warn(`Watcher close failed: ${err instanceof Error ? err.message : String(err)}`)
+	}));
 	try {
 		let firstIteration = true;
 		while (true) {
@@ -14272,17 +14413,17 @@ async function runAgentCoreWatchLoop(args) {
 				currentAbort = void 0;
 			}
 			if (!pendingReload) {
-				await reloadChain.catch(() => void 0);
+				await queue.idle();
 				if (!pendingReload) break;
 			}
-			await reloadChain.catch(() => void 0);
+			await queue.idle();
 		}
 	} finally {
-		try {
-			await watcher.close();
-		} catch (err) {
-			logger.warn(`Watcher close failed: ${err instanceof Error ? err.message : String(err)}`);
-		}
+		await stopWatchReloads({
+			watcher,
+			queue,
+			onWatcherCloseError: (err) => logger.warn(`Watcher close failed: ${err instanceof Error ? err.message : String(err)}`)
+		});
 	}
 }
 const execFileAsync$6 = promisify(execFile);
@@ -16461,10 +16602,10 @@ const defaultDockerStartImpl = async (containerId, opts = {}) => {
 	const { getDockerCmd } = await import("./docker-cmd-Cjg3jGYF.js").then((n) => n.t);
 	await promisify(execFile)(getDockerCmd(), ["start", containerId]);
 	if (opts.joinedForwarder) return;
-	const { getActiveWorkloadAwsWiring } = await import("./workload-identity-ITM3p2Ed.js").then((n) => n.L);
+	const { getActiveWorkloadAwsWiring } = await import("./workload-identity-D5zkhVcF.js").then((n) => n.R);
 	const wiring = getActiveWorkloadAwsWiring();
 	if (wiring) {
-		const { attachLoopbackForwarder } = await import("./docker-runner-CLlVjU7l.js").then((n) => n.o);
+		const { attachLoopbackForwarder } = await import("./docker-runner-DzPTb4Ai.js").then((n) => n.o);
 		await attachLoopbackForwarder(containerId, wiring);
 	}
 };
@@ -18985,24 +19126,21 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 	setShadowReadyTimeoutMs(resolveShadowReadyTimeoutMs(options, getEmbedConfig().envPrefix));
 	let perTarget = [];
 	let sigintHandler;
-	let sigintCount = 0;
+	let sigtermHandler;
 	let sharedNetwork;
 	let profileCredsFile;
 	let frontDoorServers = [];
 	let frontDoorByService = /* @__PURE__ */ new Map();
 	let frontDoorLambdaRunners = [];
 	let watcher;
-	let reloadChain = Promise.resolve();
+	let reloadQueue;
 	const cleanup = singleFlight(async () => {
-		if (watcher) {
-			try {
-				await watcher.close();
-			} catch (err) {
-				getLogger().warn(`watcher.close() failed: ${err instanceof Error ? err.message : String(err)}`);
-			}
-			watcher = void 0;
-		}
-		await reloadChain.catch(() => void 0);
+		await stopWatchReloads({
+			watcher,
+			queue: reloadQueue,
+			onWatcherCloseError: (err) => getLogger().warn(`watcher.close() failed: ${err instanceof Error ? err.message : String(err)}`)
+		});
+		watcher = void 0;
 		await Promise.allSettled(perTarget.map(async (pt) => {
 			if (pt.controller) await pt.controller.shutdown();
 			else {
@@ -19100,17 +19238,17 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 			frontDoorByService = built.frontDoorByService;
 			frontDoorLambdaRunners = built.lambdaRunners;
 		}
-		sigintHandler = () => {
-			sigintCount += 1;
-			if (sigintCount >= 2) {
-				process.stderr.write("Force-exit on second ^C; container cleanup skipped.\n");
-				process.exit(130);
-			}
-			logger.info("Stopping service(s)...");
-			cleanup().then(() => process.exit(130));
-		};
+		const onSignal = createShutdownSignalHandler({
+			cleanup,
+			stoppingMessage: () => "Stopping service(s)...",
+			forceExitHint: `Run 'docker ps -a --filter name=${getEmbedConfig().resourceNamePrefix}-' and 'docker network ls --filter name=${getEmbedConfig().resourceNamePrefix}-' to find what is left.`,
+			info: (m) => logger.info(m),
+			warn: (m) => logger.warn(m)
+		});
+		sigintHandler = () => onSignal("SIGINT", 130);
+		sigtermHandler = () => onSignal("SIGTERM", 130);
 		process.on("SIGINT", sigintHandler);
-		process.on("SIGTERM", sigintHandler);
+		process.on("SIGTERM", sigtermHandler);
 		const { tags: imageOverrideTags, overrides: imageOverrideMap } = await resolveAndBuildImageOverrides({
 			perTarget: perTarget.map((pt) => pt.boot.target),
 			stacks,
@@ -19144,47 +19282,50 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 				output: options.output,
 				watchConfig: resolveWatchConfig()
 			});
+			reloadQueue = createReloadQueue({
+				run: (changedPaths, signal) => reloadAllServices({
+					perTarget,
+					synthesizer,
+					synthOpts,
+					strategy,
+					resolvedTargets,
+					cloudMapIndexByStack,
+					options,
+					discovery,
+					skipPull,
+					extraStateProviders,
+					profileCredsFile,
+					frontDoorByService,
+					changedPaths,
+					imageOverrideTags,
+					imageOverrideMap,
+					logger,
+					signal
+				}),
+				onError: (err) => logger.error(`reloadAllServices threw: ${err instanceof Error ? err.message : String(err)}`),
+				onCoalesced: (n) => logger.debug(`Reload in progress; ${n} changed path(s) queued for one follow-up reload.`)
+			});
+			const queue = reloadQueue;
 			watcher = createFileWatcher({
 				paths: [watchRoot],
 				ignored,
 				shouldTrigger,
 				onChange: (changedPaths) => {
 					logger.info(`Detected source change (${changedPaths.length} path(s)); reloading service(s)...`);
-					reloadChain = reloadChain.then(() => reloadAllServices({
-						perTarget,
-						synthesizer,
-						synthOpts,
-						strategy,
-						resolvedTargets,
-						cloudMapIndexByStack,
-						options,
-						discovery,
-						skipPull,
-						extraStateProviders,
-						profileCredsFile,
-						frontDoorByService,
-						changedPaths,
-						imageOverrideTags,
-						imageOverrideMap,
-						logger
-					})).catch((err) => {
-						logger.error(`reloadAllServices threw: ${err instanceof Error ? err.message : String(err)}`);
-					});
+					queue.schedule(changedPaths);
 				}
 			});
 			logger.info(`Watching ${watchRoot} for source changes (excluding ${excludePatterns.join(", ")}).`);
 		}
 		await new Promise(() => {});
 	} finally {
-		if (sigintHandler) {
-			process.off("SIGINT", sigintHandler);
-			process.off("SIGTERM", sigintHandler);
-		}
 		await cleanup();
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		if (sigtermHandler) process.off("SIGTERM", sigtermHandler);
 	}
 }
 async function reloadAllServices(args) {
-	const { perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, changedPaths, imageOverrideTags: boottimeImageOverrideTags, imageOverrideMap, logger } = args;
+	const { signal, perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, changedPaths, imageOverrideTags: boottimeImageOverrideTags, imageOverrideMap, logger } = args;
 	let stacks;
 	try {
 		let checkSelectedStacks;
@@ -19194,12 +19335,16 @@ async function reloadAllServices(args) {
 		logger.warn(`cdk synth failed during reload; keeping previous version. (${err instanceof Error ? err.message : String(err)})`);
 		return;
 	}
+	if (reloadCancelled(signal, logger)) return;
 	const imageOverrideTags = new Map(boottimeImageOverrideTags);
-	for (const [target, entry] of imageOverrideMap.entries()) try {
-		const newTag = (await runImageOverrideBuilds(/* @__PURE__ */ new Map([[target, entry]]))).get(target);
-		if (newTag !== void 0) imageOverrideTags.set(target, newTag);
-	} catch (err) {
-		logger.warn(`Reload of ${displayStackName(target)}: --image-override rebuild failed; keeping the previous local image. (${err instanceof Error ? err.message : String(err)})`);
+	for (const [target, entry] of imageOverrideMap.entries()) {
+		if (reloadCancelled(signal, logger)) return;
+		try {
+			const newTag = (await runImageOverrideBuilds(/* @__PURE__ */ new Map([[target, entry]]))).get(target);
+			if (newTag !== void 0) imageOverrideTags.set(target, newTag);
+		} catch (err) {
+			logger.warn(`Reload of ${displayStackName(target)}: --image-override rebuild failed; keeping the previous local image. (${err instanceof Error ? err.message : String(err)})`);
+		}
 	}
 	const { boots: newBoots, warnings } = strategy.resolveBoots(stacks, resolvedTargets);
 	for (const w of warnings) logger.warn(w);
@@ -19213,6 +19358,7 @@ async function reloadAllServices(args) {
 	const cdkOutDir = options.output;
 	const assetLoader = new AssetManifestLoader();
 	for (const pt of perTarget) {
+		if (reloadCancelled(signal, logger)) return;
 		const newBoot = newBootByTarget.get(pt.boot.target);
 		if (!newBoot) {
 			logger.warn(`Reload: target ${displayStackName(pt.boot.target)} no longer resolves to a service in the synthesized app; keeping the previous replica(s) serving.`);
@@ -19261,11 +19407,18 @@ async function reloadAllServices(args) {
 			suppressLoadBalancerWarning: strategy.suppressLoadBalancerWarning === true,
 			verdict,
 			...imageOverrideTags.get(newBoot.target) !== void 0 && { imageOverrideTag: imageOverrideTags.get(newBoot.target) },
-			logger
+			logger,
+			...signal && { signal }
 		});
 	}
+	if (reloadCancelled(signal, logger)) return;
 	logger.info("Reload complete.");
 }
+function reloadCancelled(signal, logger) {
+	if (!signal?.aborted) return false;
+	logger.info("Reload cancelled: shutting down.");
+	return true;
+}
 async function loadAssetContextForTarget(args) {
 	const { target, controller, stacks, cdkOutDir, assetLoader, logger } = args;
 	const parsed = parseEcsTarget(target);
@@ -19332,7 +19485,7 @@ async function loadAssetContextForTarget(args) {
 	};
 }
 async function rollOneTarget(args) {
-	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, verdict, imageOverrideTag, logger } = args;
+	const { signal, controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, verdict, imageOverrideTag, logger } = args;
 	const candidate = pickCandidateStack$1(newBoot.target, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 	try {
@@ -19357,6 +19510,7 @@ async function rollOneTarget(args) {
 		if (verdict.kind === "soft-reload") logger.info(`Reload of ${displayStackName(newBoot.target)}: soft-reloading ${oldReplicas.length} replica(s) one at a time (docker cp source → restart → TCP-ready probe; no rebuild).`);
 		else logger.info(`Reload of ${displayStackName(newBoot.target)}: rolling ${oldReplicas.length} replica(s) one at a time (start new shadow → swap registrations → stop old).`);
 		for (const oldInstance of oldReplicas) {
+			if (signal?.aborted) return;
 			const idx = controller.runState.replicas.indexOf(oldInstance);
 			if (idx === -1) {
 				logger.warn(`Reload of ${displayStackName(newBoot.target)}: replica r${oldInstance.index} (gen ${oldInstance.generation}) vanished before its roll; skipping.`);
@@ -20057,7 +20211,7 @@ async function localRunTaskCommand(target, options, extraStateProviders) {
 	if (options.verbose) logger.setLevel("debug");
 	const state = createEcsRunState();
 	let sigintHandler;
-	let sigintCount = 0;
+	let sigtermHandler;
 	let stateProvider;
 	let profileCredsFile;
 	let cleanupPromise;
@@ -20134,17 +20288,17 @@ async function localRunTaskCommand(target, options, extraStateProviders) {
 				}
 			}
 		} else if (!stateProvider && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to substitute them against deployed state.");
-		sigintHandler = () => {
-			sigintCount += 1;
-			if (sigintCount >= 2) {
-				process.stderr.write("Force-exit on second stop signal; container cleanup skipped.\n");
-				process.exit(130);
-			}
-			logger.info("Stopping task...");
-			cleanup().then(() => process.exit(130));
-		};
+		const onSignal = createShutdownSignalHandler({
+			cleanup,
+			stoppingMessage: () => "Stopping task...",
+			forceExitHint: `Run 'docker ps -a --filter name=${getEmbedConfig().resourceNamePrefix}-' and 'docker network ls --filter name=${getEmbedConfig().resourceNamePrefix}-' to find what is left.`,
+			info: (m) => logger.info(m),
+			warn: (m) => logger.warn(m)
+		});
+		sigintHandler = () => onSignal("SIGINT", 130);
+		sigtermHandler = () => onSignal("SIGTERM", 130);
 		process.on("SIGINT", sigintHandler);
-		process.on("SIGTERM", sigintHandler);
+		process.on("SIGTERM", sigtermHandler);
 		const effectiveAssumeRole = resolveEcsAssumeRoleOption(options);
 		let assumedCredentials;
 		let resolvedRoleArn;
@@ -20206,18 +20360,15 @@ async function localRunTaskCommand(target, options, extraStateProviders) {
 				const containers = result.state.startedContainers.filter((c) => joinedNames.has(c.name)).map((c) => c.id.slice(0, 12)).join(", ");
 				logger.info(`Under the loopback AWS endpoint, task containers share the network of a forwarder container, so that filter does not list them. Task container ids: ${containers}. Remove them before the forwarders (${joinedForwarders.map((f) => f.name).join(", ")}).`);
 			}
-			sigintCount = 99;
 			return;
 		}
 		if (result.essentialContainerName) logger.info(`Essential container ${displayIdent(result.essentialContainerName)} exited with code ${result.exitCode}.`);
 		if (result.exitCode !== 0) process.exitCode = result.exitCode;
 	} finally {
-		if (sigintHandler) {
-			process.off("SIGINT", sigintHandler);
-			process.off("SIGTERM", sigintHandler);
-		}
 		if (stateProvider) stateProvider.dispose();
 		if (!options.detach) await cleanup();
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		if (sigtermHandler) process.off("SIGTERM", sigtermHandler);
 	}
 }
 var PlaceholderAccountError = class PlaceholderAccountError extends Error {
@@ -24227,7 +24378,7 @@ async function resolveDeployedS3Origins(distribution, stacks, options, profileCr
 		buckets
 	};
 	const synthRegion = stacks.find((s) => s.stackName === distribution.stackName)?.region;
-	const provider = createLocalStateProvider(options, distribution.stackName, synthRegion, extraStateProviders);
+	const provider = createLocalStateProvider(options, distribution.stackName, synthRegion, extraStateProviders, { realAwsOnly: true });
 	let record;
 	try {
 		record = provider ? await provider.load(distribution.stackName, synthRegion) : void 0;
@@ -24388,7 +24539,7 @@ async function localStartCloudFrontCommand(target, options, extraStateProviders,
 	process.stdout.write(`CloudFront distribution serving on ${server.url}  (${displayIdent(initial.distribution.logicalId)})\n`);
 	process.stdout.write("^C to stop.\n");
 	let watcher;
-	let reloadChain = Promise.resolve();
+	let reloadQueue;
 	if (options.watch) {
 		const watchRoot = process.cwd();
 		const { ignored, shouldTrigger, excludePatterns } = createWatchPredicates({
@@ -24396,37 +24547,37 @@ async function localStartCloudFrontCommand(target, options, extraStateProviders,
 			output: options.output,
 			watchConfig: resolveWatchConfig()
 		});
+		const queue = createReloadQueue({ run: async (_changedPaths, signal) => {
+			try {
+				const reloaded = await synthAndResolve();
+				if (signal.aborted) return;
+				annotateDeployedS3Origins(reloaded.distribution, deployedS3.buckets);
+				for (const reader of deployedS3.readers.values()) reader.clearCache();
+				warnUnsupported(reloaded.distribution, extraStateProviders);
+				await attachKvsModules(reloaded.distribution, reloaded.stacks, options, profileCredentials, logger, extraStateProviders);
+				server.update(reloaded.distribution);
+				logger.info("Reload complete.");
+			} catch (err) {
+				logger.warn(`Reload failed; keeping the previous version serving: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		} });
+		reloadQueue = queue;
 		watcher = createFileWatcher({
 			paths: [watchRoot],
 			ignored,
 			shouldTrigger,
-			onChange: () => {
+			onChange: (changedPaths) => {
 				logger.info("Detected source change; reloading...");
-				reloadChain = reloadChain.then(async () => {
-					try {
-						const reloaded = await synthAndResolve();
-						annotateDeployedS3Origins(reloaded.distribution, deployedS3.buckets);
-						for (const reader of deployedS3.readers.values()) reader.clearCache();
-						warnUnsupported(reloaded.distribution, extraStateProviders);
-						await attachKvsModules(reloaded.distribution, reloaded.stacks, options, profileCredentials, logger, extraStateProviders);
-						server.update(reloaded.distribution);
-						logger.info("Reload complete.");
-					} catch (err) {
-						logger.warn(`Reload failed; keeping the previous version serving: ${err instanceof Error ? err.message : String(err)}`);
-					}
-				}).catch(() => void 0);
+				queue.schedule(changedPaths);
 			}
 		});
 		logger.info(`Watching ${watchRoot} for source changes (excluding ${excludePatterns.join(", ")}).`);
 	}
-	let shuttingDown = false;
-	const shutdown = async (signal, exitCode) => {
-		if (shuttingDown) return;
-		shuttingDown = true;
-		logger.info(`Received ${signal}, shutting down...`);
-		if (watcher) try {
-			await watcher.close();
-		} catch {}
+	const teardown = async () => {
+		await stopWatchReloads({
+			watcher,
+			queue: reloadQueue
+		});
 		try {
 			await server.close();
 		} catch {}
@@ -24436,10 +24587,16 @@ async function localStartCloudFrontCommand(target, options, extraStateProviders,
 			logger.debug(`Web function server teardown failed: ${err instanceof Error ? err.message : String(err)}`);
 		}))]);
 		await Promise.all([...deployedS3.readers.values()].map((reader) => reader.close()));
-		process.exit(exitCode);
 	};
-	process.on("SIGINT", () => void shutdown("SIGINT", 130));
-	process.on("SIGTERM", () => void shutdown("SIGTERM", 0));
+	const shutdown = createShutdownSignalHandler({
+		cleanup: () => teardown().catch(() => void 0),
+		stoppingMessage: (signal) => `Received ${signal}, shutting down...`,
+		forceExitHint: `Run 'docker ps -a --filter name=${getEmbedConfig().resourceNamePrefix}-' to find what is left.`,
+		info: (m) => logger.info(m),
+		warn: (m) => logger.warn(m)
+	});
+	process.on("SIGINT", () => shutdown("SIGINT", 130));
+	process.on("SIGTERM", () => shutdown("SIGTERM", 0));
 	await new Promise(() => void 0);
 }
 function createLocalStartCloudFrontCommand(opts = {}) {
@@ -24810,20 +24967,17 @@ async function localStartAgentCoreCommand(target, options, extraStateProviders,
 	let profileCredsFile;
 	let stateProvider;
 	let watcher;
-	let reloadChain = Promise.resolve();
+	let reloadQueue;
 	let shuttingDown = false;
 	let tornDown = false;
 	const teardown = async () => {
 		if (tornDown) return;
 		tornDown = true;
-		if (watcher) try {
-			await watcher.close();
-		} catch (err) {
-			logger.debug(`watcher close failed: ${err instanceof Error ? err.message : String(err)}`);
-		}
-		try {
-			await reloadChain;
-		} catch {}
+		await stopWatchReloads({
+			watcher,
+			queue: reloadQueue,
+			onWatcherCloseError: (err) => logger.debug(`watcher close failed: ${err instanceof Error ? err.message : String(err)}`)
+		});
 		if (server) try {
 			await server.close();
 		} catch (err) {
@@ -24908,15 +25062,18 @@ async function localStartAgentCoreCommand(target, options, extraStateProviders,
 		...sensitiveEnvKeys.size > 0 && { sensitiveEnvKeys }
 	});
 	stopLogs = streamLogs(containerId);
-	const shutdown = async (signal, exitCode) => {
-		if (shuttingDown) return;
-		shuttingDown = true;
-		logger.info(`Received ${signal}, shutting down...`);
-		await teardown();
-		process.exit(exitCode);
-	};
-	process.on("SIGINT", () => void shutdown("SIGINT", 130));
-	process.on("SIGTERM", () => void shutdown("SIGTERM", 0));
+	const shutdown = createShutdownSignalHandler({
+		cleanup: async () => {
+			shuttingDown = true;
+			await teardown().catch(() => void 0);
+		},
+		stoppingMessage: (signal) => `Received ${signal}, shutting down...`,
+		forceExitHint: `Run 'docker ps -a --filter name=${getEmbedConfig().resourceNamePrefix}-' to find what is left.`,
+		info: (m) => logger.info(m),
+		warn: (m) => logger.warn(m)
+	});
+	process.on("SIGINT", () => shutdown("SIGINT", 130));
+	process.on("SIGTERM", () => shutdown("SIGTERM", 0));
 	try {
 		if (plan.readyPath === void 0) await waitForAgentCorePing(containerHost, containerHostPort, options.timeout);
 		else await waitForAgentCoreHttpReady(containerHost, containerHostPort, plan.readyPath, options.timeout);
@@ -24986,95 +25143,99 @@ async function localStartAgentCoreCommand(target, options, extraStateProviders,
 			watchConfig: resolveWatchConfig()
 		});
 		logger.info(`Watching ${watchRoot} for source changes (excluding ${excludePatterns.join(", ")}). The warm container reloads in place; the serve stays up.`);
+		reloadQueue = createReloadQueue({
+			run: async (changedPaths) => {
+				if (tornDown || shuttingDown) return;
+				let freshStacks;
+				let freshResolved;
+				let freshLoaded;
+				let freshImageContext;
+				let verdict;
+				let nextAssetHash = currentAssetHash;
+				try {
+					const synthRes = await synthesizer.synthesize(synthOpts);
+					freshStacks = synthRes.stacks;
+					synthRes.checkSelectedStacks?.([resolved.stack.stackName]);
+					const freshCandidate = pickAgentCoreCandidateStack(resolvedTarget, freshStacks);
+					const ctx = stateProvider && freshCandidate ? await buildAgentCoreImageContext(freshCandidate, stateProvider, options) : {
+						context: void 0,
+						loaded: void 0
+					};
+					freshImageContext = ctx.context;
+					freshLoaded = ctx.loaded;
+					freshResolved = resolveAgentCoreTarget(resolvedTarget, freshStacks, freshImageContext);
+					await resolveFromS3BucketIntrinsic(freshResolved, stateProvider, freshLoaded, freshImageContext);
+					const assetCtx = await loadAgentCoreAssetContext({
+						resolvedTarget,
+						resolved: freshResolved,
+						stacks: freshStacks,
+						cdkOutDir,
+						assetLoader,
+						oldAssetHash: currentAssetHash
+					});
+					if (assetCtx?.newAssetHash !== void 0) nextAssetHash = assetCtx.newAssetHash;
+					verdict = classifySourceChange(changedPaths, assetCtx);
+					logger.info(`Detected source change (${changedPaths.length} path(s)); verdict=${verdict.kind} (${verdict.reason}).`);
+				} catch (err) {
+					logger.error(`Reload: re-synth / classify failed (${err instanceof Error ? err.message : String(err)}); skipping this change. The serve stays up against the current container.`);
+					return;
+				}
+				if (tornDown || shuttingDown) return;
+				try {
+					if (verdict.kind === "soft-reload") {
+						if (!containerId) throw new CdkLocalError("Reload: no live container to docker cp / docker restart into.", "LOCAL_START_AGENTCORE_WATCH_NO_CONTAINER");
+						await softReloadAgentContainer(containerId, verdict.newAssetSourceDir);
+						await waitReady(containerHostPort);
+						logger.info("Reload: soft-reloaded the agent container (docker cp + docker restart; container ID + host port preserved).");
+					} else {
+						if (stopLogs) {
+							try {
+								stopLogs();
+							} catch {}
+							stopLogs = void 0;
+						}
+						if (containerId) {
+							await removeContainer(containerId);
+							containerId = void 0;
+						}
+						const newImage = await resolveAgentCoreImage(freshResolved, options, freshLoaded, stateProvider);
+						const { env: newEnv, sensitiveEnvKeys: newSensitive } = await buildContainerEnv(freshResolved, options, profileCredentials, profileCredsFile, stateProvider, freshLoaded, freshImageContext);
+						if (tornDown || shuttingDown) return;
+						const newPort = await pickFreePort();
+						const newName = `${getEmbedConfig().resourceNamePrefix}-agentcore-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+						logger.info(`Reload: starting agent container (image=${newImage}, port=${newPort} -> ${plan.containerPortLabel})...`);
+						containerId = await runDetached({
+							image: newImage,
+							mounts: [],
+							env: newEnv,
+							cmd: [],
+							hostPort: newPort,
+							host: containerHost,
+							platform: options.platform,
+							name: newName,
+							...plan.containerPort !== void 0 && { containerPort: plan.containerPort },
+							...newSensitive.size > 0 && { sensitiveEnvKeys: newSensitive }
+						});
+						stopLogs = streamLogs(containerId);
+						containerHostPort = newPort;
+						await waitReady(newPort);
+						server?.setContainerPort(newPort);
+						logger.info(`Reload: rebuilt the agent container; serve re-pointed to port ${newPort}.`);
+					}
+					currentAssetHash = nextAssetHash;
+					logger.info("Reload complete.");
+				} catch (err) {
+					logger.error(`Reload failed: ${err instanceof Error ? err.message : String(err)}. The serve stays up; edit + save again to retry.`);
+				}
+			},
+			onError: (err) => logger.error(`Reload failed: ${err instanceof Error ? err.message : String(err)}.`)
+		});
+		const queue = reloadQueue;
 		watcher = createFileWatcher({
 			paths: [watchRoot],
 			ignored,
 			shouldTrigger,
-			onChange: (changedPaths) => {
-				reloadChain = reloadChain.then(async () => {
-					if (tornDown || shuttingDown) return;
-					let freshStacks;
-					let freshResolved;
-					let freshLoaded;
-					let freshImageContext;
-					let verdict;
-					let nextAssetHash = currentAssetHash;
-					try {
-						const synthRes = await synthesizer.synthesize(synthOpts);
-						freshStacks = synthRes.stacks;
-						synthRes.checkSelectedStacks?.([resolved.stack.stackName]);
-						const freshCandidate = pickAgentCoreCandidateStack(resolvedTarget, freshStacks);
-						const ctx = stateProvider && freshCandidate ? await buildAgentCoreImageContext(freshCandidate, stateProvider, options) : {
-							context: void 0,
-							loaded: void 0
-						};
-						freshImageContext = ctx.context;
-						freshLoaded = ctx.loaded;
-						freshResolved = resolveAgentCoreTarget(resolvedTarget, freshStacks, freshImageContext);
-						await resolveFromS3BucketIntrinsic(freshResolved, stateProvider, freshLoaded, freshImageContext);
-						const assetCtx = await loadAgentCoreAssetContext({
-							resolvedTarget,
-							resolved: freshResolved,
-							stacks: freshStacks,
-							cdkOutDir,
-							assetLoader,
-							oldAssetHash: currentAssetHash
-						});
-						if (assetCtx?.newAssetHash !== void 0) nextAssetHash = assetCtx.newAssetHash;
-						verdict = classifySourceChange(changedPaths, assetCtx);
-						logger.info(`Detected source change (${changedPaths.length} path(s)); verdict=${verdict.kind} (${verdict.reason}).`);
-					} catch (err) {
-						logger.error(`Reload: re-synth / classify failed (${err instanceof Error ? err.message : String(err)}); skipping this change. The serve stays up against the current container.`);
-						return;
-					}
-					if (tornDown || shuttingDown) return;
-					try {
-						if (verdict.kind === "soft-reload") {
-							if (!containerId) throw new CdkLocalError("Reload: no live container to docker cp / docker restart into.", "LOCAL_START_AGENTCORE_WATCH_NO_CONTAINER");
-							await softReloadAgentContainer(containerId, verdict.newAssetSourceDir);
-							await waitReady(containerHostPort);
-							logger.info("Reload: soft-reloaded the agent container (docker cp + docker restart; container ID + host port preserved).");
-						} else {
-							if (stopLogs) {
-								try {
-									stopLogs();
-								} catch {}
-								stopLogs = void 0;
-							}
-							if (containerId) {
-								await removeContainer(containerId);
-								containerId = void 0;
-							}
-							const newImage = await resolveAgentCoreImage(freshResolved, options, freshLoaded, stateProvider);
-							const { env: newEnv, sensitiveEnvKeys: newSensitive } = await buildContainerEnv(freshResolved, options, profileCredentials, profileCredsFile, stateProvider, freshLoaded, freshImageContext);
-							const newPort = await pickFreePort();
-							const newName = `${getEmbedConfig().resourceNamePrefix}-agentcore-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
-							logger.info(`Reload: starting agent container (image=${newImage}, port=${newPort} -> ${plan.containerPortLabel})...`);
-							containerId = await runDetached({
-								image: newImage,
-								mounts: [],
-								env: newEnv,
-								cmd: [],
-								hostPort: newPort,
-								host: containerHost,
-								platform: options.platform,
-								name: newName,
-								...plan.containerPort !== void 0 && { containerPort: plan.containerPort },
-								...newSensitive.size > 0 && { sensitiveEnvKeys: newSensitive }
-							});
-							stopLogs = streamLogs(containerId);
-							containerHostPort = newPort;
-							await waitReady(newPort);
-							server?.setContainerPort(newPort);
-							logger.info(`Reload: rebuilt the agent container; serve re-pointed to port ${newPort}.`);
-						}
-						currentAssetHash = nextAssetHash;
-						logger.info("Reload complete.");
-					} catch (err) {
-						logger.error(`Reload failed: ${err instanceof Error ? err.message : String(err)}. The serve stays up; edit + save again to retry.`);
-					}
-				});
-			}
+			onChange: (changedPaths) => queue.schedule(changedPaths)
 		});
 	}
 	await new Promise(() => void 0);
@@ -31747,4 +31908,4 @@ function addStudioSpecificOptions(cmd) {
 
 //#endregion
 export { postHook as $, addAwsEndpointOptions as $a, parseConnectionsPath as $i, addImageOverrideOptions as $n, addStartApiSpecificOptions as $r, classifyS3Error as $t, microvmFidelityWarnings as A, parseSelectionExpressionPath as Aa, applyCorsResponseHeaders as Ai, stripCloudFrontImport as An, A2A_CONTAINER_PORT as Ar, readContainerLogTail as At, MICROVM_WS_BASE_PROTOCOL as B, AgentCoreResolutionError as Ba, evaluateResponseParameters as Bi, createLocalStartAlbCommand as Bn, AGENTCORE_SESSION_ID_HEADER as Br, parseWebFunctionBuildConfig as Bt, addListSpecificOptions as C, resolveSingleTarget as Ca, verifyJwtViaDiscovery as Ci, WEB_FUNCTION_REVISION_TYPE as Cn, setShadowReadyTimeoutMs as Cr, parseKvsFileOverrides as Ct, buildMicrovmLambdaView as D, discoverWebSocketApis as Da, invokeRequestAuthorizer as Di, compileCloudFrontFunction as Dn, createLocalInvokeAgentCoreCommand as Dr, WEB_FUNCTION_CONTAINER_PORT as Dt, addStartMicrovmSpecificOptions as E, availableWebSocketApiIdentifiers as Ea, evaluateCachedLambdaPolicy as Ei, resolveWebFunctionTarget as En, addInvokeAgentCoreSpecificOptions as Er, RecentOutput as Et, microvmImageTag as F, AGENTCORE_A2A_PROTOCOL as Fa, matchRoute as Fi, findFileAssetForObjectKey as Fn, MCP_PROTOCOL_VERSION as Fr, buildNodeEntryFileStart as Ft, startMicrovmFrontDoor as G, containsDynamicReference as Ga, HOST_DOCKER_INTERNAL_GATEWAY as Gi, addStartServiceSpecificOptions as Gn, SUPPORTED_CODE_RUNTIMES as Gr, readWebFunctionServiceConfig as Gt, PROXY_PORT_HEADER as H, resolveAgentCoreTarget as Ha, selectIntegrationResponse as Hi, resolveAlbTarget as Hn, waitForAgentCoreHttpReady as Hr, WEB_FUNCTION_HTTP_ENDPOINT_ENV as Ht, planMicrovmPorts as I, AGENTCORE_AGUI_PROTOCOL as Ia, translateLambdaResponse as Ii, isBucketDeploymentResource as In, mcpInvokeOnce as Ir, defaultWebFunctionPlatform as It, MICROVM_HOOK_PATH_PREFIX as J, keysNotFromTemplate as Ja, resolveHostGatewayExtraHosts as Ji, addRunTaskSpecificOptions as Jn, renderCodeDockerfile as Jr, idFromArn as Jt, stripMicrovmProxyHeaders as K, deployedFillMayBeSecret as Ka, HOST_GATEWAY_MIN_VERSION as Ki, createLocalStartServiceCommand as Kn, buildAgentCoreCodeImage as Kr, webFunctionAssumeRole as Kt, readExposedPorts as L, AGENTCORE_HTTP_PROTOCOL as La, applyAuthorizerOverlay as Li, resolveBucketDeploymentObjectKey as Ln, parseSseForJsonRpc as Lr, resolveWebFunctionRuntime as Lt, DEFAULT_TERMINATE_HOOK_TIMEOUT_MS as M, discoverRoutes as Ma, buildCorsConfigFromCloudFrontChain as Mi, createLocalFileKvsDataSource as Mn, a2aInvokeOnce as Mr, waitForWebFunctionReady as Mt, LocalMicrovm as N, pickRefLogicalId as Na, isFunctionUrlOacFronted as Ni, createUnboundCloudFrontModule as Nn, MCP_CONTAINER_PORT as Nr, watchContainerExit as Nt, createLocalStartMicrovmCommand as O, discoverWebSocketApisOrThrow as Oa, invokeTokenAuthorizer as Oi, runViewerRequest as On, bridgeAgentCoreWs as Or, containerFailure as Ot, buildMicrovmImage as P, resolveLambdaArnIntrinsic as Pa, matchPreflight as Pi, bucketDeploymentSourceObjectKeys as Pn, MCP_PATH as Pr, WEB_FUNCTION_RUNTIMES as Pt, pollBuildHook as Q, withoutKeys as Qa, handleConnectionsRequest as Qi, addEcsAssumeRoleOptions as Qn, createLocalInvokeCommand as Qr, resolveDeployedOriginBucket as Qt, setContainerPaused as R, AGENTCORE_MCP_PROTOCOL as Ra, buildHttpApiV2Event as Ri, addAlbSpecificOptions as Rn, AGENTCORE_SIGV4_SERVICE as Rr, supportedWebFunctionRuntimes as Rt, StudioEventBus as S, resolveWatchConfig as Sa, verifyJwtAuthorizer as Si, WEB_FUNCTION_ENDPOINT_TYPE as Sn, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as Sr, normalizeKvsFileKeys as St, formatTargetListing as T, listTargets as Ta, computeRequestIdentityHash as Ti, WebFunctionResolutionError as Tn, attachContainerLogStreamer as Tr, resolveCloudFrontTarget as Tt, rewriteUpgradeResponseHead as U, DynamicReferenceResolutionError as Ua, tryParseStatus as Ui, isApplicationLoadBalancer as Un, waitForAgentCorePing as Ur, buildWebFunctionLambdaView as Ut, MicrovmStateError as V, pickAgentCoreCandidateStack as Va, pickResponseTemplate as Vi, parseLbPortOverrides as Vn, invokeAgentCore as Vr, resolveWebFunctionArtifact as Vt, selectTargetPort as W, DynamicReferenceResolver as Wa, VtlEvaluationError as Wi, resolveAlbFrontDoor as Wn, downloadAndExtractS3Bundle as Wr, finalizeWebFunctionEnv as Wt, callRuntimeHook as X, parseDynamicReference as Xa, ConnectionRegistry as Xi, MAX_TASKS_SUBNET_RANGE_CAP as Xn, classifySourceChange as Xr, createDeployedKvsDataSource as Xt, MicrovmHookError as Y, keysOverriddenBy as Ya, bufferToBody as Yi, createLocalRunTaskCommand as Yn, toCmdArgv as Yr, resolveKvsModulesForDistribution as Yt, generateMicrovmId as Z, resolveDynamicReferencesInEnv as Za, buildMgmtEndpointEnvUrl as Zi, addCommonEcsServiceOptions as Zn, addInvokeSpecificOptions as Zr, resolveDeployedKvsArnByName as Zt, filterStudioTargetGroups as _, resolveCfnRegion as _a, defaultCredentialsLoader as _i, pickKvsLogicalIdFromArn as _n, isLocalCdkAssetImage as _r, attachAgentCoreWsBridge as _t, createLocalStudioCommand as a, resolveRuntimeImage as aa, attachStageContext as ai, serveLambdaUrlOrigin as an, resolveSharedSidecarCredentials as ar, disposeMicrovmCodeArtifact as at, renderStudioHtml as b, collectSsmParameterRefs as ba, createJwksCache as bi, pickWebFunctionEndpointLogicalIdFromOrigin as bn, CloudMapRegistry as br, addStartCloudFrontSpecificOptions as bt, startStudioProxy as c, substituteAgainstState as ca, resolveEnvVars$1 as ci, buildEdgeRequestEvent as cn, buildImageOverrideTag as cr, resolveMicrovmImageTarget as ct, createStudioDispatcher as d, substituteEnvVarsFromStateAsync as da, filterRoutesByApiIdentifiers as di, httpHeadersToEdge as dn, mergeForService as dr, createLocalStartWebFunctionCommand as dt, buildConnectEvent as ea, createLocalStartApiCommand as ei, createS3OriginReader as en, awsEndpointOptions as eo, buildEcsImageResolutionContext$1 as er, runHookBody as et, filterStudioCustomResources as f, LocalStateSourceError as fa, groupRoutesByServer as fi, CLOUDFRONT_DISTRIBUTION_TYPE as fn, parseImageOverrideFlags as fr, addStartAgentCoreSpecificOptions as ft, annotatePinnedEcsTargets as g, resolveCfnFallbackRegion as ga, resolveServiceIntegrationParameters as gi, pickFunctionUrlLogicalIdFromOrigin as gn, imageOverrideKeyAliases as gr, startAgentCoreHttpServer as gt, annotateEcsTaskPinnedTargets as h, rejectExplicitCfnStackWithMultipleStacks as ha, resolveSelectionExpression as hi, isCloudFrontDistribution as hn, describePinnedImageUri as hr, selectServeInboundAuth as ht, coerceStopRequest as i, resolveRuntimeFileExtension as ia, createFileWatcher as ii, serveFromStaticOrigin as in, resolveEcsAssumeRoleOption as ir, MicrovmResolutionError as it, readRunHookPayload as j, webSocketApiMatchesIdentifier as ja, buildCorsConfigByApiId as ji, createCloudFrontModule as jn, A2A_PATH as jr, startWebFunctionContainer as jt, finalizeMicrovmEnv as k, filterWebSocketApisByIdentifiers as ka, attachAuthorizers as ki, runViewerResponse as kn, invokeAgentCoreWs as kr, planWebFunctionContainer as kt, relayServeRequest as l, substituteAgainstStateAsync as la, availableApiIdentifiers as li, buildEdgeResponseEvent as ln, canonicalizeImageOverrideKeys as lr, s3KeyOfUri as lt, annotateAlbPinnedBackingServices as m, isCfnFlagPresent as ma, startApiServer as mi, extractKvsAssociations as mn, runImageOverrideBuilds as mr, buildAgentCoreServeAuthCheck as mt, coerceRunRequest as n, buildMessageEvent as na, resolveApiTargetSubset as ni, startCloudFrontServer as nn, parseMaxTasks as nr, MICROVM_DEFAULT_INGRESS_PORT as nt, resolveServeBaseUrl as o, EcsTaskResolutionError as oa, buildStageMap as oi, applyEdgeRequestResult as on, runEcsServiceEmulator as or, readMicrovmImageConfig as ot, isCustomResourceLambdaTarget as p, createLocalStateProvider as pa, readMtlsMaterialsFromDisk as pi, describeS3OriginDomain as pn, resolveImageOverrides as pr, createLocalStartAgentCoreCommand as pt, MAX_RUN_HOOK_PAYLOAD_BYTES as q, firstUsableRegion as qa, probeHostGatewaySupport as qi, serviceStrategy as qn, computeCodeImageTag as qr, webFunctionFidelityWarnings as qt, coerceServeRequest as r, resolveRuntimeCodeMountPath as ra, createAuthorizerCache as ri, resolveErrorResponseCandidates as rn, parseRestartPolicy as rr, MICROVM_IMAGE_TYPE as rt, createStudioServeManager as s, assertEcsTaskImagesResolvable as sa, materializeLayerFromArn as si, applyEdgeResponseResult as sn, ImageOverrideError as sr, resolveMicrovmCodeArtifact as st, addStudioSpecificOptions as t, buildDisconnectEvent as ta, createWatchPredicates as ti, matchBehavior as tn, ecsClusterOption as tr, waitForAppAnswer as tt, reinvoke as u, substituteEnvVarsFromState as ua, filterRoutesByApiIdentifier as ui, edgeHeadersToHttp as un, enforceImageOverrideOrphans as ur, addStartWebFunctionSpecificOptions as ut, startStudioServer as v, resolveCfnStackName as va, buildCognitoJwksUrl as vi, pickLambdaEdgeFunctionLogicalId as vn, listPinnedTargets as vr, startAgentCoreWsBridge as vt, createLocalListCommand as w, countTargets as wa, buildMethodArn as wi, WEB_FUNCTION_TYPE as wn, getContainerNetworkIp as wr, parseOriginOverrides as wt, createStudioStore as x, resolveSsmParameters as xa, verifyCognitoJwt as xi, resolveCloudFrontDistribution as xn, DEFAULT_SHADOW_READY_TIMEOUT_MS as xr, createLocalStartCloudFrontCommand as xt, toStudioTargetGroups as y, CfnLocalStateProvider as ya, buildJwksUrlFromIssuer as yi, pickTargetFunctionLogicalId as yn, buildCloudMapIndex as yr, LocalStartCloudFrontError as yt, MICROVM_CONTROL_PATH as z, AGENTCORE_RUNTIME_TYPE as za, buildRestV1Event as zi, albStrategy as zn, signAgentCoreInvocation as zr, disposeWebFunctionArtifact as zt };
-//# sourceMappingURL=local-studio-D8eIrFzx.js.map
+//# sourceMappingURL=local-studio-CFf6tO1e.js.map