cdk-local 0.65.2 → 0.66.0

package/dist/{local-list-JDGfdnip.js → local-list-CyW86HDN.js}

@@ -417,6 +417,24 @@ function stackMatchesPattern(stack, pattern) {
 //#endregion
 //#region src/local/intrinsic-image.ts
 /**
+* Render the resolver-error remedy string for a "needs deployed state"
+* failure. When the context records that a state-source provider's
+* `load()` was attempted but failed ({@link ImageResolutionContext.stateLoadFailureMessage}),
+* the hint surfaces the underlying failure and points at the
+* stack-name / region / profile knobs instead of repeating "pass
+* --from-cfn-stack" — the user already passed it and seeing the same
+* flag suggested back is misleading. Otherwise the original hint is
+* emitted verbatim.
+*
+* Returned as a clause without a trailing punctuation so callers can
+* concatenate it with their alternatives (e.g. "..., build via
+* ContainerImage.fromAsset, or pin a public image.").
+*/
+function formatStateRemedy(context) {
+	if (context?.stateLoadFailureMessage) return `the state-source attempt failed: ${context.stateLoadFailureMessage}; verify the stack name (try --from-cfn-stack <deployed-name> if it differs from the synthesized name) and that --region / --profile target the right account`;
+	return "pass --from-cfn-stack to load the deployed stack state";
+}
+/**
 * Derive the AWS pseudo parameters that are trivially knowable from the
 * deploy region alone, without any STS call or state load.
 * `urlSuffix` and `partition` follow the canonical AWS partition rules:
@@ -823,7 +841,7 @@ function resolveLambdaTarget(target, stacks) {
 	const { logicalId, resource } = match;
 	if (resource.Type !== "AWS::Lambda::Function") {
 		if (resource.Type.startsWith("Custom::")) throw new LocalInvokeResolutionError(`Resource '${logicalId}' in ${stack.stackName} is a Custom Resource (${resource.Type}), not a Lambda function. Custom Resources are invoked by the deploy framework, not by users. If you want to test the underlying handler, target the ServiceToken Lambda directly.`);
-		throw new LocalInvokeResolutionError(`Resource '${logicalId}' in ${stack.stackName} is ${resource.Type}, not a Lambda function. ${getEmbedConfig().cliName} invoke only works on AWS::Lambda::Function resources in v1.`);
+		throw new LocalInvokeResolutionError(`Resource '${logicalId}' in ${stack.stackName} is ${resource.Type}, not a Lambda function. ${getEmbedConfig().cliName} only invokes AWS::Lambda::Function resources.`);
 	}
 	return extractLambdaProperties(stack, logicalId, resource, resources);
 }
@@ -967,10 +985,10 @@ function extractImageUri$1(value, logicalId, stackName, resources, region) {
 			const pseudoParameters = derivePseudoParametersFromRegion(region);
 			const joinResolved = tryResolveImageFnJoin(value, resources, pseudoParameters ? { pseudoParameters } : void 0);
 			if (joinResolved.kind === "resolved") return joinResolved.uri;
-			if (joinResolved.kind === "needs-state") throw new LocalInvokeResolutionError(`Lambda '${logicalId}' in ${stackName} references same-stack ECR repository '${joinResolved.repoLogicalId}' via Fn::Join. ${getEmbedConfig().cliName} invoke cannot resolve the repository URI without state — deploy the stack first (so ${getEmbedConfig().productName} records the repository physical id), rebuild via lambda.DockerImageCode.fromImageAsset, or pin a public image.`);
-			if (joinResolved.kind === "unsupported-join") throw new LocalInvokeResolutionError(`Lambda '${logicalId}' in ${stackName} has an unsupported Fn::Join Code.ImageUri shape: ${joinResolved.reason}. ${getEmbedConfig().cliName} invoke recognizes the canonical CDK 2.x lambda.DockerImageCode.fromEcr Fn::Join shape (delimiter "" with nested Fn::Select/Fn::Split over an ECR Repository Arn GetAtt + Ref to the repo).`);
+			if (joinResolved.kind === "needs-state") throw new LocalInvokeResolutionError(`Lambda '${logicalId}' in ${stackName} references same-stack ECR repository '${joinResolved.repoLogicalId}' via Fn::Join. ${getEmbedConfig().cliName} cannot resolve the repository URI without state — deploy the stack first (so ${getEmbedConfig().productName} records the repository physical id), rebuild via lambda.DockerImageCode.fromImageAsset, or pin a public image.`);
+			if (joinResolved.kind === "unsupported-join") throw new LocalInvokeResolutionError(`Lambda '${logicalId}' in ${stackName} has an unsupported Fn::Join Code.ImageUri shape: ${joinResolved.reason}. ${getEmbedConfig().cliName} recognizes the canonical CDK 2.x lambda.DockerImageCode.fromEcr Fn::Join shape (delimiter "" with nested Fn::Select/Fn::Split over an ECR Repository Arn GetAtt + Ref to the repo).`);
 			const accountIdHint = pseudoParameters ? ` (likely \${AWS::AccountId}, which ${getEmbedConfig().productName} cannot derive without --from-state or STS)` : ` (${getEmbedConfig().productName} could not derive AWS pseudo parameters because stack.region was undefined)`;
-			throw new LocalInvokeResolutionError(`Lambda '${logicalId}' in ${stackName} has an Fn::Join Code.ImageUri that ${getEmbedConfig().cliName} invoke cannot resolve${accountIdHint}. Workarounds: deploy first and run with --from-state, or pin a fully-literal public image URI.`);
+			throw new LocalInvokeResolutionError(`Lambda '${logicalId}' in ${stackName} has an Fn::Join Code.ImageUri that ${getEmbedConfig().cliName} cannot resolve${accountIdHint}. Workarounds: deploy first and run with --from-state, or pin a fully-literal public image URI.`);
 		}
 	}
 }
@@ -992,7 +1010,7 @@ function extractImageLambdaProperties(args) {
 		const first = arches[0];
 		if (first === "arm64") architecture = "arm64";
 		else if (first === "x86_64") architecture = "x86_64";
-		else throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has unsupported Architectures value '${String(first)}'. ${getEmbedConfig().cliName} invoke supports x86_64 and arm64.`);
+		else throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has unsupported Architectures value '${String(first)}'. ${getEmbedConfig().cliName} supports x86_64 and arm64.`);
 	}
 	return {
 		kind: "image",
@@ -1534,12 +1552,13 @@ function resolveImageUri(value, logicalId, stackName, resources, region, imageCo
 	if (typeof sub === "string" && sub.length > 0) return imageContext ? substituteImagePlaceholders(sub, resources, imageContext) : sub;
 	if (Array.isArray(sub) && typeof sub[0] === "string") return imageContext ? substituteImagePlaceholders(sub[0], resources, imageContext) : sub[0];
 	if ("Fn::Join" in obj) {
-		const joinResolved = tryResolveImageFnJoin(value, resources, imageContext ?? (() => {
+		const context = imageContext ?? (() => {
 			const pseudoParameters = derivePseudoParametersFromRegion(region);
 			return pseudoParameters ? { pseudoParameters } : void 0;
-		})());
+		})();
+		const joinResolved = tryResolveImageFnJoin(value, resources, context);
 		if (joinResolved.kind === "resolved") return joinResolved.uri;
-		if (joinResolved.kind === "needs-state") throw new AgentCoreResolutionError(`AgentCore Runtime '${logicalId}' in ${stackName} references same-stack ECR repository '${joinResolved.repoLogicalId}' via Fn::Join. ${getEmbedConfig().cliName} invoke-agentcore cannot resolve the repository URI without state — pass --from-cfn-stack to load the deployed stack state, build via Runtime.fromAsset, or pin a literal / imported ECR image URI.`);
+		if (joinResolved.kind === "needs-state") throw new AgentCoreResolutionError(`AgentCore Runtime '${logicalId}' in ${stackName} references same-stack ECR repository '${joinResolved.repoLogicalId}' via Fn::Join. ${getEmbedConfig().cliName} cannot resolve the repository URI without state — ` + formatStateRemedy(context) + ", build via Runtime.fromAsset, or pin a literal / imported ECR image URI.");
 	}
 }
 
@@ -3471,10 +3490,27 @@ var AssemblyReader = class {
 	}
 	/**
 	* Read a pre-synthesized Cloud Assembly directory (no subprocess).
+	*
+	* `failOnMissingContext: false` matches CDK CLI's own behavior for
+	* `cdk deploy --app cdk.out`. CDK CLI's `cxapp/exec.js` bypasses
+	* `Toolkit.fromAssemblyDirectory()` entirely on this path and builds
+	* the assembly via `@aws-cdk/cloud-assembly-api`'s `CloudAssembly`
+	* directly, which does NOT enforce a missing-context check; then
+	* `cxapp/cloud-executable.js` attempts a single context-provider
+	* resolve, and if no progress is made it returns the assembly as-is
+	* with `manifest.missing` still populated. The strict default that
+	* `fromAssemblyDirectory()` carries is a toolkit-lib decision aimed
+	* at programmatic deploy callers, not parity with CDK CLI semantics.
+	*
+	* cdk-local's needs are looser still: we only read the synthesized
+	* template, and under `--from-cfn-stack` runtime values come from
+	* the deployed CFN stack anyway. Refusing here just makes the
+	* pre-synth flow unusable for any app that relies on context
+	* lookups (SSM / VPC / AMI / etc.), without any safety benefit.
 	*/
 	async readFromDirectory(assemblyDir) {
 		const toolkit = new Toolkit({ ioHost: new CdklIoHost() });
-		const source = await toolkit.fromAssemblyDirectory(assemblyDir);
+		const source = await toolkit.fromAssemblyDirectory(assemblyDir, { failOnMissingContext: false });
 		const cached = await toolkit.synth(source);
 		try {
 			return cached.cloudAssembly.stacks.map((stack) => mapStackArtifact(stack));
@@ -3823,6 +3859,7 @@ var CfnLocalStateProvider = class {
 	agentCoreControlClient;
 	clientOptions;
 	disposed = false;
+	lastLoadError;
 	constructor(opts) {
 		this.cfnStackName = opts.cfnStackName;
 		this.region = opts.region;
@@ -3966,10 +4003,12 @@ var CfnLocalStateProvider = class {
 		if (this.disposed) throw new Error("CfnLocalStateProvider used after dispose()");
 		const logger = getLogger();
 		const client = this.getClient();
+		this.lastLoadError = void 0;
 		let resourceMap;
 		try {
 			resourceMap = buildResourceStateMap(await fetchAllStackResources(client, this.cfnStackName));
 		} catch (err) {
+			this.lastLoadError = `ListStackResources(${this.cfnStackName}) failed: ${formatAwsErrorForWarn(err)} (region='${this.region}')`;
 			logger.warn(`${this.label}: ListStackResources(${this.cfnStackName}) failed: ${formatAwsErrorForWarn(err)}. Was the stack deployed in region '${this.region}'? Falling back.`);
 			return;
 		}
@@ -3991,6 +4030,24 @@ var CfnLocalStateProvider = class {
 		};
 	}
 	/**
+	* Return the failure detail captured by the most recent failed
+	* `load()` call, or `undefined` when the latest call succeeded /
+	* was never made. Surfaces the same `ListStackResources(<name>) failed: ...`
+	* text the warn-logger emits so downstream resolvers can embed it
+	* verbatim in their error and avoid the misleading "pass
+	* --from-cfn-stack" hint when the user already passed it.
+	*
+	* Throws after `dispose()` to keep parity with the other operational
+	* entry points on this class — a post-dispose caller is a programming
+	* bug, and surfacing it loudly is cheaper than silently returning a
+	* stale captured message after the provider's state is conceptually
+	* gone.
+	*/
+	getLastLoadError() {
+		if (this.disposed) throw new Error("CfnLocalStateProvider used after dispose()");
+		return this.lastLoadError;
+	}
+	/**
 	* Build a `CrossStackResolver` that resolves `Fn::ImportValue` via
 	* `cloudformation:ListExports`. `Fn::GetStackOutput` is rejected here
 	* — it has no CFn-side equivalent, and the user-visible error message
@@ -5923,10 +5980,10 @@ function parseContainerImage(raw, containerName, taskLogicalId, resources, _stac
 	if (getAttImage) return classifyResolvedImage(getAttImage);
 	const joinResolved = tryResolveImageFnJoin(raw, resources, context);
 	if (joinResolved.kind === "resolved") return classifyResolvedImage(joinResolved.uri);
-	if (joinResolved.kind === "needs-state") throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' references same-stack ECR repository '${joinResolved.repoLogicalId}' via Fn::Join. ${getEmbedConfig().cliName} run-task cannot resolve the repository URI without state — pass --from-cfn-stack to load the deployed stack state, build via ContainerImage.fromAsset, or pin a public image.`);
-	if (joinResolved.kind === "unsupported-join") throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' has an unsupported Fn::Join Image shape: ${joinResolved.reason}. ${getEmbedConfig().cliName} run-task recognizes the canonical CDK 2.x ContainerImage.fromEcrRepository Fn::Join shape (delimiter "" with nested Fn::Select/Fn::Split over an ECR Repository Arn GetAtt + Ref to the repo).`);
+	if (joinResolved.kind === "needs-state") throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' references same-stack ECR repository '${joinResolved.repoLogicalId}' via Fn::Join. ${getEmbedConfig().cliName} cannot resolve the repository URI without state — ` + formatStateRemedy(context) + ", build via ContainerImage.fromAsset, or pin a public image.");
+	if (joinResolved.kind === "unsupported-join") throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' has an unsupported Fn::Join Image shape: ${joinResolved.reason}. ${getEmbedConfig().cliName} recognizes the canonical CDK 2.x ContainerImage.fromEcrRepository Fn::Join shape (delimiter "" with nested Fn::Select/Fn::Split over an ECR Repository Arn GetAtt + Ref to the repo).`);
 	const flat = extractImageString(raw);
-	if (!flat) throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' has an unparseable Image property. ${getEmbedConfig().cliName} run-task v1 supports flat string images, single-key Fn::Sub bodies, and CDK-asset Image references.`);
+	if (!flat) throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' has an unparseable Image property. ${getEmbedConfig().cliName} supports flat string images, single-key Fn::Sub bodies, and CDK-asset Image references.`);
 	if (flat.includes("cdk-hnb659fds-container-assets-")) {
 		const hashMatch = /:([a-f0-9]{8,})$/.exec(flat);
 		const out = { kind: "cdk-asset" };
@@ -5936,9 +5993,9 @@ function parseContainerImage(raw, containerName, taskLogicalId, resources, _stac
 	const substituted = substituteImagePlaceholders(flat, resources, context);
 	if (substituted.includes("${")) {
 		const unresolvedRepoRef = findUnresolvedEcrRepositoryRef(substituted, resources);
-		if (unresolvedRepoRef) throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' references same-stack ECR repository '${unresolvedRepoRef}'. ${getEmbedConfig().cliName} run-task v1 cannot resolve the repository URI without state — pass --from-cfn-stack to load the deployed stack state, build via ContainerImage.fromAsset, or pin a public image.`);
+		if (unresolvedRepoRef) throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' references same-stack ECR repository '${unresolvedRepoRef}'. ${getEmbedConfig().cliName} cannot resolve the repository URI without state — ` + formatStateRemedy(context) + ", build via ContainerImage.fromAsset, or pin a public image.");
 		if (substituted.includes("AWS::")) throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' has an Image that references AWS pseudo parameters (${substituted}). ${getEmbedConfig().productName} could not resolve them: confirm AWS credentials are configured so STS GetCallerIdentity succeeds, and that --region / AWS_REGION names the target region. Workaround: build the image locally (ContainerImage.fromAsset) or pin a public image.`);
-		throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' has an Image with unresolved \${...} placeholders (${substituted}). ${getEmbedConfig().cliName} run-task v1 only resolves AWS pseudo parameters and same-stack AWS::ECR::Repository refs.`);
+		throw new EcsTaskResolutionError(`Container '${containerName}' in task '${taskLogicalId}' has an Image with unresolved \${...} placeholders (${substituted}). ${getEmbedConfig().cliName} only resolves AWS pseudo parameters and same-stack AWS::ECR::Repository refs.`);
 	}
 	const ecrMatch = /^(\d{12})\.dkr\.ecr\.([^.]+)\.amazonaws\.com(?:\.cn)?\//.exec(substituted);
 	if (ecrMatch) return {
@@ -6043,8 +6100,8 @@ function parseVolume(raw, idx, taskLogicalId, subContext) {
 	const v = raw;
 	const name = pickString(v["Name"]);
 	if (!name) throw new EcsTaskResolutionError(`Task '${taskLogicalId}' Volumes[${idx}] has no Name.`);
-	if (v["EFSVolumeConfiguration"]) throw new EcsTaskResolutionError(`Task '${taskLogicalId}' Volumes[${idx}] '${name}' uses EFSVolumeConfiguration, which ${getEmbedConfig().cliName} run-task cannot proxy locally. Workaround: bind-mount a local directory at the same containerPath via Host: { SourcePath: '<local-path>' }, or override at runtime via --env-vars semantics for a Phase 2 follow-up.`);
-	if (v["FSxWindowsFileServerVolumeConfiguration"]) throw new EcsTaskResolutionError(`Task '${taskLogicalId}' Volumes[${idx}] '${name}' uses FSxWindowsFileServerVolumeConfiguration, which ${getEmbedConfig().cliName} run-task cannot proxy locally.`);
+	if (v["EFSVolumeConfiguration"]) throw new EcsTaskResolutionError(`Task '${taskLogicalId}' Volumes[${idx}] '${name}' uses EFSVolumeConfiguration, which ${getEmbedConfig().cliName} cannot proxy locally. Workaround: bind-mount a local directory at the same containerPath via Host: { SourcePath: '<local-path>' }, or override at runtime via --env-vars semantics for a Phase 2 follow-up.`);
+	if (v["FSxWindowsFileServerVolumeConfiguration"]) throw new EcsTaskResolutionError(`Task '${taskLogicalId}' Volumes[${idx}] '${name}' uses FSxWindowsFileServerVolumeConfiguration, which ${getEmbedConfig().cliName} cannot proxy locally.`);
 	const dockerCfg = v["DockerVolumeConfiguration"];
 	if (dockerCfg && typeof dockerCfg === "object") {
 		const d = dockerCfg;
@@ -17634,10 +17691,10 @@ function extractImageUri(value, logicalId, stackName, resources, region) {
 			const pseudoParameters = derivePseudoParametersFromRegion(region);
 			const joinResolved = tryResolveImageFnJoin(value, resources, pseudoParameters ? { pseudoParameters } : void 0);
 			if (joinResolved.kind === "resolved") return joinResolved.uri;
-			if (joinResolved.kind === "needs-state") throw new Error(`Lambda '${logicalId}' in ${stackName} references same-stack ECR repository '${joinResolved.repoLogicalId}' via Fn::Join. ${getEmbedConfig().cliName} start-api cannot resolve the repository URI without state — deploy the stack first, rebuild via lambda.DockerImageCode.fromImageAsset, or pin a public image.`);
-			if (joinResolved.kind === "unsupported-join") throw new Error(`Lambda '${logicalId}' in ${stackName} has an unsupported Fn::Join Code.ImageUri shape: ${joinResolved.reason}. ${getEmbedConfig().cliName} start-api recognizes the canonical CDK 2.x lambda.DockerImageCode.fromEcr Fn::Join shape (delimiter "" with nested Fn::Select/Fn::Split over an ECR Repository Arn GetAtt + Ref to the repo).`);
+			if (joinResolved.kind === "needs-state") throw new Error(`Lambda '${logicalId}' in ${stackName} references same-stack ECR repository '${joinResolved.repoLogicalId}' via Fn::Join. ${getEmbedConfig().cliName} cannot resolve the repository URI without state — deploy the stack first, rebuild via lambda.DockerImageCode.fromImageAsset, or pin a public image.`);
+			if (joinResolved.kind === "unsupported-join") throw new Error(`Lambda '${logicalId}' in ${stackName} has an unsupported Fn::Join Code.ImageUri shape: ${joinResolved.reason}. ${getEmbedConfig().cliName} recognizes the canonical CDK 2.x lambda.DockerImageCode.fromEcr Fn::Join shape (delimiter "" with nested Fn::Select/Fn::Split over an ECR Repository Arn GetAtt + Ref to the repo).`);
 			const accountIdHint = pseudoParameters ? ` (likely \${AWS::AccountId}, which ${getEmbedConfig().binaryName} cannot derive without a state source or STS)` : ` (${getEmbedConfig().binaryName} could not derive AWS pseudo parameters because stack.region was undefined)`;
-			throw new Error(`Lambda '${logicalId}' in ${stackName} has an Fn::Join Code.ImageUri that ${getEmbedConfig().cliName} start-api cannot resolve${accountIdHint}. Workarounds: deploy first and run with a state-source flag (e.g. --from-cfn-stack or a host-provided extension), or pin a fully-literal public image URI.`);
+			throw new Error(`Lambda '${logicalId}' in ${stackName} has an Fn::Join Code.ImageUri that ${getEmbedConfig().cliName} cannot resolve${accountIdHint}. Workarounds: deploy first and run with a state-source flag (e.g. --from-cfn-stack or a host-provided extension), or pin a fully-literal public image URI.`);
 		}
 	}
 }
@@ -18811,6 +18868,9 @@ async function buildAgentCoreImageContext(candidate, stateProvider, options) {
 			if (Object.keys(ssm.values).length > 0) context.stateParameters = ssm.values;
 			if (ssm.secureStringLogicalIds.length > 0) context.stateSensitiveParameters = ssm.secureStringLogicalIds;
 		}
+	} else {
+		const loadError = stateProvider.getLastLoadError?.();
+		if (loadError) context.stateLoadFailureMessage = loadError;
 	}
 	return {
 		context,
@@ -20355,6 +20415,10 @@ async function buildEcsImageResolutionContext$1(candidate, stateProvider, option
 	if (stateProvider && wantsState) {
 		const loaded = await stateProvider.load(candidate.stackName, candidate.region);
 		if (loaded) ctx.stateResources = loaded.resources;
+		else {
+			const loadError = stateProvider.getLastLoadError?.();
+			if (loadError) ctx.stateLoadFailureMessage = loadError;
+		}
 		if (needs.needsEnvOrSecretSubstitution && stateProvider.resolveTemplateSsmParameters) {
 			const ssmParameters = await stateProvider.resolveTemplateSsmParameters(candidate.template);
 			if (Object.keys(ssmParameters.values).length > 0) ctx.stateParameters = ssmParameters.values;
@@ -23258,7 +23322,18 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 	let frontDoorServers = [];
 	let frontDoorByService = /* @__PURE__ */ new Map();
 	let frontDoorLambdaRunners = [];
+	let watcher;
+	let reloadChain = Promise.resolve();
 	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 Promise.allSettled(perTarget.map(async (pt) => {
 			if (pt.controller) await pt.controller.shutdown();
 			else {
@@ -23369,8 +23444,41 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		} else logger.info(`Service(s) running: ${frontDoorLambdaRunners.length} Lambda target(s) behind the ALB front-door.`);
 		logEndpointsBanner(perTarget, frontDoorServers, logger);
 		logger.info("Press ^C to shut down.");
-		if (perTarget.length > 0) await Promise.all(perTarget.map((pt) => pt.controller.waitForShutdown()));
-		else await new Promise(() => {});
+		if (options.watch === true && strategy.supportsWatch === true) {
+			const watchRoot = process.cwd();
+			const { ignored, shouldTrigger, excludePatterns } = createWatchPredicates({
+				watchRoot,
+				output: options.output,
+				watchConfig: resolveWatchConfig()
+			});
+			watcher = createFileWatcher({
+				paths: [watchRoot],
+				ignored,
+				shouldTrigger,
+				onChange: () => {
+					logger.info("Detected source change; reloading service(s)...");
+					reloadChain = reloadChain.then(() => reloadAllServices({
+						perTarget,
+						synthesizer,
+						synthOpts,
+						strategy,
+						resolvedTargets,
+						cloudMapIndexByStack,
+						options,
+						discovery,
+						skipPull,
+						extraStateProviders,
+						profileCredsFile,
+						frontDoorByService,
+						logger
+					})).catch((err) => {
+						logger.error(`reloadAllServices threw: ${err instanceof Error ? err.message : String(err)}`);
+					});
+				}
+			});
+			logger.info(`Watching ${watchRoot} for source changes (excluding ${excludePatterns.join(", ")}).`);
+		}
+		await new Promise(() => {});
 	} finally {
 		if (sigintHandler) {
 			process.off("SIGINT", sigintHandler);
@@ -23379,6 +23487,87 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		await cleanup();
 	}
 }
+/**
+* Phase 1 of issue #214 — refuse a `--watch` run when the resolved service's
+* effective replica count (`min(template DesiredCount, --max-tasks)`) is > 1.
+* The Phase 1 reload pathway tears the single replica down before booting the
+* new one; multi-replica services would therefore drop multiple connections at
+* once and lose any in-memory state. Multi-replica rolling reload is Phase 2
+* of issue #214. Exposed for the unit test that locks the gating logic
+* (the integ test only covers the single-replica happy path).
+*
+* @internal
+*/
+function assertSingleReplicaForWatch(service, options) {
+	if (options.watch !== true) return;
+	const effective = computeReplicaCount(service.desiredCount, options.maxTasks);
+	if (effective > 1) throw new LocalStartServiceError(`--watch is single-replica only in v1; service '${service.serviceName}' resolves to ${effective} replica(s) (template DesiredCount=${service.desiredCount}, --max-tasks=${options.maxTasks}). Lower --max-tasks to 1, drop the DesiredCount in your CDK code, or drop --watch. Multi-replica rolling reload is Phase 2 of issue #214.`);
+}
+/**
+* Phase 1 of issue #214 — single-replica rebuild-on-change reload cycle.
+* Mirrors start-api's `reloadAllServers` shape but per-ECS-service:
+*
+*   1. Re-runs `synthesizer.synthesize(synthOpts)` once (failure → warn +
+*      keep every replica serving).
+*   2. Re-runs `strategy.resolveBoots(stacks, resolvedTargets)` so a
+*      target that disappears from the CDK code is detected (warn + keep
+*      previous).
+*   3. Refreshes `cloudMapIndexByStack` from the new stacks so a peer
+*      service's namespace / discovery-name rename is picked up by the
+*      next replica's Cloud Map publish.
+*   4. Per-target: tear the existing controller down, boot a fresh one
+*      against the new stacks. A per-target boot failure logs warn and
+*      leaves that target dark until the next save with a clean boot.
+*
+* Phase 1 trade-off: each target's replica briefly stops (between old
+* `controller.shutdown()` and new `bootOneTarget()` finishing). Phase 2 of
+* #214 swaps that for a rolling deploy across multiple replicas.
+*/
+async function reloadAllServices(args) {
+	const { perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, logger } = args;
+	let stacks;
+	try {
+		({stacks} = await synthesizer.synthesize(synthOpts));
+	} catch (err) {
+		logger.warn(`cdk synth failed during reload; keeping previous version. (${err instanceof Error ? err.message : String(err)})`);
+		return;
+	}
+	const { boots: newBoots, warnings } = strategy.resolveBoots(stacks, resolvedTargets);
+	for (const w of warnings) logger.warn(w);
+	const newBootByTarget = new Map(newBoots.map((b) => [b.target, b]));
+	cloudMapIndexByStack.clear();
+	for (const stack of stacks) {
+		const index = buildCloudMapIndex(stack);
+		cloudMapIndexByStack.set(stack.stackName, index);
+		for (const w of index.warnings) logger.warn(w);
+	}
+	for (const pt of perTarget) {
+		const newBoot = newBootByTarget.get(pt.boot.target);
+		if (!newBoot) {
+			logger.warn(`Reload: target '${pt.boot.target}' no longer resolves to a service in the synthesized app; keeping the previous replica serving.`);
+			continue;
+		}
+		const oldController = pt.controller;
+		try {
+			if (oldController) await oldController.shutdown();
+		} catch (err) {
+			logger.warn(`Reload: shutdown of previous '${pt.boot.target}' controller failed (${err instanceof Error ? err.message : String(err)}); attempting re-boot anyway.`);
+		}
+		const newRunState = createServiceRunState();
+		let newController;
+		try {
+			newController = await bootOneTarget(newBoot, newRunState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService.get(newBoot.target), strategy.suppressLoadBalancerWarning === true);
+		} catch (err) {
+			if (err instanceof LocalStartServiceError) logger.error(`Reload of '${pt.boot.target}' was rejected: ${err.message}`);
+			else logger.error(`Reload: re-boot of '${pt.boot.target}' failed (${err instanceof Error ? err.message : String(err)}). The previous replica was torn down; save again with a clean boot to re-start it, or ^C and re-run start-service.`);
+			await Promise.allSettled(newRunState.replicas.map((r) => cleanupEcsRun(r.state, { keepRunning: false }).catch(() => void 0)));
+			continue;
+		}
+		pt.runState = newRunState;
+		pt.controller = newController;
+	}
+	logger.info("Reload complete.");
+}
 async function bootOneTarget(boot, runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning) {
 	const candidate = pickCandidateStack(parseEcsTarget(boot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
@@ -23394,6 +23583,7 @@ async function runOneTarget(boot, runState, stacks, options, discovery, skipPull
 	const imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
 	const service = resolveEcsServiceTarget(target, stacks, imageContext, { suppressLoadBalancerWarning });
 	logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
+	assertSingleReplicaForWatch(service, options);
 	if (service.serviceConnect) logger.info(`Service Connect: namespace='${service.serviceConnect.namespaceName}', ${service.serviceConnect.services.length} service(s) registered for peer discovery.`);
 	if (service.serviceRegistries.length > 0) logger.info(`Cloud Map: ${service.serviceRegistries.length} ServiceRegistry binding(s).`);
 	const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === service.stack.stackName) ?? service.stack);
@@ -23714,6 +23904,10 @@ async function buildEcsImageResolutionContext(target, stacks, options, stateProv
 	if (stateProvider && wantsState) {
 		const loaded = await stateProvider.load(candidate.stackName, candidate.region);
 		if (loaded) ctx.stateResources = loaded.resources;
+		else {
+			const loadError = stateProvider.getLastLoadError?.();
+			if (loadError) ctx.stateLoadFailureMessage = loadError;
+		}
 		if (needs.needsEnvOrSecretSubstitution && stateProvider.resolveTemplateSsmParameters) {
 			const ssmParameters = await stateProvider.resolveTemplateSsmParameters(candidate.template);
 			if (Object.keys(ssmParameters.values).length > 0) ctx.stateParameters = ssmParameters.values;
@@ -23845,6 +24039,73 @@ function addCommonEcsServiceOptions(cmd) {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/commands/local-start-service.ts
+/**
+* `cdkl start-service` strategy — a pure ECS replica runner. It picks
+* `AWS::ECS::Service` targets and boots each with NO front-door (the ALB
+* front-door is its own command, `cdkl start-alb`). This keeps `start-service`
+* a leaf compute runner, symmetric with `invoke` / `run-task`.
+*
+* `supportsWatch: true` opts this strategy into the emulator's `--watch`
+* reload pathway (Phase 1 of issue #214 — single-replica rebuild-on-change).
+* `start-alb`'s strategy intentionally does NOT set this so a `--watch` flag
+* never leaks into the ALB-front-door path (Phase 3).
+*/
+function serviceStrategy() {
+	return {
+		pickEntries: (stacks) => listTargets(stacks).ecsServices,
+		pickerMessage: "Select one or more ECS services to run",
+		pickerNoun: "ECS services",
+		onMissing: () => new LocalStartServiceError(`${getEmbedConfig().cliName} start-service requires at least one <target>. Pass one or more service paths like 'Stack/Orders' 'Stack/Frontend', or run it in a TTY to pick interactively.`),
+		resolveBoots: (_stacks, chosenTargets) => ({
+			boots: chosenTargets.map((target) => ({ target })),
+			warnings: []
+		}),
+		lbPortOverrides: {},
+		supportsWatch: true
+	};
+}
+/**
+* `cdkl start-service <Stack/Service>` — Phase 2 of #262. Spins up
+* `DesiredCount` task replicas locally (clamped by `--max-tasks`) using the
+* existing `ecs-task-runner` per replica. Long-running; ^C cleans every replica
+* + sidecar + shared network. Pure compute: to put a local ALB front-door in
+* front of an ALB-fronted service, use `cdkl start-alb`.
+*/
+function createLocalStartServiceCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	const cmd = new Command("start-service").description(`Run one or more AWS::ECS::Service resources locally as a long-running emulator. Spins up DesiredCount task replicas per service (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as \`${getEmbedConfig().cliName} run-task\`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Each <target> accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix. When two or more <target>s are supplied, every service is booted into a shared Cloud Map / Service Connect registry so peer services discover each other via docker --add-host overlay. Omit <targets> in an interactive terminal to multi-select the services from a list. To put a local ALB front-door in front of an ALB-fronted service, use \`${getEmbedConfig().cliName} start-alb\` instead.`).argument("[targets...]", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ECS::Service resources to run (omit to multi-select interactively in a TTY)").action(withErrorHandling(async (targets, options) => {
+		await runEcsServiceEmulator(targets, options, serviceStrategy(), opts.extraStateProviders);
+	}));
+	addStartServiceSpecificOptions(cmd);
+	return addCommonEcsServiceOptions(cmd);
+}
+/**
+* Register the option block that `cdkl start-service` adds on top of the
+* shared {@link addCommonEcsServiceOptions} ECS-service common block — the
+* flags that only make sense for a pure-compute service emulator (no front
+* door). Shared between `cdkl start-service` and any host CLI (e.g. cdkd's
+* `local start-service`) that wraps {@link runEcsServiceEmulator} with the
+* {@link serviceStrategy}, so adding or renaming a `start-service`-only flag
+* here propagates to every embedder without duplicate `.addOption(...)`
+* blocks.
+*
+* Calling order only affects `--help` presentation (Commander parses
+* insertion-order-independent). The host-CLI convention is host-specific
+* options first, then this helper, then {@link addCommonEcsServiceOptions}
+* — host flags / start-service flags / common flags grouped in three
+* `--help` clusters. Chainable: returns `cmd`.
+*
+* `--watch` is intentionally NOT in the shared
+* {@link addCommonEcsServiceOptions} block: `start-alb --watch` is not yet
+* implemented (Phase 3 of issue #214), and the shared block must not
+* advertise a flag one of its consumers does not honor.
+*/
+function addStartServiceSpecificOptions(cmd) {
+	return cmd.addOption(new Option("--host-port <containerPort=hostPort...>", "Publish a container port on a specific host port (e.g. 80=8080); repeatable. Default: host port == container port. Use this on macOS to map a privileged container port (< 1024) to a non-privileged host port and avoid the Docker Desktop admin-password prompt. (Single-replica services only — multi-replica services do not publish host ports.)")).addOption(new Option("--watch", "Hot-reload: re-synth + re-resolve every booted service and replace its single replica when the CDK app's source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). Single-replica services only in v1 — a service with effective replica count > 1 errors out (multi-replica rolling deploy is Phase 2 of issue #214). Off by default; the previous replica keeps serving when synth fails mid-reload.").default(false));
+}
+
 //#endregion
 //#region src/local/elb-front-door-resolver.ts
 /**
@@ -24790,5 +25051,5 @@ function addListSpecificOptions(cmd) {
 }
 
 //#endregion
-export { pickResponseTemplate as $, substituteAgainstState as $t, createFileWatcher as A, AgentCoreResolutionError as An, MCP_PATH as At, resolveServiceIntegrationParameters as B, SUPPORTED_CODE_RUNTIMES as Bt, addInvokeAgentCoreSpecificOptions as C, pickRefLogicalId as Cn, isFunctionUrlOacFronted as Ct, createWatchPredicates as D, AGENTCORE_HTTP_PROTOCOL as Dn, A2A_PATH as Dt, createLocalStartApiCommand as E, AGENTCORE_AGUI_PROTOCOL as En, A2A_CONTAINER_PORT as Et, filterRoutesByApiIdentifiers as F, tryResolveImageFnJoin as Fn, signAgentCoreInvocation as Ft, invokeRequestAuthorizer as G, addInvokeSpecificOptions as Gt, buildMethodArn as H, computeCodeImageTag as Ht, groupRoutesByServer as I, LocalInvokeBuildError as In, AGENTCORE_SESSION_ID_HEADER as It, translateLambdaResponse as J, buildContainerImage as Jt, invokeTokenAuthorizer as K, createLocalInvokeCommand as Kt, readMtlsMaterialsFromDisk as L, LocalStartServiceError as Ln, invokeAgentCore as Lt, buildStageMap as M, resolveAgentCoreTarget as Mn, mcpInvokeOnce as Mt, availableApiIdentifiers as N, derivePseudoParametersFromRegion as Nn, parseSseForJsonRpc as Nt, resolveApiTargetSubset as O, AGENTCORE_MCP_PROTOCOL as On, a2aInvokeOnce as Ot, filterRoutesByApiIdentifier as P, substituteImagePlaceholders as Pn, AGENTCORE_SIGV4_SERVICE as Pt, evaluateResponseParameters as Q, EcsTaskResolutionError as Qt, startApiServer as R, withErrorHandling as Rn, waitForAgentCorePing as Rt, createLocalRunTaskCommand as S, discoverRoutes as Sn, buildCorsConfigFromCloudFrontChain as St, addStartApiSpecificOptions as T, AGENTCORE_A2A_PROTOCOL as Tn, invokeAgentCoreWs as Tt, computeRequestIdentityHash as U, renderCodeDockerfile as Ut, defaultCredentialsLoader as V, buildAgentCoreCodeImage as Vt, evaluateCachedLambdaPolicy as W, toCmdArgv as Wt, buildHttpApiV2Event as X, resolveRuntimeFileExtension as Xt, applyAuthorizerOverlay as Y, resolveRuntimeCodeMountPath as Yt, buildRestV1Event as Z, resolveRuntimeImage as Zt, runEcsServiceEmulator as _, countTargets as _n, verifyJwtAuthorizer as _t, albStrategy as a, LocalStateSourceError as an, bufferToBody as at, getContainerNetworkIp as b, discoverWebSocketApisOrThrow as bn, applyCorsResponseHeaders as bt, resolveAlbTarget as c, rejectExplicitCfnStackWithMultipleStacks as cn, handleConnectionsRequest as ct, MAX_TASKS_SUBNET_RANGE_CAP as d, resolveCfnStackName as dn, buildDisconnectEvent as dt, substituteAgainstStateAsync as en, selectIntegrationResponse as et, addCommonEcsServiceOptions as f, CfnLocalStateProvider as fn, buildMessageEvent as ft, resolveSharedSidecarCredentials as g, resolveSingleTarget as gn, verifyCognitoJwt as gt, parseRestartPolicy as h, resolveWatchConfig as hn, createJwksCache as ht, addAlbSpecificOptions as i, materializeLayerFromArn as in, probeHostGatewaySupport as it, attachStageContext as j, pickAgentCoreCandidateStack as jn, MCP_PROTOCOL_VERSION as jt, createAuthorizerCache as k, AGENTCORE_RUNTIME_TYPE as kn, MCP_CONTAINER_PORT as kt, isApplicationLoadBalancer as l, resolveCfnFallbackRegion as ln, parseConnectionsPath as lt, parseMaxTasks as m, resolveSsmParameters as mn, buildJwksUrlFromIssuer as mt, createLocalListCommand as n, substituteEnvVarsFromStateAsync as nn, VtlEvaluationError as nt, createLocalStartAlbCommand as o, createLocalStateProvider as on, ConnectionRegistry as ot, buildEcsImageResolutionContext as p, collectSsmParameterRefs as pn, buildCognitoJwksUrl as pt, matchRoute as q, architectureToPlatform as qt, formatTargetListing as r, resolveEnvVars as rn, HOST_GATEWAY_MIN_VERSION as rt, parseLbPortOverrides as s, isCfnFlagPresent as sn, buildMgmtEndpointEnvUrl as st, addListSpecificOptions as t, substituteEnvVarsFromState as tn, tryParseStatus as tt, resolveAlbFrontDoor as u, resolveCfnRegion as un, buildConnectEvent as ut, buildCloudMapIndex as v, listTargets as vn, verifyJwtViaDiscovery as vt, createLocalInvokeAgentCoreCommand as w, resolveLambdaArnIntrinsic as wn, matchPreflight as wt, addRunTaskSpecificOptions as x, parseSelectionExpressionPath as xn, buildCorsConfigByApiId as xt, CloudMapRegistry as y, discoverWebSocketApis as yn, attachAuthorizers as yt, resolveSelectionExpression as z, downloadAndExtractS3Bundle as zt };
-//# sourceMappingURL=local-list-JDGfdnip.js.map
+export { buildHttpApiV2Event as $, resolveRuntimeFileExtension as $t, createWatchPredicates as A, AGENTCORE_HTTP_PROTOCOL as An, A2A_PATH as At, readMtlsMaterialsFromDisk as B, LocalInvokeBuildError as Bn, invokeAgentCore as Bt, getContainerNetworkIp as C, discoverWebSocketApisOrThrow as Cn, applyCorsResponseHeaders as Ct, createLocalInvokeAgentCoreCommand as D, resolveLambdaArnIntrinsic as Dn, matchPreflight as Dt, addInvokeAgentCoreSpecificOptions as E, pickRefLogicalId as En, isFunctionUrlOacFronted as Et, buildStageMap as F, resolveAgentCoreTarget as Fn, mcpInvokeOnce as Ft, buildMethodArn as G, computeCodeImageTag as Gt, resolveSelectionExpression as H, downloadAndExtractS3Bundle as Ht, availableApiIdentifiers as I, derivePseudoParametersFromRegion as In, parseSseForJsonRpc as It, invokeRequestAuthorizer as J, addInvokeSpecificOptions as Jt, computeRequestIdentityHash as K, renderCodeDockerfile as Kt, filterRoutesByApiIdentifier as L, formatStateRemedy as Ln, AGENTCORE_SIGV4_SERVICE as Lt, createAuthorizerCache as M, AGENTCORE_RUNTIME_TYPE as Mn, MCP_CONTAINER_PORT as Mt, createFileWatcher as N, AgentCoreResolutionError as Nn, MCP_PATH as Nt, addStartApiSpecificOptions as O, AGENTCORE_A2A_PROTOCOL as On, invokeAgentCoreWs as Ot, attachStageContext as P, pickAgentCoreCandidateStack as Pn, MCP_PROTOCOL_VERSION as Pt, applyAuthorizerOverlay as Q, resolveRuntimeCodeMountPath as Qt, filterRoutesByApiIdentifiers as R, substituteImagePlaceholders as Rn, signAgentCoreInvocation as Rt, CloudMapRegistry as S, discoverWebSocketApis as Sn, attachAuthorizers as St, createLocalRunTaskCommand as T, discoverRoutes as Tn, buildCorsConfigFromCloudFrontChain as Tt, resolveServiceIntegrationParameters as U, SUPPORTED_CODE_RUNTIMES as Ut, startApiServer as V, waitForAgentCorePing as Vt, defaultCredentialsLoader as W, buildAgentCoreCodeImage as Wt, matchRoute as X, architectureToPlatform as Xt, invokeTokenAuthorizer as Y, createLocalInvokeCommand as Yt, translateLambdaResponse as Z, buildContainerImage as Zt, parseMaxTasks as _, resolveSsmParameters as _n, buildJwksUrlFromIssuer as _t, albStrategy as a, substituteEnvVarsFromStateAsync as an, VtlEvaluationError as at, runEcsServiceEmulator as b, countTargets as bn, verifyJwtAuthorizer as bt, resolveAlbTarget as c, LocalStateSourceError as cn, bufferToBody as ct, addStartServiceSpecificOptions as d, rejectExplicitCfnStackWithMultipleStacks as dn, handleConnectionsRequest as dt, resolveRuntimeImage as en, buildRestV1Event as et, createLocalStartServiceCommand as f, resolveCfnFallbackRegion as fn, parseConnectionsPath as ft, buildEcsImageResolutionContext as g, collectSsmParameterRefs as gn, buildCognitoJwksUrl as gt, addCommonEcsServiceOptions as h, CfnLocalStateProvider as hn, buildMessageEvent as ht, addAlbSpecificOptions as i, substituteEnvVarsFromState as in, tryParseStatus as it, resolveApiTargetSubset as j, AGENTCORE_MCP_PROTOCOL as jn, a2aInvokeOnce as jt, createLocalStartApiCommand as k, AGENTCORE_AGUI_PROTOCOL as kn, A2A_CONTAINER_PORT as kt, isApplicationLoadBalancer as l, createLocalStateProvider as ln, ConnectionRegistry as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, resolveCfnStackName as mn, buildDisconnectEvent as mt, createLocalListCommand as n, substituteAgainstState as nn, pickResponseTemplate as nt, createLocalStartAlbCommand as o, resolveEnvVars as on, HOST_GATEWAY_MIN_VERSION as ot, serviceStrategy as p, resolveCfnRegion as pn, buildConnectEvent as pt, evaluateCachedLambdaPolicy as q, toCmdArgv as qt, formatTargetListing as r, substituteAgainstStateAsync as rn, selectIntegrationResponse as rt, parseLbPortOverrides as s, materializeLayerFromArn as sn, probeHostGatewaySupport as st, addListSpecificOptions as t, EcsTaskResolutionError as tn, evaluateResponseParameters as tt, resolveAlbFrontDoor as u, isCfnFlagPresent as un, buildMgmtEndpointEnvUrl as ut, parseRestartPolicy as v, resolveWatchConfig as vn, createJwksCache as vt, addRunTaskSpecificOptions as w, parseSelectionExpressionPath as wn, buildCorsConfigByApiId as wt, buildCloudMapIndex as x, listTargets as xn, verifyJwtViaDiscovery as xt, resolveSharedSidecarCredentials as y, resolveSingleTarget as yn, verifyCognitoJwt as yt, groupRoutesByServer as z, tryResolveImageFnJoin as zn, AGENTCORE_SESSION_ID_HEADER as zt };
+//# sourceMappingURL=local-list-CyW86HDN.js.map