cdk-local 0.167.1 → 0.167.2

package/dist/{local-studio-CrP4kia1.js → local-studio-B0Wlk_VO.js}

@@ -2502,6 +2502,32 @@ async function resolveProfileRegion(profile) {
 	return resolveSdkDefaultRegion(profile);
 }
 
+// src/utils/shutdown-signal.ts
+function signalExitCode(signal) {
+	return signal === "SIGINT" ? 130 : 143;
+}
+function createShutdownSignalHandler(options) {
+	const exit = options.exit ?? ((code) => process.exit(code));
+	const writeStderr = options.writeStderr ?? ((text) => void process.stderr.write(text));
+	let count = 0;
+	const handler = (signal, exitCode) => {
+		const code = exitCode ?? signalExitCode(signal === "SIGINT" ? "SIGINT" : "SIGTERM");
+		count += 1;
+		if (count === 1) {
+			options.info(options.stoppingMessage(signal));
+			options.cleanup().then(() => exit(code));
+			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(code);
+	};
+	return handler;
+}
+
 // src/utils/error-handler.ts
 var CdkLocalError = class CdkLocalError extends Error {
 	code;
@@ -7247,10 +7273,43 @@ function getAttReads(node, out = []) {
 	}
 	return out;
 }
+function computedAttributeRead(node) {
+	if (node === null || typeof node !== "object") return void 0;
+	if (Array.isArray(node)) {
+		for (const item of node) {
+			const r = computedAttributeRead(item);
+			if (r !== void 0) return r;
+		}
+		return;
+	}
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "Fn::GetAtt" && isCrossStackIntrinsic(value)) return "a Fn::GetAtt whose logical ID or attribute name is a cross-stack reference, which CloudFormation does not accept";
+		if (key === "Fn::Sub") {
+			if (isCrossStackIntrinsic(Array.isArray(value) ? value[0] : value)) return "a Fn::Sub whose template is a cross-stack reference, which CloudFormation does not accept";
+		}
+		const r = computedAttributeRead(value);
+		if (r !== void 0) return r;
+	}
+}
+function withMaskWatch(context, masked) {
+	const inner = context.crossStackResolver;
+	if (!inner) return context;
+	const watch = (v) => {
+		if (v === STATE_SECRET_MASK) masked.hit = true;
+		return v;
+	};
+	return {
+		...context,
+		crossStackResolver: {
+			resolveImport: async (exportName) => watch(await inner.resolveImport(exportName)),
+			resolveGetStackOutput: async (stack, region, output) => watch(await inner.resolveGetStackOutput(stack, region, output))
+		}
+	};
+}
 const CROSS_STACK_ARGV_REASON = "a cross-stack reference (Fn::ImportValue / Fn::GetStackOutput): it resolves only from a state source with the producer stack deployed";
 function argvValue(sub, consumedSensitive) {
-	if (sub.kind !== "literal") return { reason: sub.reason };
 	if (consumedSensitive) return { reason: "resolved from a SecureString parameter, which would put the secret on the docker run argv; move the value into an Environment variable or a Secrets entry" };
+	if (sub.kind !== "literal") return { reason: sub.reason };
 	const value = sub.value;
 	if (typeof value === "number" || typeof value === "boolean") return { value: String(value) };
 	if (value === STATE_SECRET_MASK) return { reason: "resolved to the secret mask (***), not the deployed value" };
@@ -7663,16 +7722,17 @@ async function applyCrossStackResolverToTask(task, context, containerState) {
 					remaining.push(u);
 					continue;
 				}
-				const secret = secretAttributeRead(rawElement, argvContext.resources);
-				if (secret !== void 0) {
+				const refusal = secretAttributeRead(rawElement, argvContext.resources) ?? computedAttributeRead(rawElement);
+				if (refusal !== void 0) {
 					remaining.push({
 						...u,
-						reason: secret
+						reason: refusal
 					});
 					continue;
 				}
-				const { result: sub, consumedSensitive } = await resolveWithSensitivityAsync(rawElement, argvContext);
-				const arg = argvValue(sub, consumedSensitive);
+				const masked = { hit: false };
+				const { result: sub, consumedSensitive } = await resolveWithSensitivityAsync(rawElement, withMaskWatch(argvContext, masked));
+				const arg = masked.hit ? { reason: `resolved a cross-stack value recorded as the secret mask (${STATE_SECRET_MASK}), not the deployed value` } : argvValue(sub, consumedSensitive);
 				if ("value" in arg) {
 					target[u.index] = arg.value;
 					continue;
@@ -8411,32 +8471,6 @@ function isMalformedEnvKey(key) {
 	return !WELL_FORMED_ENV_KEY.test(key);
 }
 
-// src/utils/shutdown-signal.ts
-function signalExitCode(signal) {
-	return signal === "SIGINT" ? 130 : 143;
-}
-function createShutdownSignalHandler(options) {
-	const exit = options.exit ?? ((code) => process.exit(code));
-	const writeStderr = options.writeStderr ?? ((text) => void process.stderr.write(text));
-	let count = 0;
-	const handler = (signal, exitCode) => {
-		const code = exitCode ?? signalExitCode(signal === "SIGINT" ? "SIGINT" : "SIGTERM");
-		count += 1;
-		if (count === 1) {
-			options.info(options.stoppingMessage(signal));
-			options.cleanup().then(() => exit(code));
-			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(code);
-	};
-	return handler;
-}
-
 // src/assets/asset-source-path.ts
 function resolveAssetSourcePath(opts) {
 	const { manifestDir, value, assetOutdir, field, subject, action, wrapError } = opts;
@@ -9670,6 +9704,46 @@ function execEnvForSecrets(passthrough) {
 	return { env };
 }
 
+// src/local/container-start-guard.ts
+const NAME_CONFLICT = /is already (?:in use|used) by|Conflict\. The container name/;
+function createContainerStartGuard(options) {
+	const remove = options.remove ?? removeContainer;
+	let stopping = false;
+	const inFlight = /* @__PURE__ */ new Set();
+	const cancelled = () => new CdkLocalError("Shutting down: the container is not used.", options.cancelledCode);
+	const stopAll = async () => {
+		stopping = true;
+		return (await Promise.all([...inFlight])).filter((id) => id !== void 0);
+	};
+	return {
+		async run(start, name) {
+			if (stopping) throw cancelled();
+			const started = start();
+			const outcome = started.then((id) => id, async (err) => {
+				const message = err instanceof Error ? err.message : String(err);
+				if (name !== void 0 && !NAME_CONFLICT.test(message)) try {
+					await remove(name);
+				} catch {}
+			});
+			inFlight.add(outcome);
+			try {
+				const id = await started;
+				if (stopping) throw cancelled();
+				return id;
+			} catch (err) {
+				await outcome;
+				throw err;
+			} finally {
+				inFlight.delete(outcome);
+			}
+		},
+		async stop() {
+			return (await stopAll())[0];
+		},
+		stopAll
+	};
+}
+
 // src/local/debug-timeout.ts
 const DEBUG_FUNCTION_TIMEOUT_SEC = 36e3;
 function applyDebuggerEnv(dockerEnv, debugPort) {
@@ -10404,13 +10478,17 @@ async function localInvokeCommand(target, options, extraStateProviders) {
 	let containerId;
 	let stopLogs;
 	let sigintHandler;
+	let sigtermHandler;
 	let profileCredsFile;
+	const startGuard = createContainerStartGuard({ cancelledCode: "LOCAL_INVOKE_CANCELLED" });
 	const cleanup = singleFlight(async () => {
+		const pendingContainer = startGuard.stop();
 		if (stopLogs) try {
 			stopLogs();
 		} catch (err) {
 			getLogger().debug(`streamLogs stop failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		containerId ??= await pendingContainer;
 		if (containerId) try {
 			await removeContainer(containerId);
 		} catch (err) {
@@ -10456,6 +10534,17 @@ async function localInvokeCommand(target, options, extraStateProviders) {
 	}, (err) => {
 		getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
 	});
+	const onSignal = createShutdownSignalHandler({
+		cleanup,
+		stoppingMessage: (signal) => `Received ${signal}, removing the Lambda 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");
+	sigtermHandler = () => onSignal("SIGTERM");
+	process.on("SIGINT", sigintHandler);
+	process.on("SIGTERM", sigtermHandler);
 	try {
 		await activateWorkloadAwsWiring({
 			...options,
@@ -10523,29 +10612,26 @@ async function localInvokeCommand(target, options, extraStateProviders) {
 			readOnly: true
 		}] : imagePlan.extraMounts;
 		const hostGatewayExtraHosts = await resolveHostGatewayExtraHosts();
-		containerId = await runDetached({
-			image: imagePlan.image,
-			mounts: imagePlan.mounts,
+		const containerName = `${getEmbedConfig().resourceNamePrefix}-invoke-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+		const runPlan = imagePlan;
+		containerId = await startGuard.run(() => runDetached({
+			name: containerName,
+			image: runPlan.image,
+			mounts: runPlan.mounts,
 			extraMounts: extraMountsWithProfile,
 			env: dockerEnv,
 			...containerEnv.sensitiveEnvKeys.length > 0 && { sensitiveEnvKeys: new Set(containerEnv.sensitiveEnvKeys) },
 			...hostGatewayExtraHosts.length > 0 && { extraHosts: hostGatewayExtraHosts },
-			cmd: imagePlan.cmd,
+			cmd: runPlan.cmd,
 			hostPort,
 			host: containerHost,
 			...debugPort !== void 0 && { debugPort },
-			...imagePlan.platform !== void 0 && { platform: imagePlan.platform },
-			...imagePlan.entryPoint !== void 0 && { entryPoint: imagePlan.entryPoint },
-			...imagePlan.workingDir !== void 0 && { workingDir: imagePlan.workingDir },
-			...imagePlan.tmpfs !== void 0 && { tmpfs: imagePlan.tmpfs }
-		});
+			...runPlan.platform !== void 0 && { platform: runPlan.platform },
+			...runPlan.entryPoint !== void 0 && { entryPoint: runPlan.entryPoint },
+			...runPlan.workingDir !== void 0 && { workingDir: runPlan.workingDir },
+			...runPlan.tmpfs !== void 0 && { tmpfs: runPlan.tmpfs }
+		}), containerName);
 		stopLogs = streamLogs(containerId);
-		sigintHandler = () => {
-			cleanup().then(() => {
-				process.exit(130);
-			});
-		};
-		process.on("SIGINT", sigintHandler);
 		await waitForRieReady(containerHost, hostPort, 5e3);
 		const invokeTimeoutMs = rieInvokeTimeoutMs(lambda.timeoutSec, debugPort !== void 0);
 		const result = await invokeRie(containerHost, hostPort, event, invokeTimeoutMs);
@@ -10553,8 +10639,9 @@ async function localInvokeCommand(target, options, extraStateProviders) {
 		process.stdout.write(`${result.raw}\n`);
 		if (options.responseFile) writeFileSync(options.responseFile, result.raw);
 	} finally {
-		if (sigintHandler) process.off("SIGINT", sigintHandler);
 		await cleanup();
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		if (sigtermHandler) process.off("SIGTERM", sigtermHandler);
 	}
 }
 async function resolveImagePlan(lambda, options) {
@@ -13058,6 +13145,8 @@ function createContainerPool(specs, options) {
 	const entries = /* @__PURE__ */ new Map();
 	let disposed = false;
 	const inFlightStarts = /* @__PURE__ */ new Set();
+	const startGuard = createContainerStartGuard({ cancelledCode: "CONTAINER_POOL_DISPOSED" });
+	const startedNotReady = /* @__PURE__ */ new Set();
 	for (const logicalId of specs.keys()) entries.set(logicalId, emptyEntry(logicalId));
 	function emptyEntry(logicalId) {
 		return {
@@ -13088,7 +13177,7 @@ function createContainerPool(specs, options) {
 			}] : optMount;
 			const containerCodePath = resolveRuntimeCodeMountPath(spec.lambda.runtime);
 			const image = resolveRuntimeImage(spec.lambda.runtime);
-			containerId = await runDetached({
+			containerId = await startGuard.run(() => runDetached({
 				image,
 				platform: architectureToPlatform(spec.lambda.architecture),
 				mounts: [{
@@ -13106,8 +13195,8 @@ function createContainerPool(specs, options) {
 				...spec.debugPort !== void 0 && { debugPort: spec.debugPort },
 				...spec.tmpfs !== void 0 && { tmpfs: spec.tmpfs },
 				...spec.extraHosts !== void 0 && { extraHosts: spec.extraHosts }
-			});
-		} else containerId = await runDetached({
+			}), name);
+		} else containerId = await startGuard.run(() => runDetached({
 			image: spec.image,
 			mounts: [],
 			extraMounts: [...spec.rieMount ? [spec.rieMount] : [], ...spec.profileCredentialsFile ? [{
@@ -13127,14 +13216,17 @@ function createContainerPool(specs, options) {
 			...spec.debugPort !== void 0 && { debugPort: spec.debugPort },
 			...spec.tmpfs !== void 0 && { tmpfs: spec.tmpfs },
 			...spec.extraHosts !== void 0 && { extraHosts: spec.extraHosts }
-		});
+		}), name);
 		const stopLogStream = streamingEnabled ? streamLogs(containerId) : () => void 0;
+		startedNotReady.add(containerId);
 		try {
 			await waitForRieReady(spec.containerHost, hostPort, 3e4);
 		} catch (err) {
 			stopLogStream();
 			await removeContainer(containerId).catch(() => void 0);
 			throw err;
+		} finally {
+			startedNotReady.delete(containerId);
 		}
 		return {
 			logicalId: spec.lambda.logicalId,
@@ -13191,6 +13283,7 @@ function createContainerPool(specs, options) {
 	}
 	return {
 		async acquire(logicalId) {
+			if (disposed) throw new Error(`Container pool disposed; not starting ${displayIdent(logicalId)}.`);
 			const entry = entries.get(logicalId);
 			if (!entry) throw new Error(`containerPool.acquire: no spec registered for Lambda ${displayIdent(logicalId)}. This is a bug — every reachable route's Lambda should be registered at server boot.`);
 			if (entry.warm.length > 0) {
@@ -13257,6 +13350,7 @@ function createContainerPool(specs, options) {
 				return;
 			}
 			disposed = true;
+			const pendingRuns = startGuard.stopAll();
 			logger.debug("Disposing container pool");
 			for (const entry of entries.values()) {
 				if (entry.idleTimer) {
@@ -13318,10 +13412,14 @@ function createContainerPool(specs, options) {
 				let timedOut = 0;
 				for (const r of results) if (r.kind === "ok") allHandles.push(r.handle);
 				else if (r.kind === "timeout") timedOut++;
-				if (timedOut > 0) logger.warn(`Container pool disposed with ${timedOut} in-flight start(s) still pending after ${drainTimeoutMs}ms; relying on docker --rm + the verify.sh sweep to clean up.`);
+				if (timedOut > 0) logger.debug(`${timedOut} in-flight start(s) still pending after ${drainTimeoutMs}ms; removing them by id once their docker run returns.`);
 				inFlightStarts.clear();
 			}
-			await Promise.allSettled(allHandles.map((h) => tearDown(h)));
+			const interruptedIds = [...await pendingRuns, ...startedNotReady];
+			startedNotReady.clear();
+			await Promise.allSettled([...allHandles.map((h) => tearDown(h)), ...interruptedIds.map((id) => removeContainer(id).catch((err) => {
+				logger.warn(`Failed to remove container ${id}: ${err instanceof Error ? err.message : String(err)}. Continuing cleanup.`);
+			}))]);
 			entries.clear();
 		}
 	};
@@ -16255,6 +16353,21 @@ function formatServerListeningBanner(scheme, host, port, pathSuffix, label) {
 	return `Server listening on ${scheme}://${formatAuthority(host, port)}${pathSuffix}  (${label})\n`;
 }
 async function localStartApiCommand(targets, options, extraStateProviders) {
+	let boot;
+	try {
+		await serveStartApi(targets, options, extraStateProviders, (b) => {
+			boot = b;
+		});
+	} catch (err) {
+		if (boot) {
+			await boot.teardown().catch(() => void 0);
+			if (boot.signalled()) await new Promise(() => void 0);
+			boot.detachSignals();
+		}
+		throw err;
+	}
+}
+async function serveStartApi(targets, options, extraStateProviders, registerBoot) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	let apiFilters = [...targets];
@@ -16291,6 +16404,106 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 	const inlineTmpDirs = /* @__PURE__ */ new Set();
 	const layerTmpDirs = /* @__PURE__ */ new Set();
 	let profileCredsFile;
+	const servers = [];
+	const wsServers = [];
+	const bootPools = [];
+	let watcher;
+	let reloadQueue;
+	let shuttingDown = false;
+	let signalled = false;
+	const runCleanup = singleFlight(async () => {
+		shuttingDown = true;
+		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)}`);
+			}
+		}));
+		await Promise.allSettled(bootPools.map(async (pool) => {
+			try {
+				await pool.dispose();
+			} catch (err) {
+				logger.warn(`pool.dispose() failed: ${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)}`);
+		}
+	});
+	const shutdown = createShutdownSignalHandler({
+		cleanup: async () => {
+			signalled = true;
+			await runCleanup();
+		},
+		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 onSigint = () => shutdown("SIGINT");
+	const onSigterm = () => shutdown("SIGTERM");
+	process.on("SIGINT", onSigint);
+	process.on("SIGTERM", onSigterm);
+	registerBoot({
+		teardown: runCleanup,
+		detachSignals: () => {
+			process.off("SIGINT", onSigint);
+			process.off("SIGTERM", onSigterm);
+		},
+		signalled: () => signalled
+	});
 	const authorizerCache = createAuthorizerCache();
 	const jwksCache = createJwksCache();
 	const jwksWarnedAt = /* @__PURE__ */ new Map();
@@ -16412,6 +16625,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 		};
 	};
 	const buildPool = (specs) => {
+		if (shuttingDown) throw new CdkLocalError("Shutting down: no container pool is built.", "LOCAL_START_API_CANCELLED");
 		const pool = createContainerPool(specs, {
 			perLambdaConcurrency,
 			skipPull: options.pull === false
@@ -16437,11 +16651,11 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 	const mtlsConfig = resolveMtlsConfig(options);
 	if (mtlsConfig) logger.info("mTLS enabled: client certificates required (chain check against --mtls-truststore at TLS handshake).");
 	const initialGroups = groupRoutesByServer(initialMaterial.routes);
-	const servers = [];
 	let nextPort = basePort;
 	for (const group of initialGroups) {
 		const groupSpecs = filterSpecsForGroup(group, initialMaterial.specs);
 		const groupPool = buildPool(groupSpecs);
+		bootPools.push(groupPool);
 		const groupState = {
 			routes: group.routes,
 			pool: groupPool,
@@ -16450,6 +16664,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 		if (options.warm) {
 			logger.info(`Pre-warming ${groupSpecs.size} container(s) for ${group.displayName}...`);
 			const handles = await Promise.allSettled([...groupSpecs.keys()].map((id) => groupPool.acquire(id)));
+			if (shuttingDown) throw new CdkLocalError("Shutting down: the boot is not continued.", "LOCAL_START_API_CANCELLED");
 			for (const result of handles) if (result.status === "fulfilled") groupPool.release(result.value);
 			else logger.warn(`Pre-warm failed for one Lambda in ${group.displayName} (cold start cost will apply on first request): ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
 		}
@@ -16474,7 +16689,6 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 		});
 		if (basePort !== 0) nextPort += 1;
 	}
-	const wsServers = [];
 	const initialWsApis = initialMaterial.webSocketApis ?? [];
 	warnUnsupportedWebSocketApis(initialWsApis, logger);
 	if (initialWsApis.filter((api) => !api.unsupported).length > 0) {
@@ -16495,6 +16709,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 			continue;
 		}
 		const wsPool = buildPool(wsSpecs);
+		bootPools.push(wsPool);
 		const wsState = {
 			routes: [],
 			pool: wsPool,
@@ -16562,8 +16777,6 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 		process.stdout.write(formatServerListeningBanner(scheme, ws.server.host, ws.server.port, ws.apiPath, `${ws.api.apiLogicalId} (WebSocket API)`));
 	}
 	process.stdout.write("^C to stop and clean up containers.\n");
-	let watcher;
-	let reloadQueue;
 	if (options.watch) {
 		const watchRoot = process.cwd();
 		const { ignored, shouldTrigger, excludePatterns } = createWatchPredicates({
@@ -16593,82 +16806,6 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 		});
 		logger.info(`Watching ${watchRoot} for source changes (excluding ${excludePatterns.join(", ")}).`);
 	}
-	const runCleanup = 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(`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)}`);
-		}
-	});
-	const shutdown = createShutdownSignalHandler({
-		cleanup: runCleanup,
-		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)
-	});
-	process.on("SIGINT", () => {
-		shutdown("SIGINT");
-	});
-	process.on("SIGTERM", () => {
-		shutdown("SIGTERM");
-	});
 	process.on("uncaughtException", (err) => {
 		logger.error(`Uncaught exception: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
 		shutdown("uncaughtException", 1);
@@ -18381,7 +18518,9 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 	let profileCredsFile;
 	let stateProvider;
 	let stopWatch;
+	const startGuard = createContainerStartGuard({ cancelledCode: "LOCAL_INVOKE_AGENTCORE_CANCELLED" });
 	const cleanup = singleFlight(async () => {
+		const pendingContainer = startGuard.stop();
 		if (stopWatch) await stopWatch();
 		if (stateProvider) try {
 			stateProvider.dispose();
@@ -18393,6 +18532,7 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 		} catch (err) {
 			getLogger().debug(`streamLogs stop failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		containerId ??= await pendingContainer;
 		if (containerId) try {
 			await removeContainer(containerId);
 		} catch (err) {
@@ -18406,6 +18546,17 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 	}, (err) => {
 		getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
 	});
+	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");
+	sigtermHandler = () => onSignal("SIGTERM");
+	process.on("SIGINT", sigintHandler);
+	process.on("SIGTERM", sigtermHandler);
 	try {
 		await activateWorkloadAwsWiring({
 			...options,
@@ -18485,7 +18636,7 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 		const containerPort = isMcp ? MCP_CONTAINER_PORT : isA2a ? A2A_CONTAINER_PORT : void 0;
 		const containerPortLabel = isMcp ? `${MCP_CONTAINER_PORT}${MCP_PATH}` : isA2a ? `${A2A_CONTAINER_PORT}${"/"}` : "8080";
 		logger.info(`Starting agent container (image=${image}, port=${hostPort} -> ${containerPortLabel})...`);
-		containerId = await runDetached({
+		containerId = await startGuard.run(() => runDetached({
 			image,
 			mounts: [],
 			env: dockerEnv,
@@ -18496,19 +18647,8 @@ async function localInvokeAgentCoreCommand(target, options, extraStateProviders)
 			name: containerName,
 			...containerPort !== void 0 && { containerPort },
 			...sensitiveEnvKeys.size > 0 && { sensitiveEnvKeys }
-		});
+		}), containerName);
 		stopLogs = streamLogs(containerId);
-		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");
-		sigtermHandler = () => onSignal("SIGTERM");
-		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 });
@@ -23430,8 +23570,32 @@ function createFrontDoorLambdaRunner(lambda, opts) {
 	let stopLogStream;
 	let starting;
 	let stopped = false;
+	const startGuard = createContainerStartGuard({ cancelledCode: "FRONT_DOOR_LAMBDA_STOPPED" });
+	function removePlanTmpDirs(p) {
+		if (p?.inlineTmpDir) try {
+			rmSync(p.inlineTmpDir, {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			logger.debug(`Failed to remove inline-code tmpdir ${p.inlineTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (p?.assetTmpDir) try {
+			rmSync(p.assetTmpDir, {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			logger.debug(`Failed to remove zip-asset tmpdir ${p.assetTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
 	async function doStart() {
-		plan = lambda.kind === "zip" ? await resolveZipImagePlan(lambda, opts) : await resolveContainerImagePlan(lambda, opts);
+		const resolved = lambda.kind === "zip" ? await resolveZipImagePlan(lambda, opts) : await resolveContainerImagePlan(lambda, opts);
+		if (stopped) {
+			removePlanTmpDirs(resolved);
+			throw new Error("FrontDoorLambdaRunner stopped while starting");
+		}
+		plan = resolved;
 		const port = await pickFreePort();
 		hostPort = port;
 		const name = `${getEmbedConfig().resourceNamePrefix}-alblambda-${lambda.logicalId}-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
@@ -23444,20 +23608,20 @@ function createFrontDoorLambdaRunner(lambda, opts) {
 			AWS_LAMBDA_LOG_STREAM_NAME: "local",
 			...forwardAwsEnv()
 		};
-		logger.info(`Starting Lambda target container for ${lambda.logicalId} (image=${plan.image}, port=${port})...`);
-		const id = await runDetached({
-			image: plan.image,
-			mounts: plan.mounts,
+		logger.info(`Starting Lambda target container for ${lambda.logicalId} (image=${resolved.image}, port=${port})...`);
+		const id = await startGuard.run(() => runDetached({
+			image: resolved.image,
+			mounts: resolved.mounts,
 			env,
 			...opts.sensitiveEnvKeys && opts.sensitiveEnvKeys.size > 0 && { sensitiveEnvKeys: opts.sensitiveEnvKeys },
-			cmd: plan.cmd,
+			cmd: resolved.cmd,
 			hostPort: port,
 			host: opts.containerHost,
 			name,
-			...plan.platform !== void 0 && { platform: plan.platform },
-			...plan.entryPoint !== void 0 && { entryPoint: plan.entryPoint },
-			...plan.workingDir !== void 0 && { workingDir: plan.workingDir }
-		});
+			...resolved.platform !== void 0 && { platform: resolved.platform },
+			...resolved.entryPoint !== void 0 && { entryPoint: resolved.entryPoint },
+			...resolved.workingDir !== void 0 && { workingDir: resolved.workingDir }
+		}), name);
 		containerId = id;
 		stopLogStream = opts.streamLogs === false ? void 0 : streamLogs(id);
 		try {
@@ -23486,11 +23650,14 @@ function createFrontDoorLambdaRunner(lambda, opts) {
 		async stop() {
 			if (stopped) return;
 			stopped = true;
+			const pendingContainer = startGuard.stop();
 			try {
 				stopLogStream?.();
 			} catch (err) {
 				logger.debug(`stopLogStream(${displayIdent(lambda.logicalId)}) failed: ${err instanceof Error ? err.message : String(err)}`);
 			}
+			const pendingId = await pendingContainer;
+			containerId ??= pendingId;
 			if (containerId) {
 				try {
 					await removeContainer(containerId);
@@ -23499,22 +23666,7 @@ function createFrontDoorLambdaRunner(lambda, opts) {
 				}
 				containerId = void 0;
 			}
-			if (plan?.inlineTmpDir) try {
-				rmSync(plan.inlineTmpDir, {
-					recursive: true,
-					force: true
-				});
-			} catch (err) {
-				logger.debug(`Failed to remove inline-code tmpdir ${plan.inlineTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
-			}
-			if (plan?.assetTmpDir) try {
-				rmSync(plan.assetTmpDir, {
-					recursive: true,
-					force: true
-				});
-			} catch (err) {
-				logger.debug(`Failed to remove zip-asset tmpdir ${plan.assetTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
-			}
+			removePlanTmpDirs(plan);
 		}
 	};
 }
@@ -24141,7 +24293,14 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 	let frontDoorLambdaRunners = [];
 	let watcher;
 	let reloadQueue;
+	let sharedNetworkPending;
+	let signalled = false;
+	let stopping = false;
+	const throwIfStopping = () => {
+		if (stopping) throw new LocalStartServiceError("Shutting down: the boot is not continued.");
+	};
 	const cleanup = singleFlight(async () => {
+		stopping = true;
 		await stopWatchReloads({
 			watcher,
 			queue: reloadQueue,
@@ -24159,6 +24318,9 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		frontDoorServers = [];
 		await Promise.allSettled(frontDoorLambdaRunners.map((r) => r.stop().catch((err) => getLogger().warn(`front-door Lambda target teardown failed: ${err instanceof Error ? err.message : String(err)}`))));
 		frontDoorLambdaRunners = [];
+		const pendingNetwork = await sharedNetworkPending;
+		sharedNetwork ??= pendingNetwork;
+		sharedNetworkPending = void 0;
 		if (profileCredsFile) {
 			try {
 				await profileCredsFile.dispose();
@@ -24177,6 +24339,20 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		}
 	}, (err) => getLogger().warn(`service cleanup failed: ${err instanceof Error ? err.message : String(err)}`));
 	try {
+		const onSignal = createShutdownSignalHandler({
+			cleanup: async () => {
+				signalled = true;
+				await 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");
+		sigtermHandler = () => onSignal("SIGTERM");
+		process.on("SIGINT", sigintHandler);
+		process.on("SIGTERM", sigtermHandler);
 		await activateWorkloadAwsWiring(options);
 		warnIfEmulateRoleViaUnused(options.emulateRoleVia, {
 			roleFlag: "--assume-role",
@@ -24227,16 +24403,20 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		const taskRoleMode = isTaskRoleInEffect(options);
 		const sidecarCredentials = taskRoleMode ? void 0 : await resolveSharedSidecarCredentials(options);
 		try {
-			sharedNetwork = await createSharedSvcNetwork({
+			const creating = createSharedSvcNetwork({
 				prefix: options.cluster,
 				skipPull,
 				cluster: options.cluster,
 				...taskRoleMode && { taskRole: true },
 				...sidecarCredentials !== void 0 && { credentials: sidecarCredentials }
 			});
+			sharedNetworkPending = creating.catch(() => void 0);
+			sharedNetwork = await creating;
+			sharedNetworkPending = void 0;
 		} catch (err) {
 			throw new LocalStartServiceError(`Failed to create shared service network: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		throwIfStopping();
 		if (options.profile && sidecarCredentials) profileCredsFile = await writeProfileCredentialsFile(options.profile, sidecarCredentials);
 		const discovery = {
 			registry,
@@ -24244,22 +24424,13 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 			sharedNetwork
 		};
 		if (frontDoor && frontDoor.listeners.length > 0) {
-			const built = await buildFrontDoor(frontDoor, options, logger, extraStateProviders);
+			const built = await buildFrontDoor(frontDoor, options, logger, extraStateProviders, (r) => {
+				frontDoorLambdaRunners.push(r);
+				if (stopping) r.stop().catch(() => void 0);
+			});
 			frontDoorServers = built.servers;
 			frontDoorByService = built.frontDoorByService;
-			frontDoorLambdaRunners = built.lambdaRunners;
 		}
-		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");
-		sigtermHandler = () => onSignal("SIGTERM");
-		process.on("SIGINT", sigintHandler);
-		process.on("SIGTERM", sigtermHandler);
 		const { tags: imageOverrideTags, overrides: imageOverrideMap } = await resolveAndBuildImageOverrides({
 			perTarget: perTarget.map((pt) => pt.boot.target),
 			stacks,
@@ -24267,7 +24438,10 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 			extraStateProviders,
 			logger
 		});
-		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.boot, pt.runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService.get(pt.boot.target), strategy.suppressLoadBalancerWarning === true, imageOverrideTags.get(pt.boot.target));
+		for (const pt of perTarget) {
+			throwIfStopping();
+			pt.controller = await bootOneTarget(pt.boot, pt.runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService.get(pt.boot.target), strategy.suppressLoadBalancerWarning === true, imageOverrideTags.get(pt.boot.target));
+		}
 		if (perTarget.length > 0) {
 			const summary = perTarget.map((pt) => `${pt.controller.service.serviceName} (${pt.controller.activeReplicaCount()} replica(s))`).join(", ");
 			logger.info(`Service(s) running: ${summary}.`);
@@ -24331,6 +24505,7 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		await new Promise(() => {});
 	} finally {
 		await cleanup();
+		if (signalled) await new Promise(() => void 0);
 		if (sigintHandler) process.off("SIGINT", sigintHandler);
 		if (sigtermHandler) process.off("SIGTERM", sigtermHandler);
 	}
@@ -24692,7 +24867,7 @@ async function resolveAlbLambdaTargetEnv(plan, options, extraStateProviders) {
 	for (const [logicalId, lambda] of lambdas) out.set(logicalId, await resolveLambdaContainerEnv(lambda, envOptions, profileCredentials, extraStateProviders));
 	return out;
 }
-async function buildFrontDoor(plan, options, logger, extraStateProviders) {
+async function buildFrontDoor(plan, options, logger, extraStateProviders, onLambdaRunner) {
 	const containerHost = options.containerHost;
 	const servers = [];
 	const poolRegistry = /* @__PURE__ */ new Map();
@@ -24713,6 +24888,7 @@ async function buildFrontDoor(plan, options, logger, extraStateProviders) {
 					...containerEnv !== void 0 && containerEnv.sensitiveEnvKeys.length > 0 && { sensitiveEnvKeys: new Set(containerEnv.sensitiveEnvKeys) }
 				});
 				lambdaRegistry.set(t.lambda.logicalId, runner);
+				onLambdaRunner?.(runner);
 			}
 			const boundRunner = runner;
 			return {
@@ -29344,6 +29520,7 @@ async function bootLambdaUrlOrigins(distribution, stacks, opts) {
 				containerEnv: containerEnv.env,
 				...containerEnv.sensitiveEnvKeys.length > 0 && { sensitiveEnvKeys: new Set(containerEnv.sensitiveEnvKeys) }
 			});
+			opts.runnerSink?.push(runner);
 			logger.info(`Booting Lambda Function URL origin container for ${functionLogicalId} (the backing Lambda runs locally via RIE)...`);
 			await runner.start();
 		} catch (err) {
@@ -29366,6 +29543,14 @@ async function drainWebFunctionServes(serves) {
 		await Promise.all(batch.map((s) => s.teardown().catch(() => void 0)));
 	}
 }
+async function drainLambdaRunners(runners) {
+	let done = 0;
+	while (done < runners.length) {
+		const batch = runners.slice(done);
+		done = runners.length;
+		await Promise.all(batch.map((r) => r.stop().catch(() => void 0)));
+	}
+}
 const WEB_FUNCTION_ORIGIN_READY_TIMEOUT_MS = 6e4;
 async function bootWebFunctionOrigins(distribution, stacks, opts) {
 	const logger = getLogger();
@@ -29434,6 +29619,7 @@ async function bootLambdaEdgeFunctions(distribution, stacks, opts) {
 			containerEnv: containerEnv.env,
 			...containerEnv.sensitiveEnvKeys.length > 0 && { sensitiveEnvKeys: new Set(containerEnv.sensitiveEnvKeys) }
 		});
+		opts.runnerSink?.push(runner);
 		logger.info(`Booting Lambda@Edge container for ${functionLogicalId} (the function runs locally via RIE)...`);
 		await runner.start();
 		runners.push(runner);
@@ -29610,12 +29796,13 @@ async function localStartCloudFrontCommand(target, options, extraStateProviders,
 	await attachKvsModules(initial.distribution, initial.stacks, options, profileCredentials, logger, extraStateProviders);
 	const bootOpts = buildLambdaBootOptions(options, profileCredentials, extraStateProviders);
 	const webFunctionServes = [];
+	const bootRunners = [];
 	let bootAborted = false;
 	const onBootSignal = (signal) => {
 		if (bootAborted) return;
 		bootAborted = true;
-		logger.info(`Received ${signal} during start-up; removing the web function containers...`);
-		drainWebFunctionServes(webFunctionServes).then(() => process.exit(signalExitCode(signal)));
+		logger.info(`Received ${signal} during start-up; removing the web function containers and the Lambda containers started so far...`);
+		Promise.all([drainWebFunctionServes(webFunctionServes), drainLambdaRunners(bootRunners)]).then(() => process.exit(signalExitCode(signal)));
 	};
 	const bootSigint = () => onBootSignal("SIGINT");
 	const bootSigterm = () => onBootSignal("SIGTERM");
@@ -29623,14 +29810,18 @@ async function localStartCloudFrontCommand(target, options, extraStateProviders,
 		process.off("SIGINT", bootSigint);
 		process.off("SIGTERM", bootSigterm);
 	};
-	if ([...initial.distribution.origins.values()].some((o) => o.kind === "web-function")) {
-		process.on("SIGINT", bootSigint);
-		process.on("SIGTERM", bootSigterm);
-	}
-	const { invokers: lambdaInvokers, runners: lambdaRunners } = await bootLambdaUrlOrigins(initial.distribution, initial.stacks, bootOpts);
-	const { invokers: edgeInvokers, runners: edgeRunners } = await bootLambdaEdgeFunctions(initial.distribution, initial.stacks, bootOpts);
+	process.on("SIGINT", bootSigint);
+	process.on("SIGTERM", bootSigterm);
 	let server;
 	try {
+		const { invokers: lambdaInvokers } = await bootLambdaUrlOrigins(initial.distribution, initial.stacks, {
+			...bootOpts,
+			runnerSink: bootRunners
+		});
+		const { invokers: edgeInvokers } = await bootLambdaEdgeFunctions(initial.distribution, initial.stacks, {
+			...bootOpts,
+			runnerSink: bootRunners
+		});
 		const webFunctions = await bootWebFunctionOrigins(initial.distribution, initial.stacks, {
 			...bootOpts,
 			sink: webFunctionServes
@@ -29651,7 +29842,7 @@ async function localStartCloudFrontCommand(target, options, extraStateProviders,
 			...webFunctions.targets.size > 0 && { webFunctionOrigins: webFunctions.targets }
 		});
 	} catch (err) {
-		await Promise.all([...[...lambdaRunners, ...edgeRunners].map((r) => r.stop().catch(() => void 0)), ...webFunctionServes.map((s) => s.teardown().catch(() => void 0))]);
+		await Promise.all([...bootRunners.map((r) => r.stop().catch(() => void 0)), ...webFunctionServes.map((s) => s.teardown().catch(() => void 0))]);
 		if (bootAborted) return await new Promise(() => void 0);
 		disarmBootSignals();
 		throw err;
@@ -29703,7 +29894,7 @@ async function localStartCloudFrontCommand(target, options, extraStateProviders,
 		try {
 			await server.close();
 		} catch {}
-		await Promise.all([...[...lambdaRunners, ...edgeRunners].map((r) => r.stop().catch((err) => {
+		await Promise.all([...bootRunners.map((r) => r.stop().catch((err) => {
 			logger.debug(`Lambda runner stop failed: ${err instanceof Error ? err.message : String(err)}`);
 		})), ...webFunctionServes.map((s) => s.teardown().catch((err) => {
 			logger.debug(`Web function server teardown failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -30077,6 +30268,21 @@ function resolveAgentCoreServePlan(protocol) {
 	};
 }
 async function localStartAgentCoreCommand(target, options, extraStateProviders, hostSynthesizer) {
+	let boot;
+	try {
+		await serveAgentCore(target, options, extraStateProviders, hostSynthesizer, (b) => {
+			boot = b;
+		});
+	} catch (err) {
+		if (boot) {
+			await boot.teardown().catch(() => void 0);
+			if (boot.signalled()) await new Promise(() => void 0);
+			boot.detachSignals();
+		}
+		throw err;
+	}
+}
+async function serveAgentCore(target, options, extraStateProviders, hostSynthesizer, registerBoot) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	let containerId;
@@ -30088,9 +30294,12 @@ async function localStartAgentCoreCommand(target, options, extraStateProviders,
 	let reloadQueue;
 	let shuttingDown = false;
 	let tornDown = false;
-	const teardown = async () => {
-		if (tornDown) return;
+	const startGuard = createContainerStartGuard({ cancelledCode: "LOCAL_START_AGENTCORE_CANCELLED" });
+	let teardownPromise;
+	const teardown = () => teardownPromise ??= doTeardown();
+	const doTeardown = async () => {
 		tornDown = true;
+		const pendingContainer = startGuard.stop();
 		await stopWatchReloads({
 			watcher,
 			queue: reloadQueue,
@@ -30106,6 +30315,7 @@ async function localStartAgentCoreCommand(target, options, extraStateProviders,
 		} catch (err) {
 			logger.debug(`streamLogs stop failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		containerId ??= await pendingContainer;
 		if (containerId) try {
 			await removeContainer(containerId);
 		} catch (err) {
@@ -30118,6 +30328,28 @@ async function localStartAgentCoreCommand(target, options, extraStateProviders,
 			await profileCredsFile.dispose();
 		} catch {}
 	};
+	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)
+	});
+	const onSigint = () => shutdown("SIGINT");
+	const onSigterm = () => shutdown("SIGTERM");
+	process.on("SIGINT", onSigint);
+	process.on("SIGTERM", onSigterm);
+	registerBoot({
+		teardown,
+		detachSignals: () => {
+			process.off("SIGINT", onSigint);
+			process.off("SIGTERM", onSigterm);
+		},
+		signalled: () => shuttingDown
+	});
 	await activateWorkloadAwsWiring(options);
 	warnIfEmulateRoleViaUnused(options.emulateRoleVia, {
 		roleFlag: "--assume-role",
@@ -30171,31 +30403,20 @@ async function localStartAgentCoreCommand(target, options, extraStateProviders,
 	const containerHost = options.containerHost;
 	const containerName = `${getEmbedConfig().resourceNamePrefix}-agentcore-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
 	logger.info(`Starting agent container (image=${image}, port=${containerHostPort} -> ${plan.containerPortLabel})...`);
-	containerId = await runDetached({
+	const bootPort = containerHostPort;
+	containerId = await startGuard.run(() => runDetached({
 		image,
 		mounts: [],
 		env: dockerEnv,
 		cmd: [],
-		hostPort: containerHostPort,
+		hostPort: bootPort,
 		host: containerHost,
 		platform: options.platform,
 		name: containerName,
 		...plan.containerPort !== void 0 && { containerPort: plan.containerPort },
 		...sensitiveEnvKeys.size > 0 && { sensitiveEnvKeys }
-	});
+	}), containerName);
 	stopLogs = streamLogs(containerId);
-	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"));
-	process.on("SIGTERM", () => shutdown("SIGTERM"));
 	try {
 		if (plan.readyPath === void 0) await waitForAgentCorePing(containerHost, containerHostPort, options.timeout);
 		else await waitForAgentCoreHttpReady(containerHost, containerHostPort, plan.readyPath, options.timeout);
@@ -37022,4 +37243,4 @@ function addStudioSpecificOptions(cmd) {
 }
 
 export { postHook as $, AGENTCORE_A2A_PROTOCOL as $a, probeHostGatewaySupport as $i, addImageOverrideOptions as $n, loopbackForwarderPlan as $o, resolveApiTargetSubset as $r, classifyS3Error as $t, microvmFidelityWarnings as A, createLocalStateProvider as Aa, translateLambdaResponse as Ai, stripCloudFrontImport as An, readEnvCallerCredentials as Ao, A2A_CONTAINER_PORT as Ar, readContainerLogTail as At, MICROVM_WS_BASE_PROTOCOL as B, resolveWatchConfig as Ba, ConnectionRegistry as Bi, createLocalStartAlbCommand as Bn, HOST_DEFAULT_CREDENTIALS_MISS_TTL_MS as Bo, AGENTCORE_SESSION_ID_HEADER as Br, parseWebFunctionBuildConfig as Bt, addListSpecificOptions as C, substituteAgainstState as Ca, attachAuthorizers as Ci, WEB_FUNCTION_REVISION_TYPE as Cn, resolveDynamicReferencesInEnv as Co, setShadowReadyTimeoutMs as Cr, parseKvsFileOverrides as Ct, buildMicrovmLambdaView as D, materializeLayerFromArn as Da, isFunctionUrlOacFronted as Di, compileCloudFrontFunction as Dn, SECOND_ASSUME_MESSAGE as Do, createLocalInvokeAgentCoreCommand as Dr, WEB_FUNCTION_CONTAINER_PORT as Dt, addStartMicrovmSpecificOptions as E, substituteEnvVarsFromStateAsync as Ea, buildCorsConfigFromCloudFrontChain as Ei, resolveWebFunctionTarget as En, awsEndpointOptions as Eo, addInvokeAgentCoreSpecificOptions as Er, RecentOutput as Et, microvmImageTag as F, resolveCfnRegion as Fa, pickResponseTemplate as Fi, findFileAssetForObjectKey as Fn, AUTH_OFF_PLACEHOLDER_CREDENTIALS as Fo, MCP_PROTOCOL_VERSION as Fr, buildNodeEntryFileStart as Ft, startMicrovmFrontDoor as G, discoverWebSocketApis as Ga, buildDisconnectEvent as Gi, addStartServiceSpecificOptions as Gn, collectHostEndpointOverrides as Go, SUPPORTED_CODE_RUNTIMES as Gr, readWebFunctionServiceConfig as Gt, PROXY_PORT_HEADER as H, countTargets as Ha, handleConnectionsRequest as Hi, resolveAlbTarget as Hn, applyWorkloadAwsWiringToEnv as Ho, waitForAgentCoreHttpReady as Hr, WEB_FUNCTION_HTTP_ENDPOINT_ENV as Ht, planMicrovmPorts as I, resolveCfnStackName as Ia, selectIntegrationResponse as Ii, isBucketDeploymentResource as In, CA_TRUST_ENV_KEYS as Io, mcpInvokeOnce as Ir, defaultWebFunctionPlatform as It, MICROVM_HOOK_PATH_PREFIX as J, parseSelectionExpressionPath as Ja, createFileWatcher as Ji, addRunTaskSpecificOptions as Jn, getActiveWorkloadAwsWiring as Jo, renderCodeDockerfile as Jr, idFromArn as Jt, stripMicrovmProxyHeaders as K, discoverWebSocketApisOrThrow as Ka, buildMessageEvent as Ki, createLocalStartServiceCommand as Kn, displayEndpointValue as Ko, buildAgentCoreCodeImage as Kr, webFunctionAssumeRole as Kt, readExposedPorts as L, CfnLocalStateProvider as La, tryParseStatus as Li, resolveBucketDeploymentObjectKey as Ln, DEFAULT_AWS_EMULATOR_URL as Lo, parseSseForJsonRpc as Lr, resolveWebFunctionRuntime as Lt, DEFAULT_TERMINATE_HOOK_TIMEOUT_MS as M, isCfnFlagPresent as Ma, buildHttpApiV2Event as Mi, createLocalFileKvsDataSource as Mn, resetWorkloadIdentity as Mo, a2aInvokeOnce as Mr, waitForWebFunctionReady as Mt, LocalMicrovm as N, rejectExplicitCfnStackWithMultipleStacks as Na, buildRestV1Event as Ni, createUnboundCloudFrontModule as Nn, workloadClientConfig as No, MCP_CONTAINER_PORT as Nr, watchContainerExit as Nt, createLocalStartMicrovmCommand as O, LocalStateSourceError as Oa, matchPreflight as Oi, runViewerRequest as On, assumedRoleRecorded as Oo, bridgeAgentCoreWs as Or, containerFailure as Ot, buildMicrovmImage as P, resolveCfnFallbackRegion as Pa, evaluateResponseParameters as Pi, bucketDeploymentSourceObjectKeys as Pn, workloadStsClientConfig as Po, MCP_PATH as Pr, WEB_FUNCTION_RUNTIMES as Pt, pollBuildHook as Q, resolveLambdaArnIntrinsic as Qa, HOST_GATEWAY_MIN_VERSION as Qi, addEcsAssumeRoleOptions as Qn, logMixedModeForWorkload as Qo, createWatchPredicates as Qr, resolveDeployedOriginBucket as Qt, setContainerPaused as R, collectSsmParameterRefs as Ra, VtlEvaluationError as Ri, addAlbSpecificOptions as Rn, EMULATOR_SCRUBBED_ENV_KEYS as Ro, AGENTCORE_SIGV4_SERVICE as Rr, supportedWebFunctionRuntimes as Rt, StudioEventBus as S, containsCrossStackIntrinsic as Sa, invokeTokenAuthorizer as Si, WEB_FUNCTION_ENDPOINT_TYPE as Sn, parseDynamicReference as So, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as Sr, normalizeKvsFileKeys as St, formatTargetListing as T, substituteEnvVarsFromState as Ta, buildCorsConfigByApiId as Ti, WebFunctionResolutionError as Tn, addAwsEndpointOptions as To, attachContainerLogStreamer as Tr, resolveCloudFrontTarget as Tt, rewriteUpgradeResponseHead as U, listTargets as Ua, parseConnectionsPath as Ui, isApplicationLoadBalancer as Un, awsEmulatorEnvName as Uo, waitForAgentCorePing as Ur, buildWebFunctionLambdaView as Ut, MicrovmStateError as V, resolveSingleTarget as Va, buildMgmtEndpointEnvUrl as Vi, parseLbPortOverrides as Vn, activateWorkloadAwsWiring as Vo, invokeAgentCore as Vr, resolveWebFunctionArtifact as Vt, selectTargetPort as W, availableWebSocketApiIdentifiers as Wa, buildConnectEvent as Wi, resolveAlbFrontDoor as Wn, awsEmulatorSqsHostBlocks as Wo, downloadAndExtractS3Bundle as Wr, finalizeWebFunctionEnv as Wt, callRuntimeHook as X, discoverRoutes as Xa, createLocalInvokeCommand as Xi, MAX_TASKS_SUBNET_RANGE_CAP as Xn, getContainerJavaTruststorePath as Xo, addStartApiSpecificOptions as Xr, createDeployedKvsDataSource as Xt, MicrovmHookError as Y, webSocketApiMatchesIdentifier as Ya, addInvokeSpecificOptions as Yi, createLocalRunTaskCommand as Yn, getContainerCaBundlePath as Yo, toCmdArgv as Yr, resolveKvsModulesForDistribution as Yt, generateMicrovmId as Z, pickRefLogicalId as Za, HOST_DOCKER_INTERNAL_GATEWAY as Zi, addCommonEcsServiceOptions as Zn, javaTruststoreToolOptions as Zo, createLocalStartApiCommand as Zr, resolveDeployedKvsArnByName as Zt, filterStudioTargetGroups as _, resolveRuntimeFileExtension as _a, verifyJwtViaDiscovery as _i, pickKvsLogicalIdFromArn as _n, containsDynamicReference as _o, isLocalCdkAssetImage as _r, sqsEmulatorOriginOf as _s, attachAgentCoreWsBridge as _t, createLocalStudioCommand as a, buildLoopbackForwarderDockerArgs as aa, filterRoutesByApiIdentifiers as ai, serveLambdaUrlOrigin as an, pickAgentCoreCandidateStack as ao, resolveSharedSidecarCredentials as ar, resolveAwsEmulatorOption as as, disposeMicrovmCodeArtifact as at, renderStudioHtml as b, assertEcsTaskCommandsResolved as ba, evaluateCachedLambdaPolicy as bi, pickWebFunctionEndpointLogicalIdFromOrigin as bn, keysNotFromTemplate as bo, CloudMapRegistry as br, buildStsClientConfig as bs, addStartCloudFrontSpecificOptions as bt, startStudioProxy as c, ensureForwarderImage as ca, startApiServer as ci, buildEdgeRequestEvent as cn, formatStateRemedy as co, buildImageOverrideTag as cr, setActiveWorkloadAwsWiring as cs, resolveMicrovmImageTarget as ct, createStudioDispatcher as d, buildContainerImage as da, defaultCredentialsLoader as di, httpHeadersToEdge as dn, LocalInvokeBuildError as do, mergeForService as dr, MIXED_MODE_RESIGN_BODY_CAP_BYTES as ds, createLocalStartWebFunctionCommand as dt, resolveHostGatewayExtraHosts as ea, createAuthorizerCache as ei, createS3OriginReader as en, AGENTCORE_AGUI_PROTOCOL as eo, buildEcsImageResolutionContext$1 as er, mergeJavaToolOptions as es, runHookBody as et, filterStudioCustomResources as f, dockerRegistryEnv as fa, buildCognitoJwksUrl as fi, CLOUDFRONT_DISTRIBUTION_TYPE as fn, ambientDefaultRegion as fo, parseImageOverrideFlags as fr, REAL_SQS_QUEUE_URL as fs, addStartAgentCoreSpecificOptions as ft, annotatePinnedEcsTargets as g, resolveRuntimeCodeMountPath as ga, verifyJwtAuthorizer as gi, pickFunctionUrlLogicalIdFromOrigin as gn, DynamicReferenceResolver as go, imageOverrideKeyAliases as gr, rewriteSqsQueueUrlsInEnv as gs, startAgentCoreHttpServer as gt, annotateEcsTaskPinnedTargets as h, stripEcrCredentials as ha, verifyCognitoJwt as hi, isCloudFrontDistribution as hn, DynamicReferenceResolutionError as ho, describePinnedImageUri as hr, repointLocalSqsQueueUrlsInEnv as hs, selectServeInboundAuth as ht, coerceStopRequest as i, awaitLoopbackForwarderStatus as ia, filterRoutesByApiIdentifier as ii, serveFromStaticOrigin as in, AgentCoreResolutionError as io, resolveEcsAssumeRoleOption as ir, readProfileEndpointSettings as is, MicrovmResolutionError as it, readRunHookPayload as j, groupWorkloadsRoutedApart as ja, applyAuthorizerOverlay as ji, createCloudFrontModule as jn, recordAssumedRole as jo, A2A_PATH as jr, startWebFunctionContainer as jt, finalizeMicrovmEnv as k, UNNAMED_WORKLOAD as ka, matchRoute as ki, runViewerResponse as kn, deployAccountStsClientConfig as ko, invokeAgentCoreWs as kr, planWebFunctionContainer as kt, relayServeRequest as l, startLoopbackForwarder as la, resolveSelectionExpression as li, buildEdgeResponseEvent as ln, substituteImagePlaceholders as lo, canonicalizeImageOverrideKeys as lr, takeAwsEmulatorStateSourceHint as ls, s3KeyOfUri as lt, annotateAlbPinnedBackingServices as m, noImplicitEcrPullArgs as ma, createJwksCache as mi, extractKvsAssociations as mn, setAmbientDefaultRegion as mo, runImageOverrideBuilds as mr, realSqsHostnames as ms, buildAgentCoreServeAuthCheck as mt, coerceRunRequest as n, withWorkloadAwsWiring as na, buildStageMap as ni, startCloudFrontServer as nn, AGENTCORE_MCP_PROTOCOL as no, parseMaxTasks as nr, probeAwsEmulatorHealth as ns, MICROVM_DEFAULT_INGRESS_PORT as nt, resolveServeBaseUrl as o, buildNamespaceOwnerForwarderDockerArgs as oa, groupRoutesByServer as oi, applyEdgeRequestResult as on, resolveAgentCoreTarget as oo, runEcsServiceEmulator as or, resolveHostDefaultCredentials as os, readMicrovmImageConfig as ot, isCustomResourceLambdaTarget as p, isEcrRegistryConfigKey as pa, buildJwksUrlFromIssuer as pi, describeS3OriginDomain as pn, namedEnvAwsRegion as po, resolveImageOverrides as pr, isRealAwsHost as ps, createLocalStartAgentCoreCommand as pt, MAX_RUN_HOOK_PAYLOAD_BYTES as q, filterWebSocketApisByIdentifiers as qa, classifySourceChange as qi, serviceStrategy as qn, effectiveLoopbackPorts as qo, computeCodeImageTag as qr, webFunctionFidelityWarnings as qt, coerceServeRequest as r, LOOPBACK_FORWARDER_IMAGE as ra, availableApiIdentifiers as ri, resolveErrorResponseCandidates as rn, AGENTCORE_RUNTIME_TYPE as ro, parseRestartPolicy as rr, readEmulatorRunFiles as rs, MICROVM_IMAGE_TYPE as rt, createStudioServeManager as s, describeForwarderFailure as sa, readMtlsMaterialsFromDisk as si, applyEdgeResponseResult as sn, derivePseudoParametersFromRegion as so, ImageOverrideError as sr, resolveWorkloadAwsWiring as ss, resolveMicrovmCodeArtifact as st, addStudioSpecificOptions as t, attachLoopbackForwarder as ta, attachStageContext as ti, matchBehavior as tn, AGENTCORE_HTTP_PROTOCOL as to, ecsClusterOption as tr, parseAwsEndpoint as ts, waitForAppAnswer as tt, reinvoke as u, architectureToPlatform as ua, resolveServiceIntegrationParameters as ui, edgeHeadersToHttp as un, tryResolveImageFnJoin as uo, enforceImageOverrideOrphans as ur, writeCaBundleFile as us, addStartWebFunctionSpecificOptions as ut, startStudioServer as v, resolveRuntimeImage as va, buildMethodArn as vi, pickLambdaEdgeFunctionLogicalId as vn, deployedFillMayBeSecret as vo, listPinnedTargets as vr, buildJavaTrustStore as vs, startAgentCoreWsBridge as vt, createLocalListCommand as w, substituteAgainstStateAsync as wa, applyCorsResponseHeaders as wi, WEB_FUNCTION_TYPE as wn, withoutKeys as wo, getContainerNetworkIp as wr, parseOriginOverrides as wt, createStudioStore as x, assertEcsTaskImagesResolvable as xa, invokeRequestAuthorizer as xi, resolveCloudFrontDistribution as xn, keysOverriddenBy as xo, DEFAULT_SHADOW_READY_TIMEOUT_MS as xr, resolveProfileCredentials as xs, createLocalStartCloudFrontCommand as xt, toStudioTargetGroups as y, EcsTaskResolutionError as ya, computeRequestIdentityHash as yi, pickTargetFunctionLogicalId as yn, firstUsableRegion as yo, buildCloudMapIndex as yr, createMixedModeTlsMaterials as ys, LocalStartCloudFrontError as yt, MICROVM_CONTROL_PATH as z, resolveSsmParameters as za, bufferToBody as zi, albStrategy as zn, HOST_CA_TRUST_ENV_KEYS as zo, signAgentCoreInvocation as zr, disposeWebFunctionArtifact as zt };
-//# sourceMappingURL=local-studio-CrP4kia1.js.map
+//# sourceMappingURL=local-studio-B0Wlk_VO.js.map