cdk-local 0.64.0 → 0.65.1

package/dist/{local-start-alb-CIE0TMpn.js → local-list-JDGfdnip.js}

@@ -7799,6 +7799,641 @@ async function writeProfileCredentialsFile(profileName, creds) {
 	};
 }
 
+//#endregion
+//#region src/cli/commands/local-invoke.ts
+/**
+* `cdkl invoke <target>` — run a Lambda function locally inside a
+* Docker container that bundles the AWS Lambda Runtime Interface
+* Emulator (RIE). Modeled on `sam local invoke` but reusing cdk-local's
+* synthesis / asset / construct-path plumbing.
+*/
+async function localInvokeCommand(target, options, extraStateProviders) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(options);
+	let imagePlan;
+	let containerId;
+	let stopLogs;
+	let sigintHandler;
+	let profileCredsFile;
+	/**
+	* Unified cleanup for both the success / failure unwind path AND the
+	* SIGINT handler.
+	*/
+	const cleanup = singleFlight(async () => {
+		if (stopLogs) try {
+			stopLogs();
+		} catch (err) {
+			getLogger().debug(`streamLogs stop failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (containerId) try {
+			await removeContainer(containerId);
+		} catch (err) {
+			getLogger().debug(`removeContainer(${containerId}) failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (imagePlan?.inlineTmpDir) try {
+			rmSync(imagePlan.inlineTmpDir, {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			getLogger().debug(`Failed to remove inline-code tmpdir ${imagePlan.inlineTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (imagePlan?.layersTmpDir) try {
+			rmSync(imagePlan.layersTmpDir, {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			getLogger().debug(`Failed to remove merged-layers tmpdir ${imagePlan.layersTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (imagePlan?.layerArnTmpDirs) for (const dir of imagePlan.layerArnTmpDirs) try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			getLogger().debug(`Failed to remove ARN-layer tmpdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (profileCredsFile) try {
+			await profileCredsFile.dispose();
+		} catch (err) {
+			getLogger().debug(`Failed to remove profile credentials tmpdir ${profileCredsFile.hostPath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}, (err) => {
+		getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+	});
+	try {
+		await applyRoleArnIfSet({
+			roleArn: options.roleArn,
+			region: options.region
+		});
+		await ensureDockerAvailable();
+		const profileCredentials = options.profile ? await resolveProfileCredentials$1(options.profile) : void 0;
+		if (options.profile && profileCredentials) profileCredsFile = await writeProfileCredentialsFile(options.profile, profileCredentials);
+		const appCmd = resolveApp(options.app);
+		if (!appCmd) throw new Error(`No CDK app specified. Pass --app, set ${getEmbedConfig().envPrefix}_APP, or add "app" to cdk.json.`);
+		logger.info("Synthesizing CDK app...");
+		const synthesizer = new Synthesizer();
+		const context = parseContextOptions(options.context);
+		const synthOpts = {
+			app: appCmd,
+			output: options.output,
+			...options.region && { region: options.region },
+			...options.profile && { profile: options.profile },
+			...Object.keys(context).length > 0 && { context }
+		};
+		const { stacks } = await synthesizer.synthesize(synthOpts);
+		const lambda = resolveLambdaTarget(await resolveSingleTarget(target, {
+			entries: listTargets(stacks).lambdas,
+			message: "Select a Lambda function to invoke",
+			noun: "Lambda functions",
+			onMissing: () => new CdkLocalError(`${getEmbedConfig().cliName} invoke requires a <target> (a Lambda display path or logical ID). Run \`${getEmbedConfig().cliName} list\` to see them, or run it in a TTY to pick interactively.`, "LOCAL_INVOKE_TARGET_REQUIRED")
+		}), stacks);
+		const targetLabel = lambda.kind === "zip" ? lambda.runtime : "container image";
+		logger.info(`Target: ${lambda.stack.stackName}/${lambda.logicalId} (${targetLabel})`);
+		imagePlan = await resolveImagePlan(lambda, options);
+		let stateAudit;
+		let templateEnv = getTemplateEnv$1(lambda.resource);
+		let stateForRoleHint;
+		const stateProvider = createLocalStateProvider(options, lambda.stack.stackName, await resolveCfnFallbackRegion(options, lambda.stack.region), extraStateProviders);
+		if (stateProvider) try {
+			const loaded = await stateProvider.load(lambda.stack.stackName, lambda.stack.region);
+			if (loaded) {
+				stateForRoleHint = {
+					version: 1,
+					stackName: lambda.stack.stackName,
+					resources: loaded.resources,
+					outputs: loaded.outputs,
+					lastModified: 0
+				};
+				const subContext = {
+					resources: loaded.resources,
+					consumerRegion: loaded.region
+				};
+				if (envHasIntrinsicValue$1(templateEnv)) {
+					const pseudo = await resolvePseudoParametersForInvoke(lambda.stack.region, options);
+					if (pseudo) subContext.pseudoParameters = pseudo;
+				}
+				if (envHasIntrinsicValue$1(templateEnv) && stateProvider.resolveTemplateSsmParameters) {
+					const ssmParams = await stateProvider.resolveTemplateSsmParameters(lambda.stack.template);
+					if (Object.keys(ssmParams.values).length > 0) subContext.parameters = ssmParams.values;
+					if (ssmParams.secureStringLogicalIds.length > 0) subContext.sensitiveParameters = new Set(ssmParams.secureStringLogicalIds);
+				}
+				if (envHasCrossStackIntrinsic(templateEnv)) {
+					const resolver = await stateProvider.buildCrossStackResolver(loaded.region);
+					if (resolver) subContext.crossStackResolver = resolver;
+				}
+				const { env, audit } = await substituteEnvVarsFromStateAsync(templateEnv, subContext);
+				templateEnv = env;
+				const label = stateProvider.label;
+				for (const key of audit.resolvedKeys) logger.debug(`${label}: substituted env var ${key}`);
+				let unresolved = audit.unresolved;
+				const resolvedKeys = [...audit.resolvedKeys];
+				if (unresolved.length > 0 && stateProvider.resolveDeployedFunctionEnv) {
+					const physicalId = loaded.resources[lambda.logicalId]?.physicalId;
+					if (physicalId) {
+						const deployedEnv = await stateProvider.resolveDeployedFunctionEnv(physicalId);
+						const fb = applyDeployedEnvFallback(templateEnv, unresolved, deployedEnv);
+						templateEnv = fb.env;
+						unresolved = fb.stillUnresolved;
+						for (const key of fb.filled) {
+							resolvedKeys.push(key);
+							logger.debug(`${label}: filled env var ${key} from deployed function config`);
+						}
+					}
+				}
+				stateAudit = {
+					resolvedKeys,
+					unresolved,
+					sensitiveKeys: audit.sensitiveKeys
+				};
+				for (const { key, reason } of unresolved) logger.warn(`${label}: could not substitute env var ${key} (${reason}). Override it via --env-vars or it will be dropped.`);
+			}
+		} catch (err) {
+			stateProvider.dispose();
+			throw err;
+		}
+		const overrides = readEnvOverridesFile$4(options.envVars);
+		const lambdaCdkPath = readCdkPathOrUndefined(lambda.resource);
+		const envResult = resolveEnvVars(lambda.logicalId, lambdaCdkPath, templateEnv, overrides);
+		for (const key of envResult.unresolved) {
+			if (stateAudit && stateAudit.unresolved.some((u) => u.key === key)) continue;
+			const overrideKeyExample = lambdaCdkPath?.replace(/\/Resource$/, "") ?? lambda.logicalId;
+			logger.warn(`Environment variable ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${overrideKeyExample}":{"${key}":"<literal>"}}), or pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to recover deployed values.`);
+		}
+		let resolvedAssumeRoleArn;
+		try {
+			resolvedAssumeRoleArn = await resolveAssumeRoleArnForLambda(options.assumeRole, stateForRoleHint, stateProvider, lambda.logicalId);
+		} finally {
+			stateProvider?.dispose();
+		}
+		if (options.assumeRole === void 0 && stateForRoleHint) suggestAssumeRoleFromState(stateForRoleHint, lambda.logicalId);
+		const event = await readEvent$1(options);
+		const dockerEnv = {
+			AWS_LAMBDA_FUNCTION_NAME: lambda.logicalId,
+			AWS_LAMBDA_FUNCTION_MEMORY_SIZE: String(lambda.memoryMb),
+			AWS_LAMBDA_FUNCTION_TIMEOUT: String(lambda.timeoutSec),
+			AWS_LAMBDA_FUNCTION_VERSION: "$LATEST",
+			AWS_LAMBDA_LOG_GROUP_NAME: `/aws/lambda/${lambda.logicalId}`,
+			AWS_LAMBDA_LOG_STREAM_NAME: "local",
+			...envResult.resolved
+		};
+		let assumeSucceeded = false;
+		if (resolvedAssumeRoleArn) {
+			const stsRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"];
+			try {
+				const creds = await assumeLambdaExecutionRole$1(resolvedAssumeRoleArn, stsRegion);
+				dockerEnv["AWS_ACCESS_KEY_ID"] = creds.accessKeyId;
+				dockerEnv["AWS_SECRET_ACCESS_KEY"] = creds.secretAccessKey;
+				dockerEnv["AWS_SESSION_TOKEN"] = creds.sessionToken;
+				if (stsRegion) dockerEnv["AWS_REGION"] = stsRegion;
+				assumeSucceeded = true;
+			} catch (err) {
+				const reason = err instanceof Error ? err.message : String(err);
+				logger.warn(`--assume-role: STS AssumeRole(${resolvedAssumeRoleArn}) failed: ${reason}. Falling back to the developer's shell credentials.`);
+			}
+		}
+		if (!assumeSucceeded) {
+			forwardAwsEnv$3(dockerEnv);
+			applyProfileCredentialsOverlay(dockerEnv, profileCredentials, false);
+			if (profileCredsFile) {
+				dockerEnv["AWS_SHARED_CREDENTIALS_FILE"] = profileCredsFile.containerPath;
+				dockerEnv["AWS_PROFILE"] = profileCredsFile.profileName;
+			}
+		}
+		let debugPort;
+		if (options.debugPort) {
+			debugPort = Number(options.debugPort);
+			if (!Number.isInteger(debugPort) || debugPort <= 0 || debugPort > 65535) throw new Error(`--debug-port must be an integer in 1..65535, got '${options.debugPort}'`);
+			dockerEnv["NODE_OPTIONS"] = `--inspect-brk=0.0.0.0:${debugPort}`;
+			if (lambda.kind === "image") logger.warn("--debug-port sets NODE_OPTIONS unconditionally on container Lambdas. If the image's runtime is not Node.js, this flag is a no-op.");
+		}
+		const hostPort = await pickFreePort();
+		const containerHost = options.containerHost;
+		if (lambda.layers.length > 0) logger.info(`Mounting ${lambda.layers.length} Lambda layer${lambda.layers.length === 1 ? "" : "s"} at /opt`);
+		logger.info(`Starting container (image=${imagePlan.image}, port=${hostPort})...`);
+		const extraMountsWithProfile = profileCredsFile ? [...imagePlan.extraMounts ?? [], {
+			hostPath: profileCredsFile.hostPath,
+			containerPath: profileCredsFile.containerPath,
+			readOnly: true
+		}] : imagePlan.extraMounts;
+		containerId = await runDetached({
+			image: imagePlan.image,
+			mounts: imagePlan.mounts,
+			extraMounts: extraMountsWithProfile,
+			env: dockerEnv,
+			...stateAudit && stateAudit.sensitiveKeys.length > 0 && { sensitiveEnvKeys: new Set(stateAudit.sensitiveKeys) },
+			cmd: imagePlan.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 }
+		});
+		stopLogs = streamLogs(containerId);
+		sigintHandler = () => {
+			cleanup().then(() => {
+				process.exit(130);
+			});
+		};
+		process.on("SIGINT", sigintHandler);
+		await waitForRieReady(containerHost, hostPort, 5e3);
+		const result = await invokeRie(containerHost, hostPort, event, Math.max(3e4, lambda.timeoutSec * 2 * 1e3));
+		await new Promise((resolveDelay) => setTimeout(resolveDelay, 250));
+		process.stdout.write(`${result.raw}\n`);
+	} finally {
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		await cleanup();
+	}
+}
+async function resolveImagePlan(lambda, options) {
+	if (lambda.kind === "zip") return resolveZipImagePlan$1(lambda, options);
+	return resolveContainerImagePlan$1(lambda, options);
+}
+async function resolveZipImagePlan$1(lambda, options) {
+	let inlineTmpDir;
+	let codeDir = lambda.codePath;
+	if (codeDir === null) {
+		inlineTmpDir = materializeInlineCode$2(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime));
+		codeDir = inlineTmpDir;
+	}
+	const image = resolveRuntimeImage(lambda.runtime);
+	await pullImage(image, options.pull === false);
+	const layerPlan = await materializeLambdaLayersIncludingArns(lambda.layers, options);
+	const containerCodePath = resolveRuntimeCodeMountPath(lambda.runtime);
+	const tmpfs = resolveTmpfsForLambda(lambda);
+	return {
+		image,
+		mounts: [{
+			hostPath: codeDir,
+			containerPath: containerCodePath,
+			readOnly: true
+		}],
+		extraMounts: layerPlan.mount ? [layerPlan.mount] : [],
+		cmd: [lambda.handler],
+		...inlineTmpDir !== void 0 && { inlineTmpDir },
+		...layerPlan.tmpDir !== void 0 && { layersTmpDir: layerPlan.tmpDir },
+		...layerPlan.extraTmpDirs.length > 0 && { layerArnTmpDirs: layerPlan.extraTmpDirs },
+		...tmpfs !== void 0 && { tmpfs }
+	};
+}
+async function materializeLambdaLayersIncludingArns(layers, options) {
+	const extraTmpDirs = [];
+	const flat = [];
+	for (const layer of layers) {
+		if (layer.kind === "asset") {
+			flat.push({
+				logicalId: layer.logicalId,
+				assetPath: layer.assetPath
+			});
+			continue;
+		}
+		const dir = await materializeLayerFromArn(layer, { ...options.layerRoleArn !== void 0 && { roleArn: options.layerRoleArn } });
+		extraTmpDirs.push(dir);
+		flat.push({
+			logicalId: layer.arn,
+			assetPath: dir
+		});
+	}
+	return {
+		...materializeLambdaLayers$1(flat),
+		extraTmpDirs
+	};
+}
+function resolveTmpfsForLambda(lambda) {
+	if (lambda.ephemeralStorageMb === void 0) return void 0;
+	const logger = getLogger();
+	if (lambda.kind === "image") logger.info(`Lambda ${lambda.logicalId}: capping /tmp at ${lambda.ephemeralStorageMb} MiB via --tmpfs (overlays any base-image /tmp content)`);
+	else logger.debug(`Lambda ${lambda.logicalId}: applying EphemeralStorage cap via --tmpfs /tmp:size=${lambda.ephemeralStorageMb}m`);
+	return {
+		target: "/tmp",
+		sizeMb: lambda.ephemeralStorageMb
+	};
+}
+function materializeLambdaLayers$1(layers) {
+	if (layers.length === 0) return {};
+	if (layers.length === 1) return { mount: {
+		hostPath: layers[0].assetPath,
+		containerPath: "/opt",
+		readOnly: true
+	} };
+	const tmpDir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-invoke-layers-`));
+	for (const layer of layers) cpSync(layer.assetPath, tmpDir, {
+		recursive: true,
+		force: true
+	});
+	return {
+		mount: {
+			hostPath: tmpDir,
+			containerPath: "/opt",
+			readOnly: true
+		},
+		tmpDir
+	};
+}
+async function resolveContainerImagePlan$1(lambda, options) {
+	const logger = getLogger();
+	const platform = architectureToPlatform(lambda.architecture);
+	const localBuild = await resolveLocalBuildPlan$1(lambda);
+	let imageRef;
+	if (localBuild) imageRef = await buildContainerImage(localBuild.asset, localBuild.cdkOutDir, {
+		architecture: lambda.architecture,
+		noBuild: options.build === false
+	});
+	else {
+		if (!parseEcrUri(lambda.imageUri)) throw new Error(`Container Lambda '${lambda.logicalId}' has no matching asset in cdk.out, and Code.ImageUri '${lambda.imageUri}' is not an ECR URI ${getEmbedConfig().binaryName} can authenticate against. Re-synthesize the CDK app (so cdk.out includes the build context) or deploy the image to ECR first.`);
+		logger.info(`No matching cdk.out asset for ${lambda.imageUri}; falling back to ECR pull (same-acct/region only)...`);
+		imageRef = await pullEcrImage(lambda.imageUri, {
+			skipPull: options.pull === false,
+			...options.region !== void 0 && { region: options.region },
+			...options.ecrRoleArn !== void 0 && { ecrRoleArn: options.ecrRoleArn },
+			...options.profile !== void 0 && { profile: options.profile }
+		});
+	}
+	const tmpfs = resolveTmpfsForLambda(lambda);
+	return {
+		image: imageRef,
+		mounts: [],
+		extraMounts: [],
+		cmd: lambda.imageConfig.command ?? [],
+		platform,
+		...lambda.imageConfig.entryPoint && lambda.imageConfig.entryPoint.length > 0 && { entryPoint: lambda.imageConfig.entryPoint },
+		...lambda.imageConfig.workingDirectory !== void 0 && { workingDir: lambda.imageConfig.workingDirectory },
+		...tmpfs !== void 0 && { tmpfs }
+	};
+}
+async function resolveLocalBuildPlan$1(lambda) {
+	const manifestPath = lambda.stack.assetManifestPath;
+	if (!manifestPath) return void 0;
+	const cdkOutDir = dirname(manifestPath);
+	const manifest = await new AssetManifestLoader().loadManifest(cdkOutDir, lambda.stack.stackName);
+	if (!manifest) return void 0;
+	const entry = getDockerImageBySourceHash(manifest, lambda.imageUri);
+	if (!entry) return void 0;
+	return {
+		asset: entry.asset,
+		cdkOutDir
+	};
+}
+function envHasIntrinsicValue$1(templateEnv) {
+	if (!templateEnv) return false;
+	for (const v of Object.values(templateEnv)) {
+		if (v === void 0 || v === null) continue;
+		if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") continue;
+		return true;
+	}
+	return false;
+}
+function envHasCrossStackIntrinsic(templateEnv) {
+	if (!templateEnv) return false;
+	for (const v of Object.values(templateEnv)) {
+		if (!v || typeof v !== "object") continue;
+		const obj = v;
+		if ("Fn::ImportValue" in obj || "Fn::GetStackOutput" in obj) return true;
+	}
+	return false;
+}
+async function resolvePseudoParametersForInvoke(stackRegion, options) {
+	const logger = getLogger();
+	const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? stackRegion;
+	if (!region) logger.warn(`Resolver references \${AWS::Region} but ${getEmbedConfig().binaryName} could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.`);
+	let accountId;
+	try {
+		const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+		const sts = new STSClient({ ...region && { region } });
+		try {
+			accountId = (await sts.send(new GetCallerIdentityCommand({}))).Account;
+		} finally {
+			sts.destroy();
+		}
+	} catch (err) {
+		logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env entries will be dropped with per-key warnings.`);
+	}
+	const partitionAndSuffix = region ? derivePartitionAndUrlSuffix(region) : void 0;
+	const bag = {
+		...accountId !== void 0 && { accountId },
+		...region !== void 0 && { region },
+		...partitionAndSuffix && {
+			partition: partitionAndSuffix.partition,
+			urlSuffix: partitionAndSuffix.urlSuffix
+		}
+	};
+	return Object.keys(bag).length === 0 ? void 0 : bag;
+}
+function getTemplateEnv$1(resource) {
+	const env = (resource.Properties ?? {})["Environment"];
+	if (!env || typeof env !== "object") return void 0;
+	const vars = env["Variables"];
+	if (!vars || typeof vars !== "object") return void 0;
+	return vars;
+}
+function readEnvOverridesFile$4(filePath) {
+	if (!filePath) return void 0;
+	let raw;
+	try {
+		raw = readFileSync(filePath, "utf-8");
+	} catch (err) {
+		throw new Error(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`--env-vars file '${filePath}' must contain a JSON object at the top level.`);
+	return parsed;
+}
+async function readEvent$1(options) {
+	if (options.event && options.eventStdin) throw new Error("--event and --event-stdin are mutually exclusive.");
+	if (options.eventStdin) return parseEvent$1(await readStdin$1(), "<stdin>");
+	if (options.event) return parseEvent$1(readFileSync(options.event, "utf-8"), options.event);
+	return {};
+}
+function parseEvent$1(raw, source) {
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse event payload from ${source} as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+async function readStdin$1() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	return Buffer.concat(chunks).toString("utf-8");
+}
+async function assumeLambdaExecutionRole$1(roleArn, region) {
+	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const creds = (await sts.send(new AssumeRoleCommand({
+			RoleArn: roleArn,
+			RoleSessionName: `${getEmbedConfig().resourceNamePrefix}-invoke-${Date.now()}`,
+			DurationSeconds: 3600
+		}))).Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new Error(`AssumeRole(${roleArn}) returned no usable credentials.`);
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			sessionToken: creds.SessionToken
+		};
+	} finally {
+		sts.destroy();
+	}
+}
+function forwardAwsEnv$3(env) {
+	for (const key of [
+		"AWS_ACCESS_KEY_ID",
+		"AWS_SECRET_ACCESS_KEY",
+		"AWS_SESSION_TOKEN",
+		"AWS_REGION",
+		"AWS_DEFAULT_REGION"
+	]) {
+		const value = process.env[key];
+		if (value !== void 0) env[key] = value;
+	}
+}
+/**
+* Resolve `--profile <p>` to a concrete credential set. Mirrors the
+* helper in `local-start-api.ts`.
+*/
+async function resolveProfileCredentials$1(profile) {
+	const { STSClient } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ profile });
+	try {
+		const credsProvider = sts.config.credentials;
+		const creds = typeof credsProvider === "function" ? await credsProvider() : credsProvider;
+		if (!creds || !creds.accessKeyId || !creds.secretAccessKey) throw new Error(`--profile '${profile}': credential provider chain resolved without usable credentials. Check \`aws sso login --profile ` + profile + "` for SSO profiles, or `~/.aws/credentials` / `~/.aws/config` for regular profiles.");
+		return {
+			accessKeyId: creds.accessKeyId,
+			secretAccessKey: creds.secretAccessKey,
+			...creds.sessionToken && { sessionToken: creds.sessionToken }
+		};
+	} finally {
+		sts.destroy();
+	}
+}
+function applyProfileCredentialsOverlay(env, profileCreds, assumeRoleActive) {
+	if (!profileCreds) return;
+	if (assumeRoleActive) return;
+	env["AWS_ACCESS_KEY_ID"] = profileCreds.accessKeyId;
+	env["AWS_SECRET_ACCESS_KEY"] = profileCreds.secretAccessKey;
+	if (profileCreds.sessionToken) env["AWS_SESSION_TOKEN"] = profileCreds.sessionToken;
+	else delete env["AWS_SESSION_TOKEN"];
+}
+function materializeInlineCode$2(handler, source, fileExtension) {
+	const lastDot = handler.lastIndexOf(".");
+	if (lastDot <= 0) throw new Error(`Handler '${handler}' is malformed: expected '<modulePath>.<exportName>'.`);
+	const modulePath = handler.substring(0, lastDot);
+	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-invoke-`));
+	const filePath = path.join(dir, `${modulePath}${fileExtension}`);
+	mkdirSync(path.dirname(filePath), { recursive: true });
+	writeFileSync(filePath, source, "utf-8");
+	return dir;
+}
+function suggestAssumeRoleFromState(state, logicalId) {
+	const logger = getLogger();
+	const roleArn = resolveExecutionRoleArnFromState(state, logicalId);
+	if (roleArn) logger.info(`Hint: the deployed function uses execution role ${roleArn}. Re-run with --assume-role to invoke under the deployed function's narrow permissions.`);
+}
+/**
+* Resolve the role ARN to assume for a Lambda invoke, honoring the three
+* `--assume-role` forms:
+*
+*   - `--assume-role <arn>` (explicit) → return `<arn>`.
+*   - `--assume-role` (bare, no value) → resolve from CFn state first;
+*     if that misses, fall back to
+*     `stateProvider.resolveLambdaExecutionRoleArn(<physicalId>)`
+*     (a `lambda:GetFunctionConfiguration` call) so a sibling-stack
+*     execution role still resolves (issue #181 — `ListStackResources`
+*     returns the role's name, not its ARN, so `attributes.Arn` is
+*     empty on the CFn state map and the state-only lookup misses).
+*   - `--assume-role` absent → return undefined (no assume).
+*
+* Logs the resolution path (info on success, warn on miss) so the user
+* can tell why the container did or did not get assumed-role creds.
+*
+* Exported for unit testing.
+*/
+async function resolveAssumeRoleArnForLambda(assumeRole, stateForRoleHint, stateProvider, lambdaLogicalId) {
+	const logger = getLogger();
+	if (typeof assumeRole === "string") return assumeRole;
+	if (assumeRole !== true) return;
+	if (!stateForRoleHint) {
+		logger.warn("--assume-role passed without an ARN, but no state was loaded. Pair it with a state-source flag, or pass the ARN explicitly: --assume-role <arn>. Falling back to the developer's shell credentials.");
+		return;
+	}
+	const fromState = resolveExecutionRoleArnFromState(stateForRoleHint, lambdaLogicalId);
+	if (fromState) {
+		logger.info(`--assume-role: auto-resolved execution role from state: ${fromState}`);
+		return fromState;
+	}
+	const fnPhysicalId = stateForRoleHint.resources[lambdaLogicalId]?.physicalId;
+	if (stateProvider?.resolveLambdaExecutionRoleArn && fnPhysicalId) {
+		const liveArn = await stateProvider.resolveLambdaExecutionRoleArn(fnPhysicalId);
+		if (liveArn) {
+			logger.info(`--assume-role: auto-resolved execution role from GetFunctionConfiguration: ${liveArn}`);
+			return liveArn;
+		}
+	}
+	logger.warn(`--assume-role: could not resolve the execution role ARN for '${lambdaLogicalId}'. Pass the ARN explicitly: --assume-role <arn>. Falling back to the developer's shell credentials.`);
+}
+function resolveExecutionRoleArnFromState(state, logicalId, roleProperty = "Role") {
+	const lambda = state.resources[logicalId];
+	if (!lambda) return void 0;
+	const roleRef = lambda.properties?.[roleProperty] ?? lambda.observedProperties?.[roleProperty];
+	if (typeof roleRef === "string" && roleRef.startsWith("arn:")) return roleRef;
+	if (typeof roleRef === "object" && roleRef !== null) {
+		const refLogicalId = pickReferencedLogicalId(roleRef);
+		if (refLogicalId) {
+			const cached = state.resources[refLogicalId]?.attributes?.["Arn"];
+			if (typeof cached === "string" && cached.startsWith("arn:")) return cached;
+		}
+	}
+}
+function pickReferencedLogicalId(intrinsic) {
+	if ("Ref" in intrinsic && typeof intrinsic["Ref"] === "string") return intrinsic["Ref"];
+	if ("Fn::GetAtt" in intrinsic) {
+		const arg = intrinsic["Fn::GetAtt"];
+		if (Array.isArray(arg) && typeof arg[0] === "string") return arg[0];
+		if (typeof arg === "string") return arg.split(".")[0];
+	}
+}
+function createLocalInvokeCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick the Lambda from a list.").argument("[target]", "CDK display path or stack-qualified logical ID of the Lambda to invoke (omit to pick interactively in a TTY)").action(withErrorHandling(async (target, options) => {
+		await localInvokeCommand(target, options, opts.extraStateProviders);
+	}));
+	addInvokeSpecificOptions(invoke);
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((option) => invoke.addOption(option));
+	invoke.addOption(deprecatedRegionOption);
+	return invoke;
+}
+/**
+* Register the option block that `cdkl invoke` adds on top of the shared
+* common / app / context option helpers. Shared between `cdkl invoke` and
+* any host CLI (e.g. cdkd's `local invoke`) that wraps the single-shot
+* RIE-backed Lambda runner, so adding or renaming an `invoke`-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 the shared common / app / context
+* options — host flags / invoke flags / common flags grouped in three
+* `--help` clusters. Chainable: returns `cmd`.
+*/
+function addInvokeSpecificOptions(cmd) {
+	return cmd.addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from state (requires an active state source); (3) `--no-assume-role` explicitly opts out. Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers. Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name; pass an explicit value when CFn stack name differs. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
+}
+
 //#endregion
 //#region src/local/agentcore-code-build.ts
 /**
@@ -15921,7 +16556,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 	await ensureDockerAvailable();
 	const appCmd = resolveApp(options.app);
 	if (!appCmd) throw new Error(`No CDK app specified. Pass --app, set ${getEmbedConfig().envPrefix}_APP, or add "app" to cdk.json.`);
-	const overrides = readEnvOverridesFile$1(options.envVars);
+	const overrides = readEnvOverridesFile$3(options.envVars);
 	const debugPortBase = options.debugPortBase ? parseDebugPort(options.debugPortBase) : void 0;
 	const perLambdaConcurrency = parsePerLambdaConcurrency(options.perLambdaConcurrency);
 	const inlineTmpDirs = /* @__PURE__ */ new Set();
@@ -16478,1152 +17113,2009 @@ function deriveSynthStackPrefix(targets) {
 		if (slash === -1) return void 0;
 		prefixes.add(t.slice(0, slash));
 	}
-	return prefixes.size === 1 ? [...prefixes][0] : void 0;
+	return prefixes.size === 1 ? [...prefixes][0] : void 0;
+}
+/**
+* Decide whether synth should cover ALL stacks for the given target
+* subset (item 5). Synth is scoped to one stack only when a single stack
+* can be pinned; otherwise we synth every stack and the union is filtered
+* down by `apiFilters` afterwards.
+*
+* Returns `true` (synth all) when there ARE explicit targets but no
+* single stack can be pinned from them — i.e. `--stack` is unset, an
+* explicit `--from-cfn-stack <name>` is unset, AND
+* {@link deriveSynthStackPrefix} can't resolve one shared prefix (targets
+* span stacks, or any target is a bare logical id). Returns `false` when
+* there are no targets (serve-all already synths everything via the
+* regular path) or a stack is otherwise pinned.
+*
+* @internal exported for unit tests.
+*/
+function shouldSynthAllStacks(targets, stackPattern, cfnStackFallback) {
+	if (targets.length === 0) return false;
+	if (stackPattern !== void 0 || cfnStackFallback !== void 0) return false;
+	return deriveSynthStackPrefix(targets) === void 0;
+}
+/**
+* Decide whether bare `start-api` should open the pre-selected-all
+* multi-select picker. The picker runs ONLY when:
+*  - no explicit API subset was named (`apiFilters` empty — neither
+*    positional `<targets...>` nor the deprecated `--api`),
+*  - `--all-stacks` was not passed (that path already serves every API),
+*  - AND stdin/stdout is a TTY.
+*
+* In a non-TTY (CI / pipe) this returns `false`, and the caller serves
+* EVERY discovered API without prompting — start-api's one intentional
+* asymmetry vs invoke / run-task (which error when bare in a non-TTY),
+* because start-api legitimately has a "serve all" default.
+*
+* Extracted as a pure function (TTY is passed in) so the decision is
+* unit-testable without booting the server or juggling global TTY state.
+*
+* @internal exported for unit tests.
+*/
+function shouldPromptBareMultiSelect(apiFilters, allStacks, isTty) {
+	return apiFilters.length === 0 && !allStacks && isTty;
+}
+/**
+* Decide whether the `--from-cfn-stack <name>` redundancy tip should
+* fire for the current invocation. Fires only when:
+*  - `fromCfnStack` is a non-empty STRING (explicit value, not bare `true`)
+*  - exactly ONE stack is routed
+*  - the explicit value equals the routed stack's `stackName`
+*
+* Extracted as a pure function so it can be unit-tested without booting
+* the full server. See improvement A in the start-api UX PR.
+*
+* @internal exported for unit tests.
+*/
+function shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames) {
+	if (typeof fromCfnStack !== "string") return false;
+	if (fromCfnStack.length === 0) return false;
+	if (routedStackNames.length !== 1) return false;
+	return fromCfnStack === routedStackNames[0];
+}
+/**
+* One-shot wrapper around `shouldEmitFromCfnRedundancyTip` for the
+* `--watch` hot-reload path. `synthesizeAndBuild` re-runs on every
+* reload firing, so without a gate the tip would re-emit on every
+* reload — noisy. This helper consults the caller-supplied ref:
+*  - If the predicate fires AND the ref is still `false`, calls `emit`
+*    and flips the ref to `true`.
+*  - On subsequent invocations the ref is `true` and the helper is a
+*    no-op for the rest of the ref's lifetime.
+*  - When the predicate does NOT fire (no `--from-cfn-stack` value /
+*    intentionally-different value / multi-stack run), the ref stays
+*    `false` so a future reload whose synthesized stacks change in a
+*    way that DOES make the value redundant still emits the tip once.
+*
+* The ref is owned by `localStartApiCommand` (one per server boot), so
+* independent server invocations get independent flags.
+*
+* @internal exported for unit tests.
+*/
+function tryEmitFromCfnRedundancyTipOnce(fromCfnStack, routedStackNames, emittedRef, emit) {
+	if (emittedRef.value) return;
+	if (!shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames)) return;
+	const routedStackName = routedStackNames[0];
+	if (routedStackName === void 0) return;
+	emit(routedStackName);
+	emittedRef.value = true;
+}
+/**
+* Distinct, stable list of Lambda logical IDs reachable through any
+* discovered route OR referenced by a Lambda authorizer attached to one
+* of those routes. Stable order = first-occurrence order in the routes
+* list, then any newly-introduced authorizer Lambdas, which keeps the
+* route-table output deterministic.
+*/
+function uniqueLambdaIds(routes, routesWithAuth, webSocketApis = []) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const r of routes) {
+		if (r.unsupported || r.mockCors || r.serviceIntegration) continue;
+		if (r.lambdaLogicalId.length === 0) continue;
+		if (!seen.has(r.lambdaLogicalId)) {
+			seen.add(r.lambdaLogicalId);
+			out.push(r.lambdaLogicalId);
+		}
+	}
+	for (const entry of routesWithAuth) {
+		if (entry.route.unsupported || entry.route.mockCors || entry.route.serviceIntegration) continue;
+		const auth = entry.authorizer;
+		if (!auth) continue;
+		if (auth.kind === "lambda-token" || auth.kind === "lambda-request") {
+			if (!seen.has(auth.lambdaLogicalId)) {
+				seen.add(auth.lambdaLogicalId);
+				out.push(auth.lambdaLogicalId);
+			}
+		}
+	}
+	for (const api of webSocketApis) for (const r of api.routes) if (!seen.has(r.targetLambdaLogicalId)) {
+		seen.add(r.targetLambdaLogicalId);
+		out.push(r.targetLambdaLogicalId);
+	}
+	return out;
+}
+/**
+* Prefetch the JWKS for every Cognito / JWT authorizer attached to a
+* discovered route. Failures degrade to pass-through mode (verifier
+* surfaces a warn line on first hit); we still issue the prefetch so
+* the warn lands at startup rather than mid-request.
+*/
+async function prewarmJwks(routesWithAuth, jwksCache) {
+	const urls = /* @__PURE__ */ new Set();
+	for (const entry of routesWithAuth) {
+		const auth = entry.authorizer;
+		if (!auth) continue;
+		if (auth.kind === "cognito") for (const pool of auth.pools) urls.add(buildCognitoJwksUrl(pool.region, pool.userPoolId));
+		else if (auth.kind === "jwt") {
+			const url = auth.region && auth.userPoolId ? buildCognitoJwksUrl(auth.region, auth.userPoolId) : buildJwksUrlFromIssuer(auth.issuer);
+			urls.add(url);
+		}
+	}
+	await Promise.all([...urls].map((u) => jwksCache.fetchAndCache(u)));
+}
+/**
+* Emit a one-line warn for every VPC-config Lambda. The handler still
+* runs locally, but its container does not get attached to the AWS
+* VPC's subnets — calls to private RDS / ElastiCache will fail. cdk-local
+* surfaces this so the developer can pin the unexpected behavior to
+* the VPC config rather than chasing a "connection refused" rabbit
+* hole.
+*/
+function warnVpcConfigLambdas(routesWithAuth, stacks) {
+	const logger = getLogger();
+	const seen = /* @__PURE__ */ new Set();
+	const reachable = [];
+	for (const entry of routesWithAuth) {
+		if (!seen.has(entry.route.lambdaLogicalId)) {
+			seen.add(entry.route.lambdaLogicalId);
+			reachable.push(entry.route.lambdaLogicalId);
+		}
+		const auth = entry.authorizer;
+		if (auth && (auth.kind === "lambda-token" || auth.kind === "lambda-request")) {
+			if (!seen.has(auth.lambdaLogicalId)) {
+				seen.add(auth.lambdaLogicalId);
+				reachable.push(auth.lambdaLogicalId);
+			}
+		}
+	}
+	for (const logicalId of reachable) for (const stack of stacks) {
+		const resource = stack.template.Resources?.[logicalId];
+		if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
+		const vpcConfig = (resource.Properties ?? {})["VpcConfig"];
+		if (vpcConfig && typeof vpcConfig === "object" && Object.keys(vpcConfig).length > 0) logger.warn(`Lambda ${logicalId} has VpcConfig — local container will reach external services via the host's network, NOT through the deployed VPC's NAT/private subnets. Calls to private RDS/ElastiCache will fail.`);
+		break;
+	}
 }
 /**
-* Decide whether synth should cover ALL stacks for the given target
-* subset (item 5). Synth is scoped to one stack only when a single stack
-* can be pinned; otherwise we synth every stack and the union is filtered
-* down by `apiFilters` afterwards.
-*
-* Returns `true` (synth all) when there ARE explicit targets but no
-* single stack can be pinned from them — i.e. `--stack` is unset, an
-* explicit `--from-cfn-stack <name>` is unset, AND
-* {@link deriveSynthStackPrefix} can't resolve one shared prefix (targets
-* span stacks, or any target is a bare logical id). Returns `false` when
-* there are no targets (serve-all already synths everything via the
-* regular path) or a stack is otherwise pinned.
+* Walk the discovered routes for `AuthorizationType: 'AWS_IAM'` and emit
+* a one-line warn naming the affected routes. Returns `true` when at
+* least one IAM route is present so the caller wires the SigV4
+* credentials loader. Re-runs across hot reloads are silent — the warn
+* fires only at initial boot (matches `warnVpcConfigLambdas`'s policy).
 *
-* @internal exported for unit tests.
+* Implementation note: signature verification only — IAM policy
+* evaluation (resource / action / condition) is NOT emulated. See
+* `src/local/sigv4-verify.ts` and the help text in `docs/cli-reference.md`.
 */
-function shouldSynthAllStacks(targets, stackPattern, cfnStackFallback) {
-	if (targets.length === 0) return false;
-	if (stackPattern !== void 0 || cfnStackFallback !== void 0) return false;
-	return deriveSynthStackPrefix(targets) === void 0;
+function warnIamRoutes(routesWithAuth) {
+	const logger = getLogger();
+	const iamRoutes = [];
+	const oacRoutes = [];
+	for (const entry of routesWithAuth) {
+		if (entry.authorizer?.kind !== "iam") continue;
+		if (entry.authorizer.oacFronted === true) oacRoutes.push(entry.route.declaredAt);
+		else iamRoutes.push(entry.route.declaredAt);
+	}
+	if (iamRoutes.length === 0 && oacRoutes.length === 0) return false;
+	if (iamRoutes.length > 0) {
+		logger.warn(`${iamRoutes.length} route(s) declare AuthorizationType: AWS_IAM — ${getEmbedConfig().cliName} start-api verifies the SigV4 signatures it CAN (requests signed with your local AWS credentials), but cannot verify a federated / Cognito Identity Pool / cross-account signer and does NOT emulate IAM policy evaluation (resource / action / condition rules). By default such unverifiable requests warn-and-pass with a placeholder principalId — pass --strict-sigv4 to deny them instead. Downstream authorization is the dev's responsibility.`);
+		for (const declaredAt of iamRoutes) logger.warn(`  - ${declaredAt}`);
+	}
+	if (oacRoutes.length > 0) {
+		logger.warn(`${oacRoutes.length} Function URL route(s) with AuthType: AWS_IAM are fronted by a CloudFront Origin Access Control. In production CloudFront re-signs the origin request, so no local client signature can be verified — ${getEmbedConfig().cliName} start-api passes these through (warn-and-pass) and they ignore --strict-sigv4. Do NOT trust the request identity in handler code.`);
+		for (const declaredAt of oacRoutes) logger.warn(`  - ${declaredAt}`);
+	}
+	return true;
 }
 /**
-* Decide whether bare `start-api` should open the pre-selected-all
-* multi-select picker. The picker runs ONLY when:
-*  - no explicit API subset was named (`apiFilters` empty — neither
-*    positional `<targets...>` nor the deprecated `--api`),
-*  - `--all-stacks` was not passed (that path already serves every API),
-*  - AND stdin/stdout is a TTY.
-*
-* In a non-TTY (CI / pipe) this returns `false`, and the caller serves
-* EVERY discovered API without prompting — start-api's one intentional
-* asymmetry vs invoke / run-task (which error when bare in a non-TTY),
-* because start-api legitimately has a "serve all" default.
-*
-* Extracted as a pure function (TTY is passed in) so the decision is
-* unit-testable without booting the server or juggling global TTY state.
-*
-* @internal exported for unit tests.
+* Build the per-Lambda container spec — code dir, env vars (template +
+* --env-vars overlay), STS-issued creds when --assume-role names this
+* Lambda, optional --debug-port reservation. Errors out with a clear
+* message if the Lambda's code can't be resolved (asset directory
+* missing, runtime not supported).
 */
-function shouldPromptBareMultiSelect(apiFilters, allStacks, isTty) {
-	return apiFilters.length === 0 && !allStacks && isTty;
+async function buildContainerSpec(args) {
+	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack, skipPull, layerRoleArn, profileCredentials, profileCredsFile, profileRegion, stackRegionOverride } = args;
+	const lambda = resolveLambdaByLogicalId(logicalId, stacks);
+	let codeDir;
+	let optDir;
+	let imageRef;
+	let platform;
+	if (lambda.kind === "zip") {
+		codeDir = lambda.codePath ?? materializeInlineCode$1(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
+		optDir = await materializeLambdaLayers(lambda.layers, layerTmpDirs, layerRoleArn);
+	} else {
+		imageRef = (await resolveContainerImageForStartApi(lambda, skipPull, args.profile)).imageRef;
+		platform = architectureToPlatform(lambda.architecture);
+	}
+	let templateEnv = getTemplateEnv(lambda.resource);
+	const stateBundle = stateByStack.get(lambda.stack.stackName);
+	let stateAudit;
+	if (stateBundle) {
+		const context = { resources: stateBundle.state.resources };
+		if (stateBundle.pseudoParameters) context.pseudoParameters = stateBundle.pseudoParameters;
+		if (stateBundle.ssmParameters) context.parameters = stateBundle.ssmParameters;
+		if (stateBundle.ssmSecureStringLogicalIds?.length) context.sensitiveParameters = new Set(stateBundle.ssmSecureStringLogicalIds);
+		const { env, audit } = substituteEnvVarsFromState(templateEnv, context);
+		templateEnv = env;
+		for (const key of audit.resolvedKeys) getLogger().debug(`Lambda ${logicalId}: state source substituted env var ${key}`);
+		let unresolved = audit.unresolved;
+		const resolvedKeys = [...audit.resolvedKeys];
+		const deployedEnv = stateBundle.deployedEnvByLambda?.get(logicalId);
+		if (unresolved.length > 0 && deployedEnv) {
+			const fb = applyDeployedEnvFallback(templateEnv, unresolved, deployedEnv);
+			templateEnv = fb.env;
+			unresolved = fb.stillUnresolved;
+			for (const key of fb.filled) {
+				resolvedKeys.push(key);
+				getLogger().debug(`Lambda ${logicalId}: filled env var ${key} from deployed function config`);
+			}
+		}
+		stateAudit = {
+			resolvedKeys,
+			unresolved,
+			sensitiveKeys: audit.sensitiveKeys
+		};
+		for (const { key, reason } of unresolved) getLogger().warn(`Lambda ${logicalId}: state source could not substitute env var ${key} (${reason}). Override it via --env-vars or it will be dropped.`);
+	}
+	const lambdaCdkPath = readCdkPathOrUndefined(lambda.resource);
+	const envResult = resolveEnvVars(logicalId, lambdaCdkPath, templateEnv, overrides);
+	for (const key of envResult.unresolved) {
+		if (stateAudit && stateAudit.unresolved.some((u) => u.key === key)) continue;
+		const overrideKeyExample = lambdaCdkPath?.replace(/\/Resource$/, "") ?? logicalId;
+		getLogger().warn(`Lambda ${logicalId}: env var ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${overrideKeyExample}":{"${key}":"<literal>"}}) or pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to recover deployed values.`);
+	}
+	const dockerEnv = {
+		AWS_LAMBDA_FUNCTION_NAME: logicalId,
+		AWS_LAMBDA_FUNCTION_MEMORY_SIZE: String(lambda.memoryMb),
+		AWS_LAMBDA_FUNCTION_TIMEOUT: String(lambda.timeoutSec),
+		AWS_LAMBDA_FUNCTION_VERSION: "$LATEST",
+		AWS_LAMBDA_LOG_GROUP_NAME: `/aws/lambda/${logicalId}`,
+		AWS_LAMBDA_LOG_STREAM_NAME: "local",
+		...envResult.resolved
+	};
+	const roleArn = effectiveAssumeRoleArn(logicalId, assumeRole);
+	if (roleArn) {
+		const creds = await assumeLambdaExecutionRole(roleArn, stsRegion);
+		dockerEnv["AWS_ACCESS_KEY_ID"] = creds.accessKeyId;
+		dockerEnv["AWS_SECRET_ACCESS_KEY"] = creds.secretAccessKey;
+		dockerEnv["AWS_SESSION_TOKEN"] = creds.sessionToken;
+		if (stsRegion) dockerEnv["AWS_REGION"] = stsRegion;
+	} else {
+		forwardAwsEnv$2(dockerEnv);
+		if (profileCredentials) {
+			dockerEnv["AWS_ACCESS_KEY_ID"] = profileCredentials.accessKeyId;
+			dockerEnv["AWS_SECRET_ACCESS_KEY"] = profileCredentials.secretAccessKey;
+			if (profileCredentials.sessionToken) dockerEnv["AWS_SESSION_TOKEN"] = profileCredentials.sessionToken;
+			else delete dockerEnv["AWS_SESSION_TOKEN"];
+		}
+		if (profileCredsFile) {
+			dockerEnv["AWS_SHARED_CREDENTIALS_FILE"] = profileCredsFile.containerPath;
+			dockerEnv["AWS_PROFILE"] = profileCredsFile.profileName;
+		}
+	}
+	if (!dockerEnv["AWS_REGION"]) {
+		const fallbackRegion = resolveContainerFallbackRegion({
+			stackRegionOverride,
+			synthRegion: lambda.stack.region,
+			profileRegion
+		});
+		if (fallbackRegion) dockerEnv["AWS_REGION"] = fallbackRegion;
+	}
+	if (debugPort !== void 0) dockerEnv["NODE_OPTIONS"] = `--inspect-brk=0.0.0.0:${debugPort}`;
+	const tmpfs = lambda.ephemeralStorageMb !== void 0 ? {
+		target: "/tmp",
+		sizeMb: lambda.ephemeralStorageMb
+	} : void 0;
+	const sensitiveEnvKeys = stateAudit && stateAudit.sensitiveKeys.length > 0 ? new Set(stateAudit.sensitiveKeys) : void 0;
+	if (lambda.kind === "zip") return {
+		kind: "zip",
+		lambda,
+		codeDir,
+		env: dockerEnv,
+		...sensitiveEnvKeys && { sensitiveEnvKeys },
+		containerHost,
+		...optDir !== void 0 && { optDir },
+		...debugPort !== void 0 && { debugPort },
+		...tmpfs !== void 0 && { tmpfs },
+		...profileCredsFile && { profileCredentialsFile: {
+			hostPath: profileCredsFile.hostPath,
+			containerPath: profileCredsFile.containerPath
+		} }
+	};
+	return {
+		kind: "image",
+		lambda,
+		image: imageRef,
+		platform,
+		command: lambda.imageConfig.command ?? [],
+		...lambda.imageConfig.entryPoint !== void 0 && lambda.imageConfig.entryPoint.length > 0 && { entryPoint: lambda.imageConfig.entryPoint },
+		...lambda.imageConfig.workingDirectory !== void 0 && { workingDir: lambda.imageConfig.workingDirectory },
+		env: dockerEnv,
+		...sensitiveEnvKeys && { sensitiveEnvKeys },
+		containerHost,
+		...debugPort !== void 0 && { debugPort },
+		...tmpfs !== void 0 && { tmpfs },
+		...profileCredsFile && { profileCredentialsFile: {
+			hostPath: profileCredsFile.hostPath,
+			containerPath: profileCredsFile.containerPath
+		} }
+	};
 }
 /**
-* Decide whether the `--from-cfn-stack <name>` redundancy tip should
-* fire for the current invocation. Fires only when:
-*  - `fromCfnStack` is a non-empty STRING (explicit value, not bare `true`)
-*  - exactly ONE stack is routed
-*  - the explicit value equals the routed stack's `stackName`
-*
-* Extracted as a pure function so it can be unit-tested without booting
-* the full server. See improvement A in the start-api UX PR.
+* Resolve a container Lambda's local docker image — local build from
+* `cdk.out` asset manifest first, ECR-pull fallback when the asset
+* manifest has no matching entry. Mirrors `cdkl invoke`'s
+* `resolveContainerImagePlan` shape; the start-api server doesn't
+* need the no-build flag (deterministic-tag cache reuse is automatic
+* across reloads because the per-Lambda tag is content-addressed).
 *
-* @internal exported for unit tests.
+* Same-account / same-region only on the ECR-pull path (matches the
+* `cdkl invoke` PR 5 of #224 boundary). Cross-account /
+* cross-region ECR pull is the W2-1 deferred follow-up.
 */
-function shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames) {
-	if (typeof fromCfnStack !== "string") return false;
-	if (fromCfnStack.length === 0) return false;
-	if (routedStackNames.length !== 1) return false;
-	return fromCfnStack === routedStackNames[0];
+async function resolveContainerImageForStartApi(lambda, skipPull, profile) {
+	const logger = getLogger();
+	const localBuild = await resolveLocalBuildPlan(lambda);
+	if (localBuild) return { imageRef: await buildContainerImage(localBuild.asset, localBuild.cdkOutDir, { architecture: lambda.architecture }) };
+	if (!parseEcrUri(lambda.imageUri)) throw new Error(`Container Lambda '${lambda.logicalId}' has no matching asset in cdk.out, and Code.ImageUri '${lambda.imageUri}' is not an ECR URI ${getEmbedConfig().binaryName} can authenticate against. Re-synthesize the CDK app (so cdk.out includes the build context) or deploy the image to ECR first.`);
+	logger.info(`No matching cdk.out asset for ${lambda.imageUri}; falling back to ECR pull (same-acct/region only)...`);
+	return { imageRef: await pullEcrImage(lambda.imageUri, {
+		skipPull,
+		...profile !== void 0 && { profile }
+	}) };
 }
 /**
-* One-shot wrapper around `shouldEmitFromCfnRedundancyTip` for the
-* `--watch` hot-reload path. `synthesizeAndBuild` re-runs on every
-* reload firing, so without a gate the tip would re-emit on every
-* reload — noisy. This helper consults the caller-supplied ref:
-*  - If the predicate fires AND the ref is still `false`, calls `emit`
-*    and flips the ref to `true`.
-*  - On subsequent invocations the ref is `true` and the helper is a
-*    no-op for the rest of the ref's lifetime.
-*  - When the predicate does NOT fire (no `--from-cfn-stack` value /
-*    intentionally-different value / multi-stack run), the ref stays
-*    `false` so a future reload whose synthesized stacks change in a
-*    way that DOES make the value redundant still emits the tip once.
-*
-* The ref is owned by `localStartApiCommand` (one per server boot), so
-* independent server invocations get independent flags.
+* Look up the docker image asset that backs a container Lambda.
+* Returns `undefined` when the asset manifest has no matching entry —
+* the caller falls back to the ECR-pull path.
 *
-* @internal exported for unit tests.
+* Mirrors `local-invoke.ts:resolveLocalBuildPlan`; kept separate so
+* the two commands evolve their asset-lookup heuristics independently.
 */
-function tryEmitFromCfnRedundancyTipOnce(fromCfnStack, routedStackNames, emittedRef, emit) {
-	if (emittedRef.value) return;
-	if (!shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames)) return;
-	const routedStackName = routedStackNames[0];
-	if (routedStackName === void 0) return;
-	emit(routedStackName);
-	emittedRef.value = true;
+async function resolveLocalBuildPlan(lambda) {
+	const manifestPath = lambda.stack.assetManifestPath;
+	if (!manifestPath) return void 0;
+	const cdkOutDir = path.dirname(manifestPath);
+	const manifest = await new AssetManifestLoader().loadManifest(cdkOutDir, lambda.stack.stackName);
+	if (!manifest) return void 0;
+	const entry = getDockerImageBySourceHash(manifest, lambda.imageUri);
+	if (!entry) return void 0;
+	return {
+		asset: entry.asset,
+		cdkOutDir
+	};
 }
 /**
-* Distinct, stable list of Lambda logical IDs reachable through any
-* discovered route OR referenced by a Lambda authorizer attached to one
-* of those routes. Stable order = first-occurrence order in the routes
-* list, then any newly-introduced authorizer Lambdas, which keeps the
-* route-table output deterministic.
+* Build the `/opt` bind-mount source for a Lambda's layers. Mirrors
+* the helper in `src/cli/commands/local-invoke.ts` but stores the
+* merged tmpdir into the shared `layerTmpDirs` set so the server's
+* graceful shutdown path can clean it up. Returns `undefined` when
+* the function declares no layers.
+*
+* Three branches:
+*   - 0 layers → `undefined` (no `/opt` mount).
+*   - 1 layer → bind-mount the layer's asset dir directly (no copy)
+*     when the entry is a same-stack asset. Literal-ARN entries always
+*     pre-materialize first.
+*   - 2+ layers → copy each into a fresh tmpdir IN ORDER (later
+*     layers overwrite earlier files via `cpSync({force: true})`),
+*     bind-mount the tmpdir at `/opt`. Records the tmpdir in
+*     `layerTmpDirs` so `shutdown(...)` removes it.
+*
+* Issue #448: literal-ARN entries (`{kind: 'arn', ...}`) are downloaded
+* + unzipped via `lambda:GetLayerVersion` BEFORE the cpSync-merge
+* branches run. Every per-ARN tmpdir is also recorded in `layerTmpDirs`
+* so the same shutdown path cleans it up — even for the single-layer
+* fast path that bind-mounts the dir directly.
+*
+* AWS Lambda's actual runtime extracts every layer ZIP into `/opt`
+* in template order — the merge mirrors that. Docker rejects multiple
+* `-v ...:/opt:ro` entries at the same target, so cdk-local can't rely on
+* overlay layering and must produce a single merged dir on the host.
 */
-function uniqueLambdaIds(routes, routesWithAuth, webSocketApis = []) {
-	const seen = /* @__PURE__ */ new Set();
-	const out = [];
-	for (const r of routes) {
-		if (r.unsupported || r.mockCors || r.serviceIntegration) continue;
-		if (r.lambdaLogicalId.length === 0) continue;
-		if (!seen.has(r.lambdaLogicalId)) {
-			seen.add(r.lambdaLogicalId);
-			out.push(r.lambdaLogicalId);
-		}
-	}
-	for (const entry of routesWithAuth) {
-		if (entry.route.unsupported || entry.route.mockCors || entry.route.serviceIntegration) continue;
-		const auth = entry.authorizer;
-		if (!auth) continue;
-		if (auth.kind === "lambda-token" || auth.kind === "lambda-request") {
-			if (!seen.has(auth.lambdaLogicalId)) {
-				seen.add(auth.lambdaLogicalId);
-				out.push(auth.lambdaLogicalId);
-			}
+async function materializeLambdaLayers(layers, layerTmpDirs, layerRoleArn) {
+	if (layers.length === 0) return void 0;
+	const flat = [];
+	for (const layer of layers) {
+		if (layer.kind === "asset") {
+			flat.push({
+				logicalId: layer.logicalId,
+				assetPath: layer.assetPath
+			});
+			continue;
 		}
+		const dir = await materializeLayerFromArn(layer, { ...layerRoleArn !== void 0 && { roleArn: layerRoleArn } });
+		layerTmpDirs.add(dir);
+		flat.push({
+			logicalId: layer.arn,
+			assetPath: dir
+		});
 	}
-	for (const api of webSocketApis) for (const r of api.routes) if (!seen.has(r.targetLambdaLogicalId)) {
-		seen.add(r.targetLambdaLogicalId);
-		out.push(r.targetLambdaLogicalId);
+	if (flat.length === 1) return flat[0].assetPath;
+	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-layers-`));
+	for (const layer of flat) cpSync(layer.assetPath, dir, {
+		recursive: true,
+		force: true
+	});
+	layerTmpDirs.add(dir);
+	return dir;
+}
+function resolveLambdaByLogicalId(logicalId, stacks) {
+	for (const stack of stacks) {
+		const resource = stack.template.Resources?.[logicalId];
+		if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
+		const props = resource.Properties ?? {};
+		const memoryMb = typeof props["MemorySize"] === "number" ? props["MemorySize"] : 128;
+		const timeoutSec = typeof props["Timeout"] === "number" ? props["Timeout"] : 3;
+		const code = props["Code"] ?? {};
+		const imageUri = extractImageUri(code["ImageUri"], logicalId, stack.stackName, stack.template.Resources ?? {}, stack.region);
+		if (imageUri !== void 0) return resolveImageLambda({
+			stack,
+			logicalId,
+			resource,
+			props,
+			memoryMb,
+			timeoutSec,
+			imageUri
+		});
+		const runtime = typeof props["Runtime"] === "string" ? props["Runtime"] : "";
+		const handler = typeof props["Handler"] === "string" ? props["Handler"] : "";
+		if (!runtime) throw new Error(`Lambda '${logicalId}' has no Runtime property and no Code.ImageUri. ${getEmbedConfig().cliName} start-api cannot tell if this is a ZIP or a container Lambda.`);
+		if (!handler) throw new Error(`Lambda '${logicalId}' has no Handler property.`);
+		const inlineCode = typeof code["ZipFile"] === "string" ? code["ZipFile"] : void 0;
+		let codePath = null;
+		if (!inlineCode) codePath = resolveAssetCodePath(stack, logicalId, resource);
+		const layers = resolveLambdaLayers(stack, logicalId, props);
+		const ephemeralStorageMb = extractEphemeralStorageMb(props, logicalId);
+		return {
+			kind: "zip",
+			stack,
+			logicalId,
+			resource,
+			runtime,
+			handler,
+			memoryMb,
+			timeoutSec,
+			codePath,
+			layers,
+			...inlineCode !== void 0 && { inlineCode },
+			...ephemeralStorageMb !== void 0 && { ephemeralStorageMb }
+		};
 	}
-	return out;
+	throw new Error(`No AWS::Lambda::Function resource named '${logicalId}' found in target stacks. This is likely a synthesis bug — the route-discovery phase resolved a route to this logical ID.`);
 }
 /**
-* Prefetch the JWKS for every Cognito / JWT authorizer attached to a
-* discovered route. Failures degrade to pass-through mode (verifier
-* surfaces a warn line on first hit); we still issue the prefetch so
-* the warn lands at startup rather than mid-request.
+* Extract `Code.ImageUri` across the shapes CDK actually synthesizes.
+* Mirrors the simpler subset of `lambda-resolver.ts:extractImageUri`
+* scoped to the shapes `cdkl start-api` consumes — flat string,
+* `Fn::Sub` (the canonical asset shape for
+* `lambda.DockerImageCode.fromImageAsset`), and `Fn::Join` (the
+* canonical shape for `lambda.DockerImageCode.fromImageAsset` in
+* CDK 2.x, which emits a `Fn::Join` over the literal bootstrap ECR
+* URI with `${AWS::URLSuffix}` — issues #627 + #637).
+*
+* The `Fn::Join` arm routes through the shared
+* `tryResolveImageFnJoin` helper (`src/local/intrinsic-image.ts`) used
+* by `cdkl invoke`. When the synth template recorded a deploy
+* region (`stack.region`), we derive `{ urlSuffix, partition, region }`
+* via `derivePseudoParametersFromRegion` and pass it as the resolver's
+* `pseudoParameters` block so the canonical `${AWS::URLSuffix}` shape
+* resolves cleanly (issue #637). Same-stack ECR refs still surface as
+* `needs-state` (those require `--from-state`); a Join that references
+* `${AWS::AccountId}` without state still surfaces as `not-applicable`
+* with a more specific error message naming the missing parameter.
+*
+* Returns `undefined` when the field is absent or non-recognized,
+* which routes the caller to the ZIP branch (with its existing
+* "no Runtime / no Handler" validations).
 */
-async function prewarmJwks(routesWithAuth, jwksCache) {
-	const urls = /* @__PURE__ */ new Set();
-	for (const entry of routesWithAuth) {
-		const auth = entry.authorizer;
-		if (!auth) continue;
-		if (auth.kind === "cognito") for (const pool of auth.pools) urls.add(buildCognitoJwksUrl(pool.region, pool.userPoolId));
-		else if (auth.kind === "jwt") {
-			const url = auth.region && auth.userPoolId ? buildCognitoJwksUrl(auth.region, auth.userPoolId) : buildJwksUrlFromIssuer(auth.issuer);
-			urls.add(url);
+function extractImageUri(value, logicalId, stackName, resources, region) {
+	if (typeof value === "string" && value.length > 0) return value;
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const obj = value;
+		const sub = obj["Fn::Sub"];
+		if (typeof sub === "string" && sub.length > 0) return sub;
+		if (Array.isArray(sub) && typeof sub[0] === "string") return sub[0];
+		if ("Fn::Join" in obj) {
+			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).`);
+			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.`);
 		}
 	}
-	await Promise.all([...urls].map((u) => jwksCache.fetchAndCache(u)));
 }
 /**
-* Emit a one-line warn for every VPC-config Lambda. The handler still
-* runs locally, but its container does not get attached to the AWS
-* VPC's subnets — calls to private RDS / ElastiCache will fail. cdk-local
-* surfaces this so the developer can pin the unexpected behavior to
-* the VPC config rather than chasing a "connection refused" rabbit
-* hole.
+* Build the IMAGE-variant `ResolvedStartApiLambda` from a Lambda
+* template entry with `Code.ImageUri`. Mirrors
+* `lambda-resolver.ts:extractImageLambdaProperties` but trimmed to the
+* fields `cdkl start-api` actually consumes.
 */
-function warnVpcConfigLambdas(routesWithAuth, stacks) {
-	const logger = getLogger();
-	const seen = /* @__PURE__ */ new Set();
-	const reachable = [];
-	for (const entry of routesWithAuth) {
-		if (!seen.has(entry.route.lambdaLogicalId)) {
-			seen.add(entry.route.lambdaLogicalId);
-			reachable.push(entry.route.lambdaLogicalId);
-		}
-		const auth = entry.authorizer;
-		if (auth && (auth.kind === "lambda-token" || auth.kind === "lambda-request")) {
-			if (!seen.has(auth.lambdaLogicalId)) {
-				seen.add(auth.lambdaLogicalId);
-				reachable.push(auth.lambdaLogicalId);
-			}
-		}
-	}
-	for (const logicalId of reachable) for (const stack of stacks) {
-		const resource = stack.template.Resources?.[logicalId];
-		if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
-		const vpcConfig = (resource.Properties ?? {})["VpcConfig"];
-		if (vpcConfig && typeof vpcConfig === "object" && Object.keys(vpcConfig).length > 0) logger.warn(`Lambda ${logicalId} has VpcConfig — local container will reach external services via the host's network, NOT through the deployed VPC's NAT/private subnets. Calls to private RDS/ElastiCache will fail.`);
-		break;
+function resolveImageLambda(args) {
+	const { stack, logicalId, resource, props, memoryMb, timeoutSec, imageUri } = args;
+	const rawImageConfig = props["ImageConfig"] ?? {};
+	const imageConfig = {};
+	if (Array.isArray(rawImageConfig["Command"])) imageConfig.command = rawImageConfig["Command"].filter((s) => typeof s === "string");
+	if (Array.isArray(rawImageConfig["EntryPoint"])) imageConfig.entryPoint = rawImageConfig["EntryPoint"].filter((s) => typeof s === "string");
+	if (typeof rawImageConfig["WorkingDirectory"] === "string") imageConfig.workingDirectory = rawImageConfig["WorkingDirectory"];
+	const arches = props["Architectures"];
+	let architecture = "x86_64";
+	if (Array.isArray(arches) && arches.length > 0) {
+		const first = arches[0];
+		if (first === "arm64") architecture = "arm64";
+		else if (first === "x86_64") architecture = "x86_64";
+		else throw new Error(`Lambda '${logicalId}' has unsupported Architectures value '${String(first)}'. ${getEmbedConfig().cliName} start-api supports x86_64 and arm64.`);
 	}
+	const ephemeralStorageMb = extractEphemeralStorageMb(props, logicalId);
+	return {
+		kind: "image",
+		stack,
+		logicalId,
+		resource,
+		memoryMb,
+		timeoutSec,
+		imageUri,
+		imageConfig,
+		architecture,
+		layers: [],
+		...ephemeralStorageMb !== void 0 && { ephemeralStorageMb }
+	};
 }
 /**
-* Walk the discovered routes for `AuthorizationType: 'AWS_IAM'` and emit
-* a one-line warn naming the affected routes. Returns `true` when at
-* least one IAM route is present so the caller wires the SigV4
-* credentials loader. Re-runs across hot reloads are silent — the warn
-* fires only at initial boot (matches `warnVpcConfigLambdas`'s policy).
+* Locate the Lambda's local code directory using the CDK-blessed
+* `Metadata['aws:asset:path']` hint. Bind-mounted directly at
+* `/var/task` (read-only) by the docker-runner.
+*/
+function resolveAssetCodePath(stack, logicalId, resource) {
+	const assetPath = resource.Metadata?.["aws:asset:path"];
+	if (typeof assetPath !== "string" || assetPath.length === 0) throw new Error(`Lambda '${logicalId}' has no Metadata['aws:asset:path']. ${getEmbedConfig().cliName} start-api needs this hint to find the local asset directory. Re-synthesize the app and retry.`);
+	const cdkOutDir = stack.assetManifestPath ? path.dirname(stack.assetManifestPath) : process.cwd();
+	return path.isAbsolute(assetPath) ? assetPath : path.resolve(cdkOutDir, assetPath);
+}
+/**
+* Print the discovered route table to stdout. Format mirrors the spec
+* doc's example so verify.sh / users can read it at a glance.
 *
-* Implementation note: signature verification only — IAM policy
-* evaluation (resource / action / condition) is NOT emulated. See
-* `src/local/sigv4-verify.ts` and the help text in `docs/cli-reference.md`.
+* Routes with `unsupported` or `mockCors` are annotated so the user can
+* tell at a glance which routes will dispatch to a Lambda vs which
+* return 501 / 204 directly:
+*   - normal:        `GET /items -> Handler  (HTTP API)`
+*   - mockCors:      `OPTIONS /items -> [MOCK CORS preflight]  (REST v1, stage 'prod')`
+*   - unsupported:   `POST /admin -> [501 Not Implemented]  (HTTP API)`
 */
-function warnIamRoutes(routesWithAuth) {
-	const logger = getLogger();
-	const iamRoutes = [];
-	const oacRoutes = [];
-	for (const entry of routesWithAuth) {
-		if (entry.authorizer?.kind !== "iam") continue;
-		if (entry.authorizer.oacFronted === true) oacRoutes.push(entry.route.declaredAt);
-		else iamRoutes.push(entry.route.declaredAt);
-	}
-	if (iamRoutes.length === 0 && oacRoutes.length === 0) return false;
-	if (iamRoutes.length > 0) {
-		logger.warn(`${iamRoutes.length} route(s) declare AuthorizationType: AWS_IAM — ${getEmbedConfig().cliName} start-api verifies the SigV4 signatures it CAN (requests signed with your local AWS credentials), but cannot verify a federated / Cognito Identity Pool / cross-account signer and does NOT emulate IAM policy evaluation (resource / action / condition rules). By default such unverifiable requests warn-and-pass with a placeholder principalId — pass --strict-sigv4 to deny them instead. Downstream authorization is the dev's responsibility.`);
-		for (const declaredAt of iamRoutes) logger.warn(`  - ${declaredAt}`);
-	}
-	if (oacRoutes.length > 0) {
-		logger.warn(`${oacRoutes.length} Function URL route(s) with AuthType: AWS_IAM are fronted by a CloudFront Origin Access Control. In production CloudFront re-signs the origin request, so no local client signature can be verified — ${getEmbedConfig().cliName} start-api passes these through (warn-and-pass) and they ignore --strict-sigv4. Do NOT trust the request identity in handler code.`);
-		for (const declaredAt of oacRoutes) logger.warn(`  - ${declaredAt}`);
+function printRouteTable(routes) {
+	const sorted = [...routes.map((r) => r.route)].sort((a, b) => {
+		if (a.pathPattern !== b.pathPattern) return a.pathPattern.localeCompare(b.pathPattern);
+		return a.method.localeCompare(b.method);
+	});
+	const methodWidth = Math.max(...sorted.map((r) => r.method.length), 6);
+	const pathWidth = Math.max(...sorted.map((r) => r.pathPattern.length), 8);
+	process.stdout.write("Discovered routes:\n");
+	for (const r of sorted) {
+		const sourceLabel = r.source === "http-api" ? "HTTP API" : r.source === "rest-v1" ? `REST v1, stage '${r.stage}'` : "Function URL";
+		const target = r.mockCors ? "[MOCK CORS preflight]" : r.unsupported ? "[501 Not Implemented]" : r.serviceIntegration ? `[${r.serviceIntegration.subtype}]` : r.restV1Integration ? formatRestV1IntegrationLabel(r.restV1Integration) : r.lambdaLogicalId;
+		process.stdout.write(`  ${r.method.padEnd(methodWidth)}  ${r.pathPattern.padEnd(pathWidth)}  -> ${target}  (${sourceLabel})\n`);
 	}
-	return true;
+	process.stdout.write("\n");
 }
 /**
-* Build the per-Lambda container spec — code dir, env vars (template +
-* --env-vars overlay), STS-issued creds when --assume-role names this
-* Lambda, optional --debug-port reservation. Errors out with a clear
-* message if the Lambda's code can't be resolved (asset directory
-* missing, runtime not supported).
+* Format the route-table label for a REST v1 non-AWS_PROXY integration.
+* `MOCK` / `HTTP` / `HTTP_PROXY` show their integration kind directly;
+* `AWS` (Lambda non-proxy) shows the Lambda logical id with an `[AWS]`
+* suffix so it's distinguishable from AWS_PROXY rows. Closes #457.
 */
-async function buildContainerSpec(args) {
-	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack, skipPull, layerRoleArn, profileCredentials, profileCredsFile, profileRegion, stackRegionOverride } = args;
-	const lambda = resolveLambdaByLogicalId(logicalId, stacks);
-	let codeDir;
-	let optDir;
-	let imageRef;
-	let platform;
-	if (lambda.kind === "zip") {
-		codeDir = lambda.codePath ?? materializeInlineCode$1(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
-		optDir = await materializeLambdaLayers(lambda.layers, layerTmpDirs, layerRoleArn);
-	} else {
-		imageRef = (await resolveContainerImageForStartApi(lambda, skipPull, args.profile)).imageRef;
-		platform = architectureToPlatform(lambda.architecture);
-	}
-	let templateEnv = getTemplateEnv(lambda.resource);
-	const stateBundle = stateByStack.get(lambda.stack.stackName);
-	let stateAudit;
-	if (stateBundle) {
-		const context = { resources: stateBundle.state.resources };
-		if (stateBundle.pseudoParameters) context.pseudoParameters = stateBundle.pseudoParameters;
-		if (stateBundle.ssmParameters) context.parameters = stateBundle.ssmParameters;
-		if (stateBundle.ssmSecureStringLogicalIds?.length) context.sensitiveParameters = new Set(stateBundle.ssmSecureStringLogicalIds);
-		const { env, audit } = substituteEnvVarsFromState(templateEnv, context);
-		templateEnv = env;
-		for (const key of audit.resolvedKeys) getLogger().debug(`Lambda ${logicalId}: state source substituted env var ${key}`);
-		let unresolved = audit.unresolved;
-		const resolvedKeys = [...audit.resolvedKeys];
-		const deployedEnv = stateBundle.deployedEnvByLambda?.get(logicalId);
-		if (unresolved.length > 0 && deployedEnv) {
-			const fb = applyDeployedEnvFallback(templateEnv, unresolved, deployedEnv);
-			templateEnv = fb.env;
-			unresolved = fb.stillUnresolved;
-			for (const key of fb.filled) {
-				resolvedKeys.push(key);
-				getLogger().debug(`Lambda ${logicalId}: filled env var ${key} from deployed function config`);
-			}
-		}
-		stateAudit = {
-			resolvedKeys,
-			unresolved,
-			sensitiveKeys: audit.sensitiveKeys
-		};
-		for (const { key, reason } of unresolved) getLogger().warn(`Lambda ${logicalId}: state source could not substitute env var ${key} (${reason}). Override it via --env-vars or it will be dropped.`);
-	}
-	const lambdaCdkPath = readCdkPathOrUndefined(lambda.resource);
-	const envResult = resolveEnvVars(logicalId, lambdaCdkPath, templateEnv, overrides);
-	for (const key of envResult.unresolved) {
-		if (stateAudit && stateAudit.unresolved.some((u) => u.key === key)) continue;
-		const overrideKeyExample = lambdaCdkPath?.replace(/\/Resource$/, "") ?? logicalId;
-		getLogger().warn(`Lambda ${logicalId}: env var ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${overrideKeyExample}":{"${key}":"<literal>"}}) or pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to recover deployed values.`);
-	}
-	const dockerEnv = {
-		AWS_LAMBDA_FUNCTION_NAME: logicalId,
-		AWS_LAMBDA_FUNCTION_MEMORY_SIZE: String(lambda.memoryMb),
-		AWS_LAMBDA_FUNCTION_TIMEOUT: String(lambda.timeoutSec),
-		AWS_LAMBDA_FUNCTION_VERSION: "$LATEST",
-		AWS_LAMBDA_LOG_GROUP_NAME: `/aws/lambda/${logicalId}`,
-		AWS_LAMBDA_LOG_STREAM_NAME: "local",
-		...envResult.resolved
-	};
-	const roleArn = effectiveAssumeRoleArn(logicalId, assumeRole);
-	if (roleArn) {
-		const creds = await assumeLambdaExecutionRole(roleArn, stsRegion);
-		dockerEnv["AWS_ACCESS_KEY_ID"] = creds.accessKeyId;
-		dockerEnv["AWS_SECRET_ACCESS_KEY"] = creds.secretAccessKey;
-		dockerEnv["AWS_SESSION_TOKEN"] = creds.sessionToken;
-		if (stsRegion) dockerEnv["AWS_REGION"] = stsRegion;
-	} else {
-		forwardAwsEnv$1(dockerEnv);
-		if (profileCredentials) {
-			dockerEnv["AWS_ACCESS_KEY_ID"] = profileCredentials.accessKeyId;
-			dockerEnv["AWS_SECRET_ACCESS_KEY"] = profileCredentials.secretAccessKey;
-			if (profileCredentials.sessionToken) dockerEnv["AWS_SESSION_TOKEN"] = profileCredentials.sessionToken;
-			else delete dockerEnv["AWS_SESSION_TOKEN"];
-		}
-		if (profileCredsFile) {
-			dockerEnv["AWS_SHARED_CREDENTIALS_FILE"] = profileCredsFile.containerPath;
-			dockerEnv["AWS_PROFILE"] = profileCredsFile.profileName;
-		}
-	}
-	if (!dockerEnv["AWS_REGION"]) {
-		const fallbackRegion = resolveContainerFallbackRegion({
-			stackRegionOverride,
-			synthRegion: lambda.stack.region,
-			profileRegion
-		});
-		if (fallbackRegion) dockerEnv["AWS_REGION"] = fallbackRegion;
+function formatRestV1IntegrationLabel(integration) {
+	switch (integration.kind) {
+		case "mock": return "[MOCK]";
+		case "http-proxy": return `[HTTP_PROXY ${integration.uri}]`;
+		case "http": return `[HTTP ${integration.uri}]`;
+		case "aws-lambda": return `${integration.lambdaLogicalId} [AWS]`;
 	}
-	if (debugPort !== void 0) dockerEnv["NODE_OPTIONS"] = `--inspect-brk=0.0.0.0:${debugPort}`;
-	const tmpfs = lambda.ephemeralStorageMb !== void 0 ? {
-		target: "/tmp",
-		sizeMb: lambda.ephemeralStorageMb
-	} : void 0;
-	const sensitiveEnvKeys = stateAudit && stateAudit.sensitiveKeys.length > 0 ? new Set(stateAudit.sensitiveKeys) : void 0;
-	if (lambda.kind === "zip") return {
-		kind: "zip",
-		lambda,
-		codeDir,
-		env: dockerEnv,
-		...sensitiveEnvKeys && { sensitiveEnvKeys },
-		containerHost,
-		...optDir !== void 0 && { optDir },
-		...debugPort !== void 0 && { debugPort },
-		...tmpfs !== void 0 && { tmpfs },
-		...profileCredsFile && { profileCredentialsFile: {
-			hostPath: profileCredsFile.hostPath,
-			containerPath: profileCredsFile.containerPath
-		} }
-	};
-	return {
-		kind: "image",
-		lambda,
-		image: imageRef,
-		platform,
-		command: lambda.imageConfig.command ?? [],
-		...lambda.imageConfig.entryPoint !== void 0 && lambda.imageConfig.entryPoint.length > 0 && { entryPoint: lambda.imageConfig.entryPoint },
-		...lambda.imageConfig.workingDirectory !== void 0 && { workingDir: lambda.imageConfig.workingDirectory },
-		env: dockerEnv,
-		...sensitiveEnvKeys && { sensitiveEnvKeys },
-		containerHost,
-		...debugPort !== void 0 && { debugPort },
-		...tmpfs !== void 0 && { tmpfs },
-		...profileCredsFile && { profileCredentialsFile: {
-			hostPath: profileCredsFile.hostPath,
-			containerPath: profileCredsFile.containerPath
-		} }
-	};
 }
 /**
-* Resolve a container Lambda's local docker image — local build from
-* `cdk.out` asset manifest first, ECR-pull fallback when the asset
-* manifest has no matching entry. Mirrors `cdkl invoke`'s
-* `resolveContainerImagePlan` shape; the start-api server doesn't
-* need the no-build flag (deterministic-tag cache reuse is automatic
-* across reloads because the per-Lambda tag is content-addressed).
-*
-* Same-account / same-region only on the ECR-pull path (matches the
-* `cdkl invoke` PR 5 of #224 boundary). Cross-account /
-* cross-region ECR pull is the W2-1 deferred follow-up.
+* Materialize an inline Lambda body (`Code.ZipFile`) to a tmpdir and
+* return the directory the container should mount at /var/task.
+* Mirrors `cdkl invoke`'s implementation; the only divergence is
+* the long-running-server lifecycle: every tmpdir created here is
+* recorded in `tmpDirsOut` so the caller's shutdown path can `rmSync`
+* them. (`cdkl invoke` runs once and `--rm` is the right model;
+* `cdkl start-api` lives across requests, so leaks compound.)
 */
-async function resolveContainerImageForStartApi(lambda, skipPull, profile) {
-	const logger = getLogger();
-	const localBuild = await resolveLocalBuildPlan(lambda);
-	if (localBuild) return { imageRef: await buildContainerImage(localBuild.asset, localBuild.cdkOutDir, { architecture: lambda.architecture }) };
-	if (!parseEcrUri(lambda.imageUri)) throw new Error(`Container Lambda '${lambda.logicalId}' has no matching asset in cdk.out, and Code.ImageUri '${lambda.imageUri}' is not an ECR URI ${getEmbedConfig().binaryName} can authenticate against. Re-synthesize the CDK app (so cdk.out includes the build context) or deploy the image to ECR first.`);
-	logger.info(`No matching cdk.out asset for ${lambda.imageUri}; falling back to ECR pull (same-acct/region only)...`);
-	return { imageRef: await pullEcrImage(lambda.imageUri, {
-		skipPull,
-		...profile !== void 0 && { profile }
-	}) };
+function materializeInlineCode$1(handler, source, fileExtension, tmpDirsOut) {
+	const lastDot = handler.lastIndexOf(".");
+	if (lastDot <= 0) throw new Error(`Handler '${handler}' is malformed: expected '<modulePath>.<exportName>'.`);
+	const modulePath = handler.substring(0, lastDot);
+	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-`));
+	tmpDirsOut.add(dir);
+	const filePath = path.join(dir, `${modulePath}${fileExtension}`);
+	mkdirSync(path.dirname(filePath), { recursive: true });
+	writeFileSync(filePath, source, "utf-8");
+	return dir;
+}
+/** Pull `Properties.Environment.Variables` (when present). */
+function getTemplateEnv(resource) {
+	const env = (resource.Properties ?? {})["Environment"];
+	if (!env || typeof env !== "object") return void 0;
+	const vars = env["Variables"];
+	if (!vars || typeof vars !== "object") return void 0;
+	return vars;
+}
+/** Read the SAM-shape `--env-vars` JSON file. */
+function readEnvOverridesFile$3(filePath) {
+	if (!filePath) return void 0;
+	let raw;
+	try {
+		raw = readFileSync(filePath, "utf-8");
+	} catch (err) {
+		throw new Error(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`--env-vars file '${filePath}' must contain a JSON object at the top level.`);
+	return parsed;
 }
 /**
-* Look up the docker image asset that backs a container Lambda.
-* Returns `undefined` when the asset manifest has no matching entry —
-* the caller falls back to the ECR-pull path.
-*
-* Mirrors `local-invoke.ts:resolveLocalBuildPlan`; kept separate so
-* the two commands evolve their asset-lookup heuristics independently.
+* Forward the developer's AWS credentials into the container so the
+* handler's AWS SDK calls can authenticate. Used when --assume-role is
+* NOT set for that Lambda — SAM-compatible default.
 */
-async function resolveLocalBuildPlan(lambda) {
-	const manifestPath = lambda.stack.assetManifestPath;
-	if (!manifestPath) return void 0;
-	const cdkOutDir = path.dirname(manifestPath);
-	const manifest = await new AssetManifestLoader().loadManifest(cdkOutDir, lambda.stack.stackName);
-	if (!manifest) return void 0;
-	const entry = getDockerImageBySourceHash(manifest, lambda.imageUri);
-	if (!entry) return void 0;
-	return {
-		asset: entry.asset,
-		cdkOutDir
-	};
+function forwardAwsEnv$2(env) {
+	for (const key of [
+		"AWS_ACCESS_KEY_ID",
+		"AWS_SECRET_ACCESS_KEY",
+		"AWS_SESSION_TOKEN",
+		"AWS_REGION",
+		"AWS_DEFAULT_REGION"
+	]) {
+		const value = process.env[key];
+		if (value !== void 0) env[key] = value;
+	}
 }
 /**
-* Build the `/opt` bind-mount source for a Lambda's layers. Mirrors
-* the helper in `src/cli/commands/local-invoke.ts` but stores the
-* merged tmpdir into the shared `layerTmpDirs` set so the server's
-* graceful shutdown path can clean it up. Returns `undefined` when
-* the function declares no layers.
+* Issue #654: resolve `--profile <p>` to a concrete credential set
+* for forwarding to Lambda containers.
 *
-* Three branches:
-*   - 0 layers → `undefined` (no `/opt` mount).
-*   - 1 layer → bind-mount the layer's asset dir directly (no copy)
-*     when the entry is a same-stack asset. Literal-ARN entries always
-*     pre-materialize first.
-*   - 2+ layers → copy each into a fresh tmpdir IN ORDER (later
-*     layers overwrite earlier files via `cpSync({force: true})`),
-*     bind-mount the tmpdir at `/opt`. Records the tmpdir in
-*     `layerTmpDirs` so `shutdown(...)` removes it.
+* The dev's AWS credentials may live in any of:
+*   - `~/.aws/sso/cache/*.json` (AWS IAM Identity Center / legacy SSO)
+*   - `~/.aws/credentials` (regular long-lived access keys)
+*   - `~/.aws/config` profiles with `role_arn` + `source_profile` (chained AssumeRole)
+*   - `credential_process` external resolvers
 *
-* Issue #448: literal-ARN entries (`{kind: 'arn', ...}`) are downloaded
-* + unzipped via `lambda:GetLayerVersion` BEFORE the cpSync-merge
-* branches run. Every per-ARN tmpdir is also recorded in `layerTmpDirs`
-* so the same shutdown path cleans it up — even for the single-layer
-* fast path that bind-mounts the dir directly.
+* `forwardAwsEnv` only reads `process.env.AWS_*`, which is empty for
+* every shape except "user manually exported the env vars". The
+* Lambda container therefore boots without creds and the handler's
+* AWS SDK call fails with `Could not load credentials from any providers`.
 *
-* AWS Lambda's actual runtime extracts every layer ZIP into `/opt`
-* in template order — the merge mirrors that. Docker rejects multiple
-* `-v ...:/opt:ro` entries at the same target, so cdk-local can't rely on
-* overlay layering and must produce a single merged dir on the host.
+* This helper constructs a transient `STSClient({ profile })` to drive
+* the SDK's default credential provider chain — same code path the
+* host's own AWS SDK clients use when `--profile` is set, so SSO / IAM
+* Identity Center / role-assumption profiles all resolve the same way
+* they already do for the host's outbound calls. We then extract the
+* resolved `AwsCredentialIdentity` via `sts.config.credentials()` and
+* return the underlying `{ accessKeyId, secretAccessKey, sessionToken? }`
+* for env-var injection.
+*
+* Called ONCE at server boot; the resolved creds are reused for every
+* Lambda container's env overlay (when `--assume-role` is not set for
+* that Lambda — assume-role wins per the existing precedence). SSO
+* temp creds typically last 1h+, so a single resolve is fine for the
+* common dev session; long-running `--watch` sessions that outlive
+* the creds need a cdk-local restart (deferred refresh out of scope for
+* v1, see issue #654).
+*
+* Also resolves the profile's configured `region` (from `~/.aws/config`'s
+* `region = ...` for this profile) off the same client config. The
+* synthesized credentials file we mount into the container carries only
+* the credential triple — no `region =` — so without this the container
+* boots with creds but no region, and a handler's ambient-region SDK call
+* (`new XxxClient({})`) fails with "Region is missing". The caller seeds
+* the container's `AWS_REGION` fallback with it (see
+* {@link resolveContainerFallbackRegion}). Region resolution is
+* best-effort: a profile with no region (or any resolution failure)
+* yields `region: undefined` rather than throwing — a missing region is
+* not a missing-credentials error.
 */
-async function materializeLambdaLayers(layers, layerTmpDirs, layerRoleArn) {
-	if (layers.length === 0) return void 0;
-	const flat = [];
-	for (const layer of layers) {
-		if (layer.kind === "asset") {
-			flat.push({
-				logicalId: layer.logicalId,
-				assetPath: layer.assetPath
-			});
-			continue;
+async function resolveProfileCredentials(profile) {
+	const { STSClient } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ profile });
+	try {
+		const credsProvider = sts.config.credentials;
+		const creds = typeof credsProvider === "function" ? await credsProvider() : credsProvider;
+		if (!creds || !creds.accessKeyId || !creds.secretAccessKey) throw new Error(`--profile '${profile}': credential provider chain resolved without usable credentials. Check \`aws sso login --profile ` + profile + "` for SSO profiles, or `~/.aws/credentials` / `~/.aws/config` for regular profiles.");
+		let region;
+		try {
+			const regionProvider = sts.config.region;
+			const resolved = typeof regionProvider === "function" ? await regionProvider() : regionProvider;
+			if (typeof resolved === "string" && resolved.length > 0) region = resolved;
+		} catch {
+			region = void 0;
 		}
-		const dir = await materializeLayerFromArn(layer, { ...layerRoleArn !== void 0 && { roleArn: layerRoleArn } });
-		layerTmpDirs.add(dir);
-		flat.push({
-			logicalId: layer.arn,
-			assetPath: dir
-		});
-	}
-	if (flat.length === 1) return flat[0].assetPath;
-	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-layers-`));
-	for (const layer of flat) cpSync(layer.assetPath, dir, {
-		recursive: true,
-		force: true
-	});
-	layerTmpDirs.add(dir);
-	return dir;
-}
-function resolveLambdaByLogicalId(logicalId, stacks) {
-	for (const stack of stacks) {
-		const resource = stack.template.Resources?.[logicalId];
-		if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
-		const props = resource.Properties ?? {};
-		const memoryMb = typeof props["MemorySize"] === "number" ? props["MemorySize"] : 128;
-		const timeoutSec = typeof props["Timeout"] === "number" ? props["Timeout"] : 3;
-		const code = props["Code"] ?? {};
-		const imageUri = extractImageUri(code["ImageUri"], logicalId, stack.stackName, stack.template.Resources ?? {}, stack.region);
-		if (imageUri !== void 0) return resolveImageLambda({
-			stack,
-			logicalId,
-			resource,
-			props,
-			memoryMb,
-			timeoutSec,
-			imageUri
-		});
-		const runtime = typeof props["Runtime"] === "string" ? props["Runtime"] : "";
-		const handler = typeof props["Handler"] === "string" ? props["Handler"] : "";
-		if (!runtime) throw new Error(`Lambda '${logicalId}' has no Runtime property and no Code.ImageUri. ${getEmbedConfig().cliName} start-api cannot tell if this is a ZIP or a container Lambda.`);
-		if (!handler) throw new Error(`Lambda '${logicalId}' has no Handler property.`);
-		const inlineCode = typeof code["ZipFile"] === "string" ? code["ZipFile"] : void 0;
-		let codePath = null;
-		if (!inlineCode) codePath = resolveAssetCodePath(stack, logicalId, resource);
-		const layers = resolveLambdaLayers(stack, logicalId, props);
-		const ephemeralStorageMb = extractEphemeralStorageMb(props, logicalId);
 		return {
-			kind: "zip",
-			stack,
-			logicalId,
-			resource,
-			runtime,
-			handler,
-			memoryMb,
-			timeoutSec,
-			codePath,
-			layers,
-			...inlineCode !== void 0 && { inlineCode },
-			...ephemeralStorageMb !== void 0 && { ephemeralStorageMb }
+			accessKeyId: creds.accessKeyId,
+			secretAccessKey: creds.secretAccessKey,
+			...creds.sessionToken && { sessionToken: creds.sessionToken },
+			...region && { region }
 		};
+	} finally {
+		sts.destroy();
 	}
-	throw new Error(`No AWS::Lambda::Function resource named '${logicalId}' found in target stacks. This is likely a synthesis bug — the route-discovery phase resolved a route to this logical ID.`);
 }
 /**
-* Extract `Code.ImageUri` across the shapes CDK actually synthesizes.
-* Mirrors the simpler subset of `lambda-resolver.ts:extractImageUri`
-* scoped to the shapes `cdkl start-api` consumes — flat string,
-* `Fn::Sub` (the canonical asset shape for
-* `lambda.DockerImageCode.fromImageAsset`), and `Fn::Join` (the
-* canonical shape for `lambda.DockerImageCode.fromImageAsset` in
-* CDK 2.x, which emits a `Fn::Join` over the literal bootstrap ECR
-* URI with `${AWS::URLSuffix}` — issues #627 + #637).
+* Resolve the fallback `AWS_REGION` for a Lambda container when neither
+* the assume-role STS region nor a forwarded `AWS_REGION` /
+* `AWS_DEFAULT_REGION` env var already set one.
 *
-* The `Fn::Join` arm routes through the shared
-* `tryResolveImageFnJoin` helper (`src/local/intrinsic-image.ts`) used
-* by `cdkl invoke`. When the synth template recorded a deploy
-* region (`stack.region`), we derive `{ urlSuffix, partition, region }`
-* via `derivePseudoParametersFromRegion` and pass it as the resolver's
-* `pseudoParameters` block so the canonical `${AWS::URLSuffix}` shape
-* resolves cleanly (issue #637). Same-stack ECR refs still surface as
-* `needs-state` (those require `--from-state`); a Join that references
-* `${AWS::AccountId}` without state still surfaces as `not-applicable`
-* with a more specific error message naming the missing parameter.
+* Precedence mirrors where the deployed function would actually run, so a
+* handler's ambient-region SDK call (`new XxxClient({})`) reaches the same
+* region locally as the resources it is bound to:
 *
-* Returns `undefined` when the field is absent or non-recognized,
-* which routes the caller to the ZIP branch (with its existing
-* "no Runtime / no Handler" validations).
+*   1. `--stack-region` — explicit; also drives the `--from-cfn-stack` CFn
+*      client, so the container matches the region the bound stack was read
+*      from.
+*   2. the synth-derived stack region — `env.region` on the CDK stack, read
+*      from the cloud assembly manifest (`StackInfo.region`). Previously
+*      used only host-side for the `--from-cfn-stack` CFn client; never
+*      injected into the container.
+*   3. the `--profile`'s configured region — `~/.aws/config`'s `region =`
+*      for the profile. `--profile` injected credentials but not this.
+*
+* Returns `undefined` when none is known; the caller leaves `AWS_REGION`
+* unset so the SDK's own "Region is missing" surfaces (the correct signal
+* for a region-agnostic stack with no profile region and no `AWS_REGION`
+* env).
 */
-function extractImageUri(value, logicalId, stackName, resources, region) {
-	if (typeof value === "string" && value.length > 0) return value;
-	if (value && typeof value === "object" && !Array.isArray(value)) {
-		const obj = value;
-		const sub = obj["Fn::Sub"];
-		if (typeof sub === "string" && sub.length > 0) return sub;
-		if (Array.isArray(sub) && typeof sub[0] === "string") return sub[0];
-		if ("Fn::Join" in obj) {
-			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).`);
-			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.`);
-		}
+function resolveContainerFallbackRegion(args) {
+	return args.stackRegionOverride ?? args.synthRegion ?? args.profileRegion;
+}
+/**
+* Issue an STS AssumeRole and return temporary credentials. Mirrors
+* `cdkl invoke`'s helper byte-for-byte; lifted here so the
+* start-api command stays self-contained.
+*/
+async function assumeLambdaExecutionRole(roleArn, region) {
+	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const creds = (await sts.send(new AssumeRoleCommand({
+			RoleArn: roleArn,
+			RoleSessionName: `${getEmbedConfig().resourceNamePrefix}-start-api-${Date.now()}`,
+			DurationSeconds: 3600
+		}))).Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new Error(`AssumeRole(${roleArn}) returned no usable credentials.`);
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			sessionToken: creds.SessionToken
+		};
+	} finally {
+		sts.destroy();
 	}
 }
 /**
-* Build the IMAGE-variant `ResolvedStartApiLambda` from a Lambda
-* template entry with `Code.ImageUri`. Mirrors
-* `lambda-resolver.ts:extractImageLambdaProperties` but trimmed to the
-* fields `cdkl start-api` actually consumes.
+* Parse / clamp the `--per-lambda-concurrency` flag. Above-cap values
+* are clamped to 4 with a warn line (per the spec doc's risk-mitigation
+* row).
 */
-function resolveImageLambda(args) {
-	const { stack, logicalId, resource, props, memoryMb, timeoutSec, imageUri } = args;
-	const rawImageConfig = props["ImageConfig"] ?? {};
-	const imageConfig = {};
-	if (Array.isArray(rawImageConfig["Command"])) imageConfig.command = rawImageConfig["Command"].filter((s) => typeof s === "string");
-	if (Array.isArray(rawImageConfig["EntryPoint"])) imageConfig.entryPoint = rawImageConfig["EntryPoint"].filter((s) => typeof s === "string");
-	if (typeof rawImageConfig["WorkingDirectory"] === "string") imageConfig.workingDirectory = rawImageConfig["WorkingDirectory"];
-	const arches = props["Architectures"];
-	let architecture = "x86_64";
-	if (Array.isArray(arches) && arches.length > 0) {
-		const first = arches[0];
-		if (first === "arm64") architecture = "arm64";
-		else if (first === "x86_64") architecture = "x86_64";
-		else throw new Error(`Lambda '${logicalId}' has unsupported Architectures value '${String(first)}'. ${getEmbedConfig().cliName} start-api supports x86_64 and arm64.`);
+function parsePerLambdaConcurrency(raw) {
+	const parsed = parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 1) throw new Error(`--per-lambda-concurrency must be a positive integer (got '${raw}')`);
+	if (parsed > 4) {
+		getLogger().warn(`--per-lambda-concurrency ${parsed} exceeds the v1 cap of 4; clamping to 4. (Raise this in a follow-up PR if your workload needs more.)`);
+		return 4;
 	}
-	const ephemeralStorageMb = extractEphemeralStorageMb(props, logicalId);
-	return {
-		kind: "image",
-		stack,
-		logicalId,
-		resource,
-		memoryMb,
-		timeoutSec,
-		imageUri,
-		imageConfig,
-		architecture,
-		layers: [],
-		...ephemeralStorageMb !== void 0 && { ephemeralStorageMb }
-	};
+	return parsed;
 }
 /**
-* Locate the Lambda's local code directory using the CDK-blessed
-* `Metadata['aws:asset:path']` hint. Bind-mounted directly at
-* `/var/task` (read-only) by the docker-runner.
+* Filter the global Lambda spec map to just the Lambdas reachable from
+* one API server group. The container pool for that server is built
+* from this filtered map so per-API authorizer Lambdas + route
+* handlers stay scoped to their owning server — disposing one server's
+* pool on shutdown does NOT touch another server's still-warm
+* containers.
+*
+* Also includes any authorizer Lambdas attached to the group's routes
+* (a Lambda authorizer is a Lambda the pool needs to know about, even
+* though no route directly handles `lambdaLogicalId === auth.lambdaLogicalId`).
 */
-function resolveAssetCodePath(stack, logicalId, resource) {
-	const assetPath = resource.Metadata?.["aws:asset:path"];
-	if (typeof assetPath !== "string" || assetPath.length === 0) throw new Error(`Lambda '${logicalId}' has no Metadata['aws:asset:path']. ${getEmbedConfig().cliName} start-api needs this hint to find the local asset directory. Re-synthesize the app and retry.`);
-	const cdkOutDir = stack.assetManifestPath ? path.dirname(stack.assetManifestPath) : process.cwd();
-	return path.isAbsolute(assetPath) ? assetPath : path.resolve(cdkOutDir, assetPath);
+function filterSpecsForGroup(group, allSpecs) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const rwa of group.routes) {
+		ids.add(rwa.route.lambdaLogicalId);
+		const auth = rwa.authorizer;
+		if (auth && (auth.kind === "lambda-token" || auth.kind === "lambda-request")) ids.add(auth.lambdaLogicalId);
+	}
+	const out = /* @__PURE__ */ new Map();
+	for (const id of ids) {
+		const spec = allSpecs.get(id);
+		if (spec) out.set(id, spec);
+	}
+	return out;
 }
 /**
-* Print the discovered route table to stdout. Format mirrors the spec
-* doc's example so verify.sh / users can read it at a glance.
-*
-* Routes with `unsupported` or `mockCors` are annotated so the user can
-* tell at a glance which routes will dispatch to a Lambda vs which
-* return 501 / 204 directly:
-*   - normal:        `GET /items -> Handler  (HTTP API)`
-*   - mockCors:      `OPTIONS /items -> [MOCK CORS preflight]  (REST v1, stage 'prod')`
-*   - unsupported:   `POST /admin -> [501 Not Implemented]  (HTTP API)`
+* Print one route table per server, with the server's display name as
+* the section header. Replaces the pre-issue #260 single flat table —
+* users now see exactly which routes belong to which API + port.
 */
-function printRouteTable(routes) {
-	const sorted = [...routes.map((r) => r.route)].sort((a, b) => {
-		if (a.pathPattern !== b.pathPattern) return a.pathPattern.localeCompare(b.pathPattern);
-		return a.method.localeCompare(b.method);
-	});
-	const methodWidth = Math.max(...sorted.map((r) => r.method.length), 6);
-	const pathWidth = Math.max(...sorted.map((r) => r.pathPattern.length), 8);
-	process.stdout.write("Discovered routes:\n");
-	for (const r of sorted) {
-		const sourceLabel = r.source === "http-api" ? "HTTP API" : r.source === "rest-v1" ? `REST v1, stage '${r.stage}'` : "Function URL";
-		const target = r.mockCors ? "[MOCK CORS preflight]" : r.unsupported ? "[501 Not Implemented]" : r.serviceIntegration ? `[${r.serviceIntegration.subtype}]` : r.restV1Integration ? formatRestV1IntegrationLabel(r.restV1Integration) : r.lambdaLogicalId;
-		process.stdout.write(`  ${r.method.padEnd(methodWidth)}  ${r.pathPattern.padEnd(pathWidth)}  -> ${target}  (${sourceLabel})\n`);
+function printPerServerRouteTables(servers) {
+	for (const { group, server } of servers) {
+		process.stdout.write(`\n${group.displayName}  (http://${server.host}:${server.port})\n`);
+		printRouteTable(group.routes);
 	}
-	process.stdout.write("\n");
 }
 /**
-* Format the route-table label for a REST v1 non-AWS_PROXY integration.
-* `MOCK` / `HTTP` / `HTTP_PROXY` show their integration kind directly;
-* `AWS` (Lambda non-proxy) shows the Lambda logical id with an `[AWS]`
-* suffix so it's distinguishable from AWS_PROXY rows. Closes #457.
+* Surface every `unsupported` route (deferred 501) as a startup warn so
+* the user sees what isn't reachable BEFORE they try to curl it. One
+* warn line per route — the route's `unsupported.reason` already names
+* the offender + the underlying limitation, so we just prefix with
+* method + path. Returns the number of unsupported routes so the caller
+* can emit a single-line summary header above the list.
 */
-function formatRestV1IntegrationLabel(integration) {
-	switch (integration.kind) {
-		case "mock": return "[MOCK]";
-		case "http-proxy": return `[HTTP_PROXY ${integration.uri}]`;
-		case "http": return `[HTTP ${integration.uri}]`;
-		case "aws-lambda": return `${integration.lambdaLogicalId} [AWS]`;
-	}
+function warnUnsupportedRoutes(routes, logger) {
+	const unsupported = routes.filter((r) => r.unsupported);
+	if (unsupported.length === 0) return 0;
+	logger.warn(`${unsupported.length} route(s) will respond HTTP 501 Not Implemented when hit (boot continued):`);
+	for (const r of unsupported) logger.warn(`  - ${r.method} ${r.pathPattern}: ${r.unsupported.reason}`);
+	return unsupported.length;
 }
 /**
-* Materialize an inline Lambda body (`Code.ZipFile`) to a tmpdir and
-* return the directory the container should mount at /var/task.
-* Mirrors `cdkl invoke`'s implementation; the only divergence is
-* the long-running-server lifecycle: every tmpdir created here is
-* recorded in `tmpDirsOut` so the caller's shutdown path can `rmSync`
-* them. (`cdkl invoke` runs once and `--rm` is the right model;
-* `cdkl start-api` lives across requests, so leaks compound.)
+* Surface every WebSocket API tagged as unsupported at discovery as a
+* startup warn. The boot loop above skips attaching the server for
+* these APIs, so no upgrade requests are ever accepted on them —
+* mirrors `warnUnsupportedRoutes`'s shape but for the WebSocket axis.
+* Typical trigger: a Route declaring `AuthorizationType !== 'NONE'` on
+* `$connect` (cdkl v1 does not emulate WebSocket authorizers; closing
+* this gap structurally rather than silently admitting
+* unauthenticated clients matches the security-by-default precedent
+* PR #514 set for HTTP API v2 service integrations).
 */
-function materializeInlineCode$1(handler, source, fileExtension, tmpDirsOut) {
-	const lastDot = handler.lastIndexOf(".");
-	if (lastDot <= 0) throw new Error(`Handler '${handler}' is malformed: expected '<modulePath>.<exportName>'.`);
-	const modulePath = handler.substring(0, lastDot);
-	const dir = mkdtempSync(path.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-`));
-	tmpDirsOut.add(dir);
-	const filePath = path.join(dir, `${modulePath}${fileExtension}`);
-	mkdirSync(path.dirname(filePath), { recursive: true });
-	writeFileSync(filePath, source, "utf-8");
-	return dir;
+function warnUnsupportedWebSocketApis(apis, logger) {
+	const unsupported = apis.filter((api) => api.unsupported);
+	if (unsupported.length === 0) return 0;
+	logger.warn(`${unsupported.length} WebSocket API(s) will NOT accept upgrade requests (boot continued):`);
+	for (const api of unsupported) logger.warn(`  - ${api.declaredAt}: ${api.unsupported.reason}`);
+	return unsupported.length;
 }
-/** Pull `Properties.Environment.Variables` (when present). */
-function getTemplateEnv(resource) {
-	const env = (resource.Properties ?? {})["Environment"];
-	if (!env || typeof env !== "object") return void 0;
-	const vars = env["Variables"];
-	if (!vars || typeof vars !== "object") return void 0;
-	return vars;
+/**
+* Surface a one-line warn per HTTP / HTTP_PROXY integration whose
+* `Integration.Uri` points at a well-known internal address space
+* (AWS IMDS, loopback, link-local, RFC1918). PR #505 / issue #457
+* follow-up: cdk-local does NOT block these — warn-and-proceed matches the
+* cognito JWKS pass-through pattern — but the user should see the
+* destination at boot so a malicious / typo'd template Uri does not
+* silently exfiltrate credentials in CI. Deduplicated per-Uri.
+*/
+function warnSsrfRiskyIntegrations(routes, logger) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const r of routes) {
+		const integ = r.restV1Integration;
+		if (!integ) continue;
+		if (integ.kind !== "http" && integ.kind !== "http-proxy") continue;
+		if (seen.has(integ.uri)) continue;
+		seen.add(integ.uri);
+		warnSsrfRiskyUri(integ.uri, `${r.method} ${r.pathPattern}`, (msg) => logger.warn(msg));
+	}
 }
-/** Read the SAM-shape `--env-vars` JSON file. */
-function readEnvOverridesFile$1(filePath) {
-	if (!filePath) return void 0;
-	let raw;
+/**
+* One reload cycle for the multi-server topology (issue #260). The
+* watcher serializes calls via a chain promise; this function:
+*
+*   1. Re-runs `synthesizeAndBuild()` once (failure → warn + keep
+*      previous version serving on every server).
+*   2. Re-groups the new routes by API server key.
+*   3. For each existing server, swaps state to the new group's
+*      routes + a freshly-built pool filtered to that group's
+*      Lambdas. Disposes the previous pool in the background.
+*   4. Warns about new groups (= an API was added in CDK code) and
+*      vanished groups (= an API was removed) — those require a
+*      server restart in v1.
+*/
+async function reloadAllServers(args) {
+	const { synthesizeAndBuild, servers, buildPool, logger } = args;
+	let material;
 	try {
-		raw = readFileSync(filePath, "utf-8");
+		material = await synthesizeAndBuild();
 	} catch (err) {
-		throw new Error(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+		logger.warn(`cdk synth failed during reload; keeping previous version. (${err instanceof Error ? err.message : String(err)})`);
+		return;
 	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (err) {
-		throw new Error(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	const newGroups = groupRoutesByServer(material.routes);
+	const newByKey = new Map(newGroups.map((g) => [g.serverKey, g]));
+	const oldKeys = new Set(servers.map((s) => s.group.serverKey));
+	const newKeys = new Set(newByKey.keys());
+	const added = [...newKeys].filter((k) => !oldKeys.has(k));
+	const removed = [...oldKeys].filter((k) => !newKeys.has(k));
+	if (added.length > 0) logger.warn(`Reload detected new API surface(s): ${added.join(", ")}. Restart '${getEmbedConfig().cliName} start-api' to serve them.`);
+	if (removed.length > 0) logger.warn(`Reload detected removed API surface(s): ${removed.join(", ")}. Their servers will keep serving stale routes until restart.`);
+	for (const booted of servers) {
+		const group = newByKey.get(booted.group.serverKey);
+		if (!group) continue;
+		const newPool = buildPool(filterSpecsForGroup(group, material.specs));
+		const newState = {
+			routes: group.routes,
+			pool: newPool,
+			corsConfigByApiId: material.corsConfigByApiId
+		};
+		const previousState = booted.server.setServerState(newState);
+		booted.group = group;
+		previousState.pool.dispose().catch((err) => {
+			logger.debug(`Previous pool dispose() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
+		});
+	}
+	printPerServerRouteTables(servers);
+	const allRoutes = servers.flatMap((s) => s.group.routes.map((r) => r.route));
+	warnUnsupportedRoutes(allRoutes, logger);
+	warnSsrfRiskyIntegrations(allRoutes, logger);
+}
+/**
+* Returns true when any value in the function's template env map is a
+* CFn intrinsic (non-primitive). Used to gate the pseudo-parameter STS
+* hop inside the `--from-state` flow: literal-only env maps don't need
+* the pseudo-parameter bag and shouldn't pay for an STS call. Mirrors
+* the same gating in `local-invoke.ts` (`envHasIntrinsicValue`) and
+* `ecs-task-resolver.ts` (`containerHasIntrinsicEnvOrSecret`).
+*/
+function envHasIntrinsicValue(templateEnv) {
+	if (!templateEnv) return false;
+	for (const v of Object.values(templateEnv)) {
+		if (v === void 0 || v === null) continue;
+		if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") continue;
+		return true;
 	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`--env-vars file '${filePath}' must contain a JSON object at the top level.`);
-	return parsed;
+	return false;
 }
 /**
-* Forward the developer's AWS credentials into the container so the
-* handler's AWS SDK calls can authenticate. Used when --assume-role is
-* NOT set for that Lambda — SAM-compatible default.
+* Load deployed state for every stack that owns a routed Lambda. Once
+* per `synthesizeAndBuild` pass (initial boot + every reload), so a
+* Lambda's per-spec build does not pay one round-trip per Lambda. Per-
+* stack failures (no state, ambiguous region, bucket resolution error)
+* degrade to warn-and-fall-back via the active `LocalStateProvider` —
+* the affected stack's reachable Lambdas behave as if `--from-state` /
+* `--from-cfn-stack` were not set, while sibling stacks with loadable
+* state still substitute.
+*
+* Pseudo parameters are resolved per stack and only when at least one
+* reachable Lambda in that stack has an intrinsic-valued env entry
+* (gated via {@link envHasIntrinsicValue}). STS failures degrade to
+* warn and leave `pseudoParameters: undefined` — substitution still
+* runs for non-`AWS::*` refs.
 */
-function forwardAwsEnv$1(env) {
-	for (const key of [
-		"AWS_ACCESS_KEY_ID",
-		"AWS_SECRET_ACCESS_KEY",
-		"AWS_SESSION_TOKEN",
-		"AWS_REGION",
-		"AWS_DEFAULT_REGION"
-	]) {
-		const value = process.env[key];
-		if (value !== void 0) env[key] = value;
+/**
+* Returns true when at least one host-provided extra state-provider flag
+* is active in the options bag.
+*/
+function hasExtraStateProviderActive(options, extraStateProviders) {
+	if (!extraStateProviders) return false;
+	for (const key of Object.keys(extraStateProviders)) if (options[key]) return true;
+	return false;
+}
+async function loadStateForRoutedStacks(stacks, routes, routesWithAuth, options, extraStateProviders) {
+	const logger = getLogger();
+	const out = /* @__PURE__ */ new Map();
+	const lambdaIds = uniqueLambdaIds(routes, routesWithAuth);
+	const reachableStackNames = /* @__PURE__ */ new Set();
+	for (const logicalId of lambdaIds) for (const stack of stacks) {
+		const resource = stack.template.Resources?.[logicalId];
+		if (resource && resource.Type === "AWS::Lambda::Function") {
+			reachableStackNames.add(stack.stackName);
+			break;
+		}
+	}
+	const stackHasIntrinsicEnv = (stackName) => {
+		for (const logicalId of lambdaIds) for (const stack of stacks) {
+			if (stack.stackName !== stackName) continue;
+			const resource = stack.template.Resources?.[logicalId];
+			if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
+			if (envHasIntrinsicValue(getTemplateEnv(resource))) return true;
+		}
+		return false;
+	};
+	rejectExplicitCfnStackWithMultipleStacks(options, reachableStackNames.size);
+	for (const stackName of reachableStackNames) {
+		const stack = stacks.find((s) => s.stackName === stackName);
+		if (!stack) continue;
+		const provider = createLocalStateProvider(options, stack.stackName, await resolveCfnFallbackRegion(options, stack.region), extraStateProviders);
+		if (!provider) continue;
+		try {
+			const loaded = await provider.load(stack.stackName, stack.region);
+			if (!loaded) continue;
+			const bundle = { state: {
+				version: 1,
+				stackName: stack.stackName,
+				resources: loaded.resources,
+				outputs: loaded.outputs,
+				lastModified: 0
+			} };
+			if (stackHasIntrinsicEnv(stackName)) {
+				const pseudo = await resolvePseudoParametersForStartApi(loaded.region, options);
+				if (pseudo) bundle.pseudoParameters = pseudo;
+			}
+			if (provider.resolveDeployedFunctionEnv) {
+				const deployedEnvByLambda = /* @__PURE__ */ new Map();
+				for (const logicalId of lambdaIds) {
+					const resource = stack.template.Resources?.[logicalId];
+					if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
+					if (!envHasIntrinsicValue(getTemplateEnv(resource))) continue;
+					const physicalId = loaded.resources[logicalId]?.physicalId;
+					if (!physicalId) continue;
+					const deployedEnv = await provider.resolveDeployedFunctionEnv(physicalId);
+					if (deployedEnv) deployedEnvByLambda.set(logicalId, deployedEnv);
+				}
+				if (deployedEnvByLambda.size > 0) bundle.deployedEnvByLambda = deployedEnvByLambda;
+			}
+			if (stackHasIntrinsicEnv(stackName) && provider.resolveTemplateSsmParameters) {
+				const ssmParameters = await provider.resolveTemplateSsmParameters(stack.template);
+				if (Object.keys(ssmParameters.values).length > 0) bundle.ssmParameters = ssmParameters.values;
+				if (ssmParameters.secureStringLogicalIds.length > 0) bundle.ssmSecureStringLogicalIds = ssmParameters.secureStringLogicalIds;
+			}
+			out.set(stackName, bundle);
+			logger.debug(`${provider.label}: loaded state for ${stackName} (${loaded.region})`);
+		} finally {
+			provider.dispose();
+		}
 	}
+	return out;
 }
 /**
-* Issue #654: resolve `--profile <p>` to a concrete credential set
-* for forwarding to Lambda containers.
-*
-* The dev's AWS credentials may live in any of:
-*   - `~/.aws/sso/cache/*.json` (AWS IAM Identity Center / legacy SSO)
-*   - `~/.aws/credentials` (regular long-lived access keys)
-*   - `~/.aws/config` profiles with `role_arn` + `source_profile` (chained AssumeRole)
-*   - `credential_process` external resolvers
-*
-* `forwardAwsEnv` only reads `process.env.AWS_*`, which is empty for
-* every shape except "user manually exported the env vars". The
-* Lambda container therefore boots without creds and the handler's
-* AWS SDK call fails with `Could not load credentials from any providers`.
-*
-* This helper constructs a transient `STSClient({ profile })` to drive
-* the SDK's default credential provider chain — same code path the
-* host's own AWS SDK clients use when `--profile` is set, so SSO / IAM
-* Identity Center / role-assumption profiles all resolve the same way
-* they already do for the host's outbound calls. We then extract the
-* resolved `AwsCredentialIdentity` via `sts.config.credentials()` and
-* return the underlying `{ accessKeyId, secretAccessKey, sessionToken? }`
-* for env-var injection.
-*
-* Called ONCE at server boot; the resolved creds are reused for every
-* Lambda container's env overlay (when `--assume-role` is not set for
-* that Lambda — assume-role wins per the existing precedence). SSO
-* temp creds typically last 1h+, so a single resolve is fine for the
-* common dev session; long-running `--watch` sessions that outlive
-* the creds need a cdk-local restart (deferred refresh out of scope for
-* v1, see issue #654).
+* Build the AWS pseudo-parameter bag for `--from-state` env-var
+* substitution. Mirrors `resolvePseudoParametersForInvoke` in
+* `local-invoke.ts` byte-for-byte — kept inlined here rather than
+* extracted into a shared helper because the two call sites differ in
+* region precedence (this one is per-stack so the resolved state
+* region takes priority).
 *
-* Also resolves the profile's configured `region` (from `~/.aws/config`'s
-* `region = ...` for this profile) off the same client config. The
-* synthesized credentials file we mount into the container carries only
-* the credential triple — no `region =` — so without this the container
-* boots with creds but no region, and a handler's ambient-region SDK call
-* (`new XxxClient({})`) fails with "Region is missing". The caller seeds
-* the container's `AWS_REGION` fallback with it (see
-* {@link resolveContainerFallbackRegion}). Region resolution is
-* best-effort: a profile with no region (or any resolution failure)
-* yields `region: undefined` rather than throwing — a missing region is
-* not a missing-credentials error.
+* Region precedence: `--region` > `AWS_REGION` > `AWS_DEFAULT_REGION` >
+* the state record's region (returned by the active `LocalStateProvider`).
 */
-async function resolveProfileCredentials(profile) {
-	const { STSClient } = await import("@aws-sdk/client-sts");
-	const sts = new STSClient({ profile });
+async function resolvePseudoParametersForStartApi(stateRegion, options) {
+	const logger = getLogger();
+	const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? stateRegion;
+	let accountId;
 	try {
-		const credsProvider = sts.config.credentials;
-		const creds = typeof credsProvider === "function" ? await credsProvider() : credsProvider;
-		if (!creds || !creds.accessKeyId || !creds.secretAccessKey) throw new Error(`--profile '${profile}': credential provider chain resolved without usable credentials. Check \`aws sso login --profile ` + profile + "` for SSO profiles, or `~/.aws/credentials` / `~/.aws/config` for regular profiles.");
-		let region;
+		const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+		const sts = new STSClient({ ...region && { region } });
 		try {
-			const regionProvider = sts.config.region;
-			const resolved = typeof regionProvider === "function" ? await regionProvider() : regionProvider;
-			if (typeof resolved === "string" && resolved.length > 0) region = resolved;
-		} catch {
-			region = void 0;
+			accountId = (await sts.send(new GetCallerIdentityCommand({}))).Account;
+		} finally {
+			sts.destroy();
 		}
-		return {
-			accessKeyId: creds.accessKeyId,
-			secretAccessKey: creds.secretAccessKey,
-			...creds.sessionToken && { sessionToken: creds.sessionToken },
-			...region && { region }
-		};
-	} finally {
-		sts.destroy();
+	} catch (err) {
+		logger.warn(`--from-state: resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped for AWS::AccountId; affected env entries will be dropped with per-key warnings.`);
 	}
+	const partitionAndSuffix = region ? derivePartitionAndUrlSuffix(region) : void 0;
+	const bag = {
+		...accountId !== void 0 && { accountId },
+		...region !== void 0 && { region },
+		...partitionAndSuffix && {
+			partition: partitionAndSuffix.partition,
+			urlSuffix: partitionAndSuffix.urlSuffix
+		}
+	};
+	return Object.keys(bag).length === 0 ? void 0 : bag;
+}
+/** Validate `--debug-port-base`. */
+function parseDebugPort(raw) {
+	const parsed = parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) throw new Error(`--debug-port-base must be 1..65535 (got '${raw}')`);
+	return parsed;
 }
 /**
-* Resolve the fallback `AWS_REGION` for a Lambda container when neither
-* the assume-role STS region nor a forwarded `AWS_REGION` /
-* `AWS_DEFAULT_REGION` env var already set one.
-*
-* Precedence mirrors where the deployed function would actually run, so a
-* handler's ambient-region SDK call (`new XxxClient({})`) reaches the same
-* region locally as the resources it is bound to:
+* Resolve the mTLS configuration from CLI options. Returns `undefined`
+* when none of the three `--mtls-*` flags is set (the server stays
+* plain-HTTP). When any of the three is set, ALL THREE must be set —
+* partial configurations are rejected at parse time so the server
+* never boots in a half-configured state.
 *
-*   1. `--stack-region` — explicit; also drives the `--from-cfn-stack` CFn
-*      client, so the container matches the region the bound stack was read
-*      from.
-*   2. the synth-derived stack region — `env.region` on the CDK stack, read
-*      from the cloud assembly manifest (`StackInfo.region`). Previously
-*      used only host-side for the `--from-cfn-stack` CFn client; never
-*      injected into the container.
-*   3. the `--profile`'s configured region — `~/.aws/config`'s `region =`
-*      for the profile. `--profile` injected credentials but not this.
+* Exported for unit testing.
+*/
+function resolveMtlsConfig(options) {
+	const present = [];
+	const absent = [];
+	if (options.mtlsTruststore !== void 0 && options.mtlsTruststore !== "") present.push("--mtls-truststore");
+	else absent.push("--mtls-truststore");
+	if (options.mtlsCert !== void 0 && options.mtlsCert !== "") present.push("--mtls-cert");
+	else absent.push("--mtls-cert");
+	if (options.mtlsKey !== void 0 && options.mtlsKey !== "") present.push("--mtls-key");
+	else absent.push("--mtls-key");
+	if (present.length === 0) return void 0;
+	if (absent.length > 0) throw new Error(`mTLS configuration is incomplete: ${present.join(", ")} set but ${absent.join(", ")} missing. All three of --mtls-truststore, --mtls-cert, and --mtls-key must be set together to enable mTLS, or all three left unset for plain HTTP.`);
+	return readMtlsMaterialsFromDisk({
+		truststorePath: options.mtlsTruststore,
+		certPath: options.mtlsCert,
+		keyPath: options.mtlsKey
+	});
+}
+/**
+* Builder for the `start-api` subcommand.
+*/
+function createLocalStartApiCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and AWS_IAM auth (REST v1 `AuthorizationType: AWS_IAM` and Function URL `AuthType: AWS_IAM` — SigV4 signature verification only; IAM policy evaluation is NOT emulated). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[targets...]", `Optional API subset filter. Pass one or more identifiers to serve exactly that subset (the union; each on its own port). Each accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted in a TTY, a multi-select picker opens with every API pre-selected (Enter serves all, deselect to pick a subset); when omitted in a non-TTY (CI / pipe) every discovered API is served. Mirrors \`${getEmbedConfig().cliName} invoke\` / \`${getEmbedConfig().cliName} run-task\` target syntax.`).action(withErrorHandling(async (targets, options) => {
+		await localStartApiCommand(targets, options, opts.extraStateProviders);
+	}));
+	addStartApiSpecificOptions(startApi);
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((opt) => startApi.addOption(opt));
+	startApi.addOption(deprecatedRegionOption);
+	return startApi;
+}
+/**
+* Register the option block that `cdkl start-api` adds on top of the shared
+* common / app / context option helpers. Shared between `cdkl start-api`
+* and any host CLI (e.g. cdkd's `local start-api`) that wraps the
+* long-running API-Gateway-fronted local HTTP server, so adding or
+* renaming a `start-api`-only flag here propagates to every embedder
+* without duplicate `.addOption(...)` blocks.
 *
-* Returns `undefined` when none is known; the caller leaves `AWS_REGION`
-* unset so the SDK's own "Region is missing" surfaces (the correct signal
-* for a region-agnostic stack with no profile region and no `AWS_REGION`
-* env).
+* Calling order only affects `--help` presentation (Commander parses
+* insertion-order-independent). The host-CLI convention is host-specific
+* options first, then this helper, then the shared common / app / context
+* options — host flags / start-api flags / common flags grouped in three
+* `--help` clusters. Chainable: returns `cmd`.
 */
-function resolveContainerFallbackRegion(args) {
-	return args.stackRegionOverride ?? args.synthRegion ?? args.profileRegion;
+function addStartApiSpecificOptions(cmd) {
+	return cmd.addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--all-stacks", "Serve every stack's API in a multi-stack app (each API on its own port) instead of erroring out. Mutually exclusive with a positional target subset, --stack, and an explicit --from-cfn-stack <name>; the bare --from-cfn-stack flag stays compatible (binds each routed stack to its own CFn stack).").default(false)).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when the CDK app's source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <targets...> argument instead. Accepts a SINGLE identifier; for a subset pass multiple positional targets. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).addOption(new Option("--mtls-truststore <path>", `PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj "/CN=${getEmbedConfig().resourceNamePrefix}-ca" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj "/CN=localhost"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj "/CN=client"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...`)).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--strict-sigv4", "Opt-in: DENY AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id — e.g. a federated / Cognito Identity Pool / cross-account signer — OR no local AWS credentials configured) instead of the default warn-and-pass. DEFAULT off: cdk-local warn-and-passes unverifiable IAM requests with a placeholder principalId so local dev exercises app logic without reproducing an auth boundary it cannot fully emulate. OAC-fronted Function URLs always warn-and-pass regardless.").default(false));
 }
+
+//#endregion
+//#region src/cli/commands/local-invoke-agentcore.ts
 /**
-* Issue an STS AssumeRole and return temporary credentials. Mirrors
-* `cdkl invoke`'s helper byte-for-byte; lifted here so the
-* start-api command stays self-contained.
+* Parser for `--timeout <ms>`. Accepts a positive integer; rejects 0,
+* negatives, fractions, and non-numeric input.
 */
-async function assumeLambdaExecutionRole(roleArn, region) {
-	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
-	const sts = new STSClient({ ...region && { region } });
+function parseTimeoutMs(raw) {
+	const parsed = Number(raw);
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new CdkLocalError(`--timeout must be a positive integer number of milliseconds (got '${raw}').`, "LOCAL_INVOKE_AGENTCORE_TIMEOUT_INVALID");
+	return parsed;
+}
+/**
+* `cdkl invoke-agentcore <target>` — run a Bedrock AgentCore Runtime container
+* locally and invoke it once over the AgentCore HTTP contract. Resolves
+* the `AWS::BedrockAgentCore::Runtime`, pulls / builds its container,
+* starts it on port 8080, waits for `GET /ping`, POSTs the event to
+* `POST /invocations`, prints the response, and tears down. Covers the
+* container artifact and the CodeConfiguration managed-runtime artifact
+* (fromCodeAsset, built from source) on the HTTP + MCP protocols; the agent's
+* calls to real AWS go to real AWS (credentials injected like `cdkl invoke`).
+*/
+async function localInvokeAgentCoreCommand(target, options, extraStateProviders) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(options);
+	let containerId;
+	let stopLogs;
+	let sigintHandler;
+	let profileCredsFile;
+	let stateProvider;
+	const cleanup = singleFlight(async () => {
+		if (stateProvider) try {
+			stateProvider.dispose();
+		} catch (err) {
+			getLogger().debug(`state provider dispose failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (stopLogs) try {
+			stopLogs();
+		} catch (err) {
+			getLogger().debug(`streamLogs stop failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (containerId) try {
+			await removeContainer(containerId);
+		} catch (err) {
+			getLogger().debug(`removeContainer(${containerId}) failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (profileCredsFile) try {
+			await profileCredsFile.dispose();
+		} catch (err) {
+			getLogger().debug(`Failed to remove profile credentials tmpdir ${profileCredsFile.hostPath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}, (err) => {
+		getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+	});
 	try {
-		const creds = (await sts.send(new AssumeRoleCommand({
-			RoleArn: roleArn,
-			RoleSessionName: `${getEmbedConfig().resourceNamePrefix}-start-api-${Date.now()}`,
-			DurationSeconds: 3600
-		}))).Credentials;
-		if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new Error(`AssumeRole(${roleArn}) returned no usable credentials.`);
-		return {
-			accessKeyId: creds.AccessKeyId,
-			secretAccessKey: creds.SecretAccessKey,
-			sessionToken: creds.SessionToken
+		await applyRoleArnIfSet({
+			roleArn: options.roleArn,
+			region: options.region
+		});
+		await ensureDockerAvailable();
+		const profileCredentials = options.profile ? await resolveProfileCredentials(options.profile) : void 0;
+		if (options.profile && profileCredentials) profileCredsFile = await writeProfileCredentialsFile(options.profile, profileCredentials);
+		const appCmd = resolveApp(options.app);
+		if (!appCmd) throw new Error(`No CDK app specified. Pass --app, set ${getEmbedConfig().envPrefix}_APP, or add "app" to cdk.json.`);
+		logger.info("Synthesizing CDK app...");
+		const synthesizer = new Synthesizer();
+		const context = parseContextOptions(options.context);
+		const synthOpts = {
+			app: appCmd,
+			output: options.output,
+			...options.region && { region: options.region },
+			...options.profile && { profile: options.profile },
+			...Object.keys(context).length > 0 && { context }
+		};
+		const { stacks } = await synthesizer.synthesize(synthOpts);
+		const resolvedTarget = await resolveSingleTarget(target, {
+			entries: listTargets(stacks).agentCoreRuntimes,
+			message: "Select an AgentCore Runtime to invoke",
+			noun: "AgentCore Runtimes",
+			onMissing: () => new CdkLocalError(`${getEmbedConfig().cliName} invoke-agentcore requires a <target> (an AgentCore Runtime display path or logical ID). Run \`${getEmbedConfig().cliName} list\` to see them, or run it in a TTY to pick interactively.`, "LOCAL_INVOKE_AGENTCORE_TARGET_REQUIRED")
+		});
+		const candidate = pickAgentCoreCandidateStack(resolvedTarget, stacks);
+		stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
+		const { context: imageContext, loaded: loadedState } = stateProvider && candidate ? await buildAgentCoreImageContext(candidate, stateProvider, options) : {
+			context: void 0,
+			loaded: void 0
+		};
+		const resolved = resolveAgentCoreTarget(resolvedTarget, stacks, imageContext);
+		logger.info(`Target: ${resolved.stack.stackName}/${resolved.logicalId} (${resolved.protocol})`);
+		const isMcp = resolved.protocol === "MCP";
+		const isA2a = resolved.protocol === "A2A";
+		if (resolved.protocol === "AGUI") logger.info("AGUI runtime: routing through the HTTP /invocations + /ws path (AG-UI wire is SSE / WebSocket on port 8080).");
+		if ((isMcp || isA2a) && options.ws) logger.warn(`--ws applies only to the HTTP / AGUI protocols; ignoring it for this ${resolved.protocol} runtime.`);
+		if (options.wsInteractive && !options.ws) logger.warn("--ws-interactive is meaningful only with --ws; ignoring.");
+		if (options.sigv4 && (isMcp || isA2a || options.ws)) logger.warn("--sigv4 signs the HTTP /invocations request only; ignoring it for the " + (isMcp ? "MCP" : isA2a ? "A2A" : "/ws WebSocket") + " path.");
+		const sessionId = options.sessionId ?? randomUUID();
+		const event = await readEvent(options);
+		const mcpRequest = isMcp ? buildMcpRequest(event) : void 0;
+		const a2aRequest = isA2a ? buildA2aRequest(event) : void 0;
+		let authorization;
+		if (isMcp || isA2a) {
+			if (resolved.jwtAuthorizer || options.bearerToken) {
+				const pathLabel = isMcp ? MCP_PATH : "/";
+				logger.info(`${resolved.protocol} runtime: invoking the local container's ${pathLabel} directly (vanilla ${resolved.protocol}). An inbound JWT / --bearer-token is an AgentCore managed-plane concern and is not applied locally.`);
+			}
+		} else authorization = await resolveInboundAuthorization(resolved, options);
+		await resolveFromS3BucketIntrinsic(resolved, stateProvider, loadedState, imageContext);
+		const image = await resolveAgentCoreImage(resolved, options, loadedState, stateProvider);
+		const { env: dockerEnv, sensitiveEnvKeys } = await buildContainerEnv(resolved, options, profileCredentials, profileCredsFile, stateProvider, loadedState, imageContext);
+		const hostPort = await pickFreePort();
+		const containerHost = options.containerHost;
+		const containerName = `${getEmbedConfig().resourceNamePrefix}-agentcore-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+		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({
+			image,
+			mounts: [],
+			env: dockerEnv,
+			cmd: [],
+			hostPort,
+			host: containerHost,
+			platform: options.platform,
+			name: containerName,
+			...containerPort !== void 0 && { containerPort },
+			...sensitiveEnvKeys.size > 0 && { sensitiveEnvKeys }
+		});
+		stopLogs = streamLogs(containerId);
+		sigintHandler = () => {
+			cleanup().then(() => process.exit(130));
 		};
+		process.on("SIGINT", sigintHandler);
+		if (isMcp && mcpRequest) {
+			logger.info(`MCP request: ${mcpRequest.method}`);
+			const mcp = await mcpInvokeOnce(containerHost, hostPort, mcpRequest, { requestTimeoutMs: options.timeout });
+			await new Promise((r) => setTimeout(r, 250));
+			emitMcpResult(mcp);
+		} else if (isA2a && a2aRequest) {
+			logger.info(`A2A request: ${a2aRequest.method}`);
+			const a2a = await a2aInvokeOnce(containerHost, hostPort, a2aRequest, { requestTimeoutMs: options.timeout });
+			await new Promise((r) => setTimeout(r, 250));
+			emitA2aResult(a2a);
+		} else if (options.ws) {
+			await waitForAgentCorePing(containerHost, hostPort);
+			const frameSource = options.wsInteractive ? readStdinLines() : void 0;
+			logger.info(options.wsInteractive ? "Opening the agent /ws WebSocket (interactive — stdin lines = follow-up frames; Ctrl-D to end)..." : "Opening the agent /ws WebSocket and streaming frames...");
+			const wsResult = await invokeAgentCoreWs(containerHost, hostPort, event, {
+				sessionId,
+				timeoutMs: options.timeout,
+				onMessage: (text) => process.stdout.write(text),
+				...authorization && { authorization },
+				...frameSource && { frameSource }
+			});
+			await new Promise((r) => setTimeout(r, 250));
+			emitWsResult(wsResult);
+		} else {
+			await waitForAgentCorePing(containerHost, hostPort);
+			const additionalHeaders = await buildSigV4HeadersIfRequested(options, resolved, loadedState, containerHost, hostPort, event, sessionId, stateProvider);
+			const result = await invokeAgentCore(containerHost, hostPort, event, {
+				sessionId,
+				timeoutMs: options.timeout,
+				onChunk: (text) => process.stdout.write(text),
+				...authorization && { authorization },
+				...additionalHeaders && { additionalHeaders }
+			});
+			await new Promise((r) => setTimeout(r, 250));
+			emitResult(result);
+		}
 	} finally {
-		sts.destroy();
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		await cleanup();
 	}
 }
 /**
-* Parse / clamp the `--per-lambda-concurrency` flag. Above-cap values
-* are clamped to 4 with a warn line (per the spec doc's risk-mitigation
-* row).
+* Enforce the runtime's inbound JWT authorizer (when declared) and return
+* the `Authorization` header to forward to `/invocations`.
+*
+* - No authorizer → forward the token verbatim if one was given (no-op
+*   otherwise).
+* - `--no-verify-auth` → warn + forward without verifying (local-dev escape).
+* - Authorizer + no token → reject (AgentCore returns 401).
+* - Authorizer + token → verify against the OIDC discovery URL; reject on
+*   failure (AgentCore returns 403); forward on success. An unreachable
+*   discovery URL falls back to pass-through accept (offline-dev fallback in
+*   {@link verifyJwtViaDiscovery}).
+*
+* Exported so a unit test can drive the gate without the full Docker pipeline.
 */
-function parsePerLambdaConcurrency(raw) {
-	const parsed = parseInt(raw, 10);
-	if (!Number.isFinite(parsed) || parsed < 1) throw new Error(`--per-lambda-concurrency must be a positive integer (got '${raw}')`);
-	if (parsed > 4) {
-		getLogger().warn(`--per-lambda-concurrency ${parsed} exceeds the v1 cap of 4; clamping to 4. (Raise this in a follow-up PR if your workload needs more.)`);
-		return 4;
+async function resolveInboundAuthorization(resolved, options) {
+	const logger = getLogger();
+	const authorizer = resolved.jwtAuthorizer;
+	const header = options.bearerToken ? `Bearer ${options.bearerToken}` : void 0;
+	if (!authorizer) return header;
+	if (options.verifyAuth === false) {
+		logger.warn(`Runtime '${resolved.logicalId}' declares a customJwtAuthorizer, but --no-verify-auth was set — skipping inbound JWT verification (local-dev escape hatch).`);
+		return header;
+	}
+	if (!header) throw new CdkLocalError(`Runtime '${resolved.logicalId}' requires an inbound JWT (customJwtAuthorizer). Pass --bearer-token <jwt>, or --no-verify-auth to skip verification for local dev.`, "LOCAL_INVOKE_AGENTCORE_AUTH_REQUIRED");
+	if (!(await verifyJwtViaDiscovery({
+		discoveryUrl: authorizer.discoveryUrl,
+		...authorizer.allowedAudience && { allowedAudience: authorizer.allowedAudience },
+		...authorizer.allowedClients && { allowedClients: authorizer.allowedClients },
+		...authorizer.allowedScopes && { allowedScopes: authorizer.allowedScopes },
+		...authorizer.customClaims && { customClaims: authorizer.customClaims }
+	}, header, createJwksCache(), { warned: /* @__PURE__ */ new Set() })).allow) throw new CdkLocalError(`Inbound JWT rejected by the runtime's customJwtAuthorizer (signature / issuer / expiry / audience check failed against ${authorizer.discoveryUrl}).`, "LOCAL_INVOKE_AGENTCORE_AUTH_DENIED");
+	logger.info(`Inbound JWT verified against ${authorizer.discoveryUrl}.`);
+	return header;
+}
+/**
+* Compute the SigV4 headers for the `/invocations` POST when `--sigv4` is
+* requested. Returns `undefined` (no header overlay) when:
+*
+* - `--sigv4` is not set,
+* - the runtime declares a `customJwtAuthorizer` (the JWT path wins; warns),
+*
+* Throws a {@link CdkLocalError} when `--sigv4` conflicts with
+* `--bearer-token`, or when no AWS credentials are resolvable for signing.
+*
+* Exported so a unit test can drive the gate without the full Docker pipeline.
+*/
+async function buildSigV4HeadersIfRequested(options, resolved, loaded, host, port, event, sessionId, stateProvider) {
+	if (!options.sigv4) return void 0;
+	if (options.bearerToken) throw new CdkLocalError(`--sigv4 and --bearer-token are mutually exclusive: pick one inbound auth.`, "LOCAL_INVOKE_AGENTCORE_AUTH_CONFLICT");
+	if (resolved.jwtAuthorizer) {
+		getLogger().warn(`Runtime '${resolved.logicalId}' declares a customJwtAuthorizer; --sigv4 ignored (JWT path takes precedence).`);
+		return;
 	}
-	return parsed;
+	const region = options.region ?? options.stackRegion ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? resolved.stack.region;
+	if (!region) throw new CdkLocalError("--sigv4: no region resolved for the AgentCore signing scope. Pass --region <region>, set AWS_REGION, or use --from-cfn-stack with a region-bound stack.", "LOCAL_INVOKE_AGENTCORE_SIGV4_NO_REGION");
+	const signed = await signAgentCoreInvocation({
+		credentials: await resolveHostCredentialsForSigV4(options, resolved, loaded, region, stateProvider),
+		region,
+		host,
+		port,
+		path: "/invocations",
+		body: JSON.stringify(event ?? {}),
+		sessionId
+	});
+	const headers = {
+		Authorization: signed.authorization,
+		"X-Amz-Date": signed.amzDate,
+		"X-Amz-Content-Sha256": signed.amzContentSha256
+	};
+	if (signed.amzSecurityToken) headers["X-Amz-Security-Token"] = signed.amzSecurityToken;
+	getLogger().info(`Signed /invocations with SigV4 (region=${region}).`);
+	return headers;
 }
 /**
-* Filter the global Lambda spec map to just the Lambdas reachable from
-* one API server group. The container pool for that server is built
-* from this filtered map so per-API authorizer Lambdas + route
-* handlers stay scoped to their owning server — disposing one server's
-* pool on shutdown does NOT touch another server's still-warm
-* containers.
+* Resolve credentials for host-side SigV4 signing. Precedence:
+*   1. `--assume-role` → STS temp creds (warn + fall through on STS failure);
+*   2. `--profile` → profile creds (sessionToken when the profile carries one);
+*   3. shell env (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / optional
+*      `AWS_SESSION_TOKEN`).
 *
-* Also includes any authorizer Lambdas attached to the group's routes
-* (a Lambda authorizer is a Lambda the pool needs to know about, even
-* though no route directly handles `lambdaLogicalId === auth.lambdaLogicalId`).
+* Throws a {@link CdkLocalError} when none are available — `--sigv4` cannot
+* proceed without credentials, unlike the unsigned path.
 */
-function filterSpecsForGroup(group, allSpecs) {
-	const ids = /* @__PURE__ */ new Set();
-	for (const rwa of group.routes) {
-		ids.add(rwa.route.lambdaLogicalId);
-		const auth = rwa.authorizer;
-		if (auth && (auth.kind === "lambda-token" || auth.kind === "lambda-request")) ids.add(auth.lambdaLogicalId);
+async function resolveHostCredentialsForSigV4(options, resolved, loaded, region, stateProvider) {
+	const logger = getLogger();
+	const assumeRoleArn = await resolveAssumeRoleArn(options, resolved, loaded, stateProvider);
+	if (assumeRoleArn) try {
+		return await assumeAgentCoreExecutionRole(assumeRoleArn, region);
+	} catch (err) {
+		logger.warn(`--assume-role: STS AssumeRole(${assumeRoleArn}) failed for --sigv4 signing: ${err instanceof Error ? err.message : String(err)}. Falling back to ${options.profile ? `--profile ${options.profile}` : "shell credentials"}.`);
 	}
-	const out = /* @__PURE__ */ new Map();
-	for (const id of ids) {
-		const spec = allSpecs.get(id);
-		if (spec) out.set(id, spec);
+	if (options.profile) {
+		const creds = await resolveProfileCredentials(options.profile);
+		if (creds?.accessKeyId && creds.secretAccessKey) return {
+			accessKeyId: creds.accessKeyId,
+			secretAccessKey: creds.secretAccessKey,
+			...creds.sessionToken && { sessionToken: creds.sessionToken }
+		};
 	}
-	return out;
-}
-/**
-* Print one route table per server, with the server's display name as
-* the section header. Replaces the pre-issue #260 single flat table —
-* users now see exactly which routes belong to which API + port.
-*/
-function printPerServerRouteTables(servers) {
-	for (const { group, server } of servers) {
-		process.stdout.write(`\n${group.displayName}  (http://${server.host}:${server.port})\n`);
-		printRouteTable(group.routes);
+	const accessKeyId = process.env["AWS_ACCESS_KEY_ID"];
+	const secretAccessKey = process.env["AWS_SECRET_ACCESS_KEY"];
+	if (accessKeyId && secretAccessKey) {
+		const sessionToken = process.env["AWS_SESSION_TOKEN"];
+		return {
+			accessKeyId,
+			secretAccessKey,
+			...sessionToken && { sessionToken }
+		};
 	}
+	throw new CdkLocalError("--sigv4: no AWS credentials available to sign the request. Set AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, pass --profile <name>, or pass --assume-role <arn>.", "LOCAL_INVOKE_AGENTCORE_SIGV4_NO_CREDENTIALS");
 }
 /**
-* Surface every `unsupported` route (deferred 501) as a startup warn so
-* the user sees what isn't reachable BEFORE they try to curl it. One
-* warn line per route — the route's `unsupported.reason` already names
-* the offender + the underlying limitation, so we just prefix with
-* method + path. Returns the number of unsupported routes so the caller
-* can emit a single-line summary header above the list.
-*/
-function warnUnsupportedRoutes(routes, logger) {
-	const unsupported = routes.filter((r) => r.unsupported);
-	if (unsupported.length === 0) return 0;
-	logger.warn(`${unsupported.length} route(s) will respond HTTP 501 Not Implemented when hit (boot continued):`);
-	for (const r of unsupported) logger.warn(`  - ${r.method} ${r.pathPattern}: ${r.unsupported.reason}`);
-	return unsupported.length;
-}
-/**
-* Surface every WebSocket API tagged as unsupported at discovery as a
-* startup warn. The boot loop above skips attaching the server for
-* these APIs, so no upgrade requests are ever accepted on them —
-* mirrors `warnUnsupportedRoutes`'s shape but for the WebSocket axis.
-* Typical trigger: a Route declaring `AuthorizationType !== 'NONE'` on
-* `$connect` (cdkl v1 does not emulate WebSocket authorizers; closing
-* this gap structurally rather than silently admitting
-* unauthenticated clients matches the security-by-default precedent
-* PR #514 set for HTTP API v2 service integrations).
-*/
-function warnUnsupportedWebSocketApis(apis, logger) {
-	const unsupported = apis.filter((api) => api.unsupported);
-	if (unsupported.length === 0) return 0;
-	logger.warn(`${unsupported.length} WebSocket API(s) will NOT accept upgrade requests (boot continued):`);
-	for (const api of unsupported) logger.warn(`  - ${api.declaredAt}: ${api.unsupported.reason}`);
-	return unsupported.length;
-}
-/**
-* Surface a one-line warn per HTTP / HTTP_PROXY integration whose
-* `Integration.Uri` points at a well-known internal address space
-* (AWS IMDS, loopback, link-local, RFC1918). PR #505 / issue #457
-* follow-up: cdk-local does NOT block these — warn-and-proceed matches the
-* cognito JWKS pass-through pattern — but the user should see the
-* destination at boot so a malicious / typo'd template Uri does not
-* silently exfiltrate credentials in CI. Deduplicated per-Uri.
+* Acquire the agent image. A CODE artifact (managed runtime) is built from
+* source — a fromCodeAsset bundle from its cdk.out asset, a fromS3 bundle
+* downloaded + extracted from S3. A CONTAINER artifact mirrors the
+* container-Lambda path: build from a local cdk.out asset when the URI matches
+* one, else pull from ECR, else pull a plain registry image.
+*
+* `loaded` is the `--from-cfn-stack` state record (when available) — threaded
+* through so a bare `--assume-role` can resolve the execution-role ARN from
+* state for the fromS3 download. `stateProvider` enables the issue-#187
+* live-fallback to `bedrock-agentcore-control:GetAgentRuntime` when the
+* static state lookup misses.
 */
-function warnSsrfRiskyIntegrations(routes, logger) {
-	const seen = /* @__PURE__ */ new Set();
-	for (const r of routes) {
-		const integ = r.restV1Integration;
-		if (!integ) continue;
-		if (integ.kind !== "http" && integ.kind !== "http-proxy") continue;
-		if (seen.has(integ.uri)) continue;
-		seen.add(integ.uri);
-		warnSsrfRiskyUri(integ.uri, `${r.method} ${r.pathPattern}`, (msg) => logger.warn(msg));
+async function resolveAgentCoreImage(resolved, options, loaded, stateProvider) {
+	const logger = getLogger();
+	const architecture = platformToArchitecture(options.platform);
+	if (resolved.codeArtifact) return resolveAgentCoreCodeImage(resolved, resolved.codeArtifact, options, architecture, loaded, stateProvider);
+	const containerUri = resolved.containerUri;
+	if (containerUri === void 0) throw new CdkLocalError(`AgentCore Runtime '${resolved.logicalId}' has neither a container image nor a code artifact to run.`, "LOCAL_INVOKE_AGENTCORE_NO_ARTIFACT");
+	const manifestPath = resolved.stack.assetManifestPath;
+	if (manifestPath) {
+		const cdkOutDir = dirname(manifestPath);
+		const manifest = await new AssetManifestLoader().loadManifest(cdkOutDir, resolved.stack.stackName);
+		if (manifest) {
+			const entry = getDockerImageBySourceHash(manifest, containerUri);
+			if (entry) return buildContainerImage(entry.asset, cdkOutDir, {
+				architecture,
+				noBuild: options.build === false
+			});
+		}
+	}
+	if (parseEcrUri(containerUri)) {
+		logger.info(`Pulling agent image from ECR: ${containerUri}`);
+		return pullEcrImage(containerUri, {
+			skipPull: options.pull === false,
+			...options.region !== void 0 && { region: options.region },
+			...options.ecrRoleArn !== void 0 && { ecrRoleArn: options.ecrRoleArn },
+			...options.profile !== void 0 && { profile: options.profile }
+		});
 	}
+	await pullImage(containerUri, options.pull === false);
+	return containerUri;
+}
+/**
+* Build a local image from a `CodeConfiguration` (managed-runtime) bundle.
+*
+* - fromS3 (`code.s3Source` set, a literal S3 object): download + extract the
+*   bundle, then run the from-source build over the extracted dir.
+* - fromCodeAsset: locate the source dir in cdk.out via its asset hash, then
+*   run the same from-source build (generated Dockerfile → install deps → run
+*   EntryPoint).
+*/
+async function resolveAgentCoreCodeImage(resolved, code, options, architecture, loaded, stateProvider) {
+	if (code.s3Source) return resolveAgentCoreCodeImageFromS3(resolved, code, code.s3Source, options, architecture, loaded, stateProvider);
+	const manifestPath = resolved.stack.assetManifestPath;
+	if (!manifestPath) throw new CdkLocalError(`AgentCore Runtime '${resolved.logicalId}' uses a code artifact, but its stack has no asset manifest in cdk.out to read the bundle source from.`, "LOCAL_INVOKE_AGENTCORE_CODE_NO_MANIFEST");
+	const cdkOutDir = dirname(manifestPath);
+	const loader = new AssetManifestLoader();
+	const manifest = await loader.loadManifest(cdkOutDir, resolved.stack.stackName);
+	const fileAssets = manifest ? loader.getFileAssets(manifest) : void 0;
+	const asset = fileAssets ? fileAssets.get(code.codeAssetHash) ?? findFileAssetByObjectKey(fileAssets, code.codeAssetHash) : void 0;
+	if (!asset) throw new CdkLocalError(`AgentCore Runtime '${resolved.logicalId}' code bundle (asset ${code.codeAssetHash}) was not found in the cdk.out asset manifest. ${getEmbedConfig().cliName} invoke-agentcore runs a local from-source build of a fromCodeAsset bundle — re-synthesize the app so the asset is staged in cdk.out and retry. (A fromS3 bundle is downloaded from S3 instead; this runtime has no literal Code.S3.Bucket.)`, "LOCAL_INVOKE_AGENTCORE_CODE_ASSET_NOT_FOUND");
+	const sourceDir = loader.getAssetSourcePath(cdkOutDir, asset);
+	if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) throw new CdkLocalError(`AgentCore Runtime '${resolved.logicalId}' code bundle source '${sourceDir}' does not exist or is not a directory. Re-synthesize the app and retry.`, "LOCAL_INVOKE_AGENTCORE_CODE_SOURCE_MISSING");
+	return buildAgentCoreCodeImage({
+		sourceDir,
+		runtime: code.runtime,
+		entryPoint: code.entryPoint,
+		architecture,
+		noBuild: options.build === false
+	});
 }
 /**
-* One reload cycle for the multi-server topology (issue #260). The
-* watcher serializes calls via a chain promise; this function:
+* Build a local image from a fromS3 CodeConfiguration bundle: download +
+* extract the S3 object, run the from-source build over the extracted dir, then
+* clean up the temp dir.
 *
-*   1. Re-runs `synthesizeAndBuild()` once (failure → warn + keep
-*      previous version serving on every server).
-*   2. Re-groups the new routes by API server key.
-*   3. For each existing server, swaps state to the new group's
-*      routes + a freshly-built pool filtered to that group's
-*      Lambdas. Disposes the previous pool in the background.
-*   4. Warns about new groups (= an API was added in CDK code) and
-*      vanished groups (= an API was removed) — those require a
-*      server restart in v1.
+* Credentials mirror the rest of the command: an `--assume-role` ARN (explicit,
+* or resolved from `--from-cfn-stack` state for the bare form) yields STS temp
+* creds for the download; otherwise `--profile` / the default chain is used.
+* The region is `--region` / `--stack-region` / env / the stack's region.
 */
-async function reloadAllServers(args) {
-	const { synthesizeAndBuild, servers, buildPool, logger } = args;
-	let material;
-	try {
-		material = await synthesizeAndBuild();
+async function resolveAgentCoreCodeImageFromS3(resolved, code, s3Source, options, architecture, loaded, stateProvider) {
+	const logger = getLogger();
+	if (typeof s3Source.bucket !== "string" || s3Source.bucket.length === 0) throw new CdkLocalError(`AgentCore Runtime '${resolved.logicalId}' fromS3 bundle reached the image step with no literal bucket. This is a cdk-local bug — please report it.`, "LOCAL_INVOKE_AGENTCORE_FROMS3_BUCKET_UNRESOLVED");
+	const location = {
+		bucket: s3Source.bucket,
+		key: s3Source.key,
+		...s3Source.versionId !== void 0 && { versionId: s3Source.versionId }
+	};
+	const region = options.region ?? options.stackRegion ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? resolved.stack.region;
+	const assumeRoleArn = await resolveAssumeRoleArn(options, resolved, loaded, stateProvider);
+	let credentials;
+	if (assumeRoleArn) try {
+		credentials = await assumeAgentCoreExecutionRole(assumeRoleArn, region);
 	} catch (err) {
-		logger.warn(`cdk synth failed during reload; keeping previous version. (${err instanceof Error ? err.message : String(err)})`);
-		return;
+		logger.warn(`--assume-role: STS AssumeRole(${assumeRoleArn}) failed for the fromS3 bundle download: ${err instanceof Error ? err.message : String(err)}. Falling back to ${options.profile ? `--profile ${options.profile}` : "the default credentials"}.`);
 	}
-	const newGroups = groupRoutesByServer(material.routes);
-	const newByKey = new Map(newGroups.map((g) => [g.serverKey, g]));
-	const oldKeys = new Set(servers.map((s) => s.group.serverKey));
-	const newKeys = new Set(newByKey.keys());
-	const added = [...newKeys].filter((k) => !oldKeys.has(k));
-	const removed = [...oldKeys].filter((k) => !newKeys.has(k));
-	if (added.length > 0) logger.warn(`Reload detected new API surface(s): ${added.join(", ")}. Restart '${getEmbedConfig().cliName} start-api' to serve them.`);
-	if (removed.length > 0) logger.warn(`Reload detected removed API surface(s): ${removed.join(", ")}. Their servers will keep serving stale routes until restart.`);
-	for (const booted of servers) {
-		const group = newByKey.get(booted.group.serverKey);
-		if (!group) continue;
-		const newPool = buildPool(filterSpecsForGroup(group, material.specs));
-		const newState = {
-			routes: group.routes,
-			pool: newPool,
-			corsConfigByApiId: material.corsConfigByApiId
-		};
-		const previousState = booted.server.setServerState(newState);
-		booted.group = group;
-		previousState.pool.dispose().catch((err) => {
-			logger.debug(`Previous pool dispose() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`);
+	const bundle = await downloadAndExtractS3Bundle(location, {
+		...region !== void 0 && { region },
+		...options.profile !== void 0 && { profile: options.profile },
+		...credentials !== void 0 && { credentials }
+	});
+	try {
+		return await buildAgentCoreCodeImage({
+			sourceDir: bundle.dir,
+			runtime: code.runtime,
+			entryPoint: code.entryPoint,
+			architecture,
+			noBuild: options.build === false
 		});
+	} finally {
+		await bundle.cleanup();
 	}
-	printPerServerRouteTables(servers);
-	const allRoutes = servers.flatMap((s) => s.group.routes.map((r) => r.route));
-	warnUnsupportedRoutes(allRoutes, logger);
-	warnSsrfRiskyIntegrations(allRoutes, logger);
 }
 /**
-* Returns true when any value in the function's template env map is a
-* CFn intrinsic (non-primitive). Used to gate the pseudo-parameter STS
-* hop inside the `--from-state` flow: literal-only env maps don't need
-* the pseudo-parameter bag and shouldn't pay for an STS call. Mirrors
-* the same gating in `local-invoke.ts` (`envHasIntrinsicValue`) and
-* `ecs-task-resolver.ts` (`containerHasIntrinsicEnvOrSecret`).
+* Find the file asset whose destination objectKey is `<hash>.zip` (matching the
+* `Code.S3.Prefix`'s hash) when the source-hash-keyed lookup misses — covers a
+* synthesizer whose source hash differs from the destination objectKey.
 */
-function envHasIntrinsicValue(templateEnv) {
-	if (!templateEnv) return false;
-	for (const v of Object.values(templateEnv)) {
-		if (v === void 0 || v === null) continue;
-		if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") continue;
-		return true;
-	}
-	return false;
+function findFileAssetByObjectKey(fileAssets, hash) {
+	const zip = `${hash}.zip`;
+	for (const asset of fileAssets.values()) if (Object.values(asset.destinations).some((d) => d.objectKey === zip || d.objectKey.endsWith(`/${zip}`))) return asset;
 }
 /**
-* Load deployed state for every stack that owns a routed Lambda. Once
-* per `synthesizeAndBuild` pass (initial boot + every reload), so a
-* Lambda's per-spec build does not pay one round-trip per Lambda. Per-
-* stack failures (no state, ambiguous region, bucket resolution error)
-* degrade to warn-and-fall-back via the active `LocalStateProvider` —
-* the affected stack's reachable Lambdas behave as if `--from-state` /
-* `--from-cfn-stack` were not set, while sibling stacks with loadable
-* state still substitute.
+* Build the container env + the set of env keys to keep off the `docker run`
+* argv. Substitutes `--from-cfn-stack` state into the template env (reusing the
+* shared state load + image-resolution context — Ref / Fn::Sub / Fn::Join +
+* SSM parameters, with decrypted SecureString values flagged sensitive),
+* applies `--env-vars` overrides, then injects AWS credentials (`--assume-role`
+* STS temp creds — resolving an intrinsic RoleArn from state for bare
+* `--assume-role` — else `--profile` / dev creds).
 *
-* Pseudo parameters are resolved per stack and only when at least one
-* reachable Lambda in that stack has an intrinsic-valued env entry
-* (gated via {@link envHasIntrinsicValue}). STS failures degrade to
-* warn and leave `pseudoParameters: undefined` — substitution still
-* runs for non-`AWS::*` refs.
+* The state provider + loaded record + image context are built once by the
+* caller and shared here, so this does not re-load state.
 */
+async function buildContainerEnv(resolved, options, profileCredentials, profileCredsFile, stateProvider, loaded, imageContext) {
+	const logger = getLogger();
+	let templateEnv = resolved.environmentVariables;
+	const sensitiveEnvKeys = /* @__PURE__ */ new Set();
+	if (stateProvider && loaded) {
+		const subContext = {
+			resources: imageContext?.stateResources ?? loaded.resources,
+			consumerRegion: loaded.region
+		};
+		const pseudo = imageContext?.pseudoParameters ?? derivePseudoParametersFromRegion(loaded.region);
+		if (pseudo) subContext.pseudoParameters = pseudo;
+		if (imageContext?.stateParameters) subContext.parameters = imageContext.stateParameters;
+		if (imageContext?.stateSensitiveParameters?.length) subContext.sensitiveParameters = new Set(imageContext.stateSensitiveParameters);
+		const resolver = await stateProvider.buildCrossStackResolver(loaded.region);
+		if (resolver) subContext.crossStackResolver = resolver;
+		const { env, audit } = await substituteEnvVarsFromStateAsync(templateEnv, subContext);
+		templateEnv = env;
+		for (const key of audit.resolvedKeys) logger.debug(`${stateProvider.label}: substituted env var ${key}`);
+		for (const key of audit.sensitiveKeys) sensitiveEnvKeys.add(key);
+		for (const { key, reason } of audit.unresolved) logger.warn(`${stateProvider.label}: could not substitute env var ${key} (${reason}). Override it via --env-vars or it will be dropped.`);
+	}
+	const overrides = readEnvOverridesFile$2(options.envVars);
+	const cdkPath = readCdkPathOrUndefined(resolved.resource);
+	const envResult = resolveEnvVars(resolved.logicalId, cdkPath, templateEnv, overrides);
+	for (const key of envResult.unresolved) {
+		const overrideKeyExample = cdkPath?.replace(/\/Resource$/, "") ?? resolved.logicalId;
+		logger.warn(`Environment variable ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${overrideKeyExample}":{"${key}":"<literal>"}}), or pass a state-source flag (e.g. --from-cfn-stack) to recover deployed values.`);
+	}
+	const dockerEnv = { ...envResult.resolved };
+	const assumeRoleArn = await resolveAssumeRoleArn(options, resolved, loaded, stateProvider);
+	await applyAgentCoreCredentialEnv(dockerEnv, {
+		...assumeRoleArn !== void 0 && { assumeRoleArn },
+		...options.region !== void 0 && { region: options.region },
+		...profileCredentials !== void 0 && { profileCredentials },
+		...profileCredsFile !== void 0 && { profileCredsFile: {
+			containerPath: profileCredsFile.containerPath,
+			profileName: profileCredsFile.profileName
+		} }
+	});
+	return {
+		env: dockerEnv,
+		sensitiveEnvKeys
+	};
+}
+/**
+* Resolve a fromS3 bundle's intrinsic `Code.S3.Bucket` to a literal bucket
+* name in place on `resolved.codeArtifact.s3Source.bucket`. Uses the SAME
+* state-substitution machinery env vars use under `--from-cfn-stack`, so
+* every cross-stack intrinsic that path supports (`Ref` / `Fn::ImportValue` /
+* `Fn::GetStackOutput`) is supported transparently here.
+*
+* No-op when there is no intrinsic to resolve. Errors when no state is
+* available, or when the substitution returns a non-string / unresolved value.
+*
+* Exported so a unit test can drive the gate without the full Docker pipeline.
+*/
+async function resolveFromS3BucketIntrinsic(resolved, stateProvider, loaded, imageContext) {
+	const s3Source = resolved.codeArtifact?.s3Source;
+	if (!s3Source || s3Source.bucketIntrinsic === void 0) return;
+	if (s3Source.bucket !== void 0) return;
+	if (!stateProvider || !loaded) throw new CdkLocalError(`AgentCore Runtime '${resolved.logicalId}' fromS3 bundle's Code.S3.Bucket is an unresolved intrinsic (${describeIntrinsic(s3Source.bucketIntrinsic)}). Pass --from-cfn-stack so its physical bucket name can be resolved against the deployed stack state.`, "LOCAL_INVOKE_AGENTCORE_FROMS3_BUCKET_INTRINSIC_NO_STATE");
+	const subContext = {
+		resources: imageContext?.stateResources ?? loaded.resources,
+		consumerRegion: loaded.region
+	};
+	const pseudo = imageContext?.pseudoParameters ?? derivePseudoParametersFromRegion(loaded.region);
+	if (pseudo) subContext.pseudoParameters = pseudo;
+	const crossStackResolver = await stateProvider.buildCrossStackResolver(loaded.region);
+	if (crossStackResolver) subContext.crossStackResolver = crossStackResolver;
+	const result = await substituteAgainstStateAsync(s3Source.bucketIntrinsic, subContext);
+	if (result.kind !== "literal") throw new CdkLocalError(`Could not resolve AgentCore Runtime '${resolved.logicalId}' fromS3 Code.S3.Bucket intrinsic (${describeIntrinsic(s3Source.bucketIntrinsic)}) against the --from-cfn-stack state: ${result.reason}. Confirm the referenced resource / export exists in the deployed stack.`, "LOCAL_INVOKE_AGENTCORE_FROMS3_BUCKET_INTRINSIC_UNRESOLVED");
+	if (typeof result.value !== "string" || result.value.length === 0) throw new CdkLocalError(`AgentCore Runtime '${resolved.logicalId}' fromS3 Code.S3.Bucket intrinsic resolved to a ${typeof result.value} value, not a bucket name string. (${describeIntrinsic(s3Source.bucketIntrinsic)})`, "LOCAL_INVOKE_AGENTCORE_FROMS3_BUCKET_INTRINSIC_NOT_STRING");
+	s3Source.bucket = result.value;
+	getLogger().info(`Resolved fromS3 Code.S3.Bucket from state: ${describeIntrinsic(s3Source.bucketIntrinsic)} -> ${result.value}`);
+}
+/** Render the intrinsic key for an error / log message (e.g. `Ref:Bucket1`). */
+function describeIntrinsic(value) {
+	if (!value || typeof value !== "object") return String(value);
+	const obj = value;
+	const key = Object.keys(obj)[0] ?? "?";
+	const arg = obj[key];
+	if (typeof arg === "string") return `${key}:${arg}`;
+	return key;
+}
 /**
-* Returns true when at least one host-provided extra state-provider flag
-* is active in the options bag.
+* Build the `--from-cfn-stack` image-resolution context + return the loaded
+* state record (loaded once, reused by env substitution + role resolution).
+* Mirrors `run-task`'s `buildEcsImageResolutionContext`: pseudo parameters
+* (region + STS account id), the deployed resources, and SSM template
+* parameters (decrypted SecureString logical ids flagged sensitive).
 */
-function hasExtraStateProviderActive(options, extraStateProviders) {
-	if (!extraStateProviders) return false;
-	for (const key of Object.keys(extraStateProviders)) if (options[key]) return true;
-	return false;
-}
-async function loadStateForRoutedStacks(stacks, routes, routesWithAuth, options, extraStateProviders) {
+async function buildAgentCoreImageContext(candidate, stateProvider, options) {
 	const logger = getLogger();
-	const out = /* @__PURE__ */ new Map();
-	const lambdaIds = uniqueLambdaIds(routes, routesWithAuth);
-	const reachableStackNames = /* @__PURE__ */ new Set();
-	for (const logicalId of lambdaIds) for (const stack of stacks) {
-		const resource = stack.template.Resources?.[logicalId];
-		if (resource && resource.Type === "AWS::Lambda::Function") {
-			reachableStackNames.add(stack.stackName);
-			break;
-		}
+	const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
+	let accountId;
+	try {
+		accountId = await resolveCallerAccountId$2(region, options.profile);
+	} catch (err) {
+		logger.warn(`--from-cfn-stack: STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. A same-stack ECR image URI referencing \${AWS::AccountId} may not resolve.`);
 	}
-	const stackHasIntrinsicEnv = (stackName) => {
-		for (const logicalId of lambdaIds) for (const stack of stacks) {
-			if (stack.stackName !== stackName) continue;
-			const resource = stack.template.Resources?.[logicalId];
-			if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
-			if (envHasIntrinsicValue(getTemplateEnv(resource))) return true;
+	const context = {};
+	const pseudo = derivePseudoParametersFromRegion(region, accountId);
+	if (pseudo) context.pseudoParameters = pseudo;
+	const loaded = await stateProvider.load(candidate.stackName, candidate.region);
+	if (loaded) {
+		context.stateResources = loaded.resources;
+		if (stateProvider.resolveTemplateSsmParameters) {
+			const ssm = await stateProvider.resolveTemplateSsmParameters(candidate.template);
+			if (Object.keys(ssm.values).length > 0) context.stateParameters = ssm.values;
+			if (ssm.secureStringLogicalIds.length > 0) context.stateSensitiveParameters = ssm.secureStringLogicalIds;
 		}
-		return false;
+	}
+	return {
+		context,
+		loaded: loaded ?? void 0
 	};
-	rejectExplicitCfnStackWithMultipleStacks(options, reachableStackNames.size);
-	for (const stackName of reachableStackNames) {
-		const stack = stacks.find((s) => s.stackName === stackName);
-		if (!stack) continue;
-		const provider = createLocalStateProvider(options, stack.stackName, await resolveCfnFallbackRegion(options, stack.region), extraStateProviders);
-		if (!provider) continue;
+}
+/** STS `GetCallerIdentity` for the `${AWS::AccountId}` pseudo parameter (threads `--profile`). */
+async function resolveCallerAccountId$2(region, profile) {
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({
+		...region && { region },
+		...profile && { profile }
+	});
+	try {
+		return (await sts.send(new GetCallerIdentityCommand({}))).Account;
+	} finally {
+		sts.destroy();
+	}
+}
+/**
+* Inject AWS credentials into the container env. Precedence:
+*   1. `--assume-role` → STS-issued temp creds for the resolved ARN (on
+*      STS failure, warn + fall through to dev creds).
+*   2. dev shell creds (`forwardAwsEnv`) + `--profile` overlay
+*      ({@link applyProfileCredentialsOverlay}) + the bind-mounted
+*      credentials-file env so handler `fromIni({ profile })` resolves.
+*
+* Exported so a unit test can lock the binding (mock STS) without driving
+* the full synth + docker pipeline.
+*/
+async function applyAgentCoreCredentialEnv(dockerEnv, args) {
+	const logger = getLogger();
+	let assumeSucceeded = false;
+	if (args.assumeRoleArn) {
+		const stsRegion = args.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"];
 		try {
-			const loaded = await provider.load(stack.stackName, stack.region);
-			if (!loaded) continue;
-			const bundle = { state: {
-				version: 1,
-				stackName: stack.stackName,
-				resources: loaded.resources,
-				outputs: loaded.outputs,
-				lastModified: 0
-			} };
-			if (stackHasIntrinsicEnv(stackName)) {
-				const pseudo = await resolvePseudoParametersForStartApi(loaded.region, options);
-				if (pseudo) bundle.pseudoParameters = pseudo;
-			}
-			if (provider.resolveDeployedFunctionEnv) {
-				const deployedEnvByLambda = /* @__PURE__ */ new Map();
-				for (const logicalId of lambdaIds) {
-					const resource = stack.template.Resources?.[logicalId];
-					if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
-					if (!envHasIntrinsicValue(getTemplateEnv(resource))) continue;
-					const physicalId = loaded.resources[logicalId]?.physicalId;
-					if (!physicalId) continue;
-					const deployedEnv = await provider.resolveDeployedFunctionEnv(physicalId);
-					if (deployedEnv) deployedEnvByLambda.set(logicalId, deployedEnv);
-				}
-				if (deployedEnvByLambda.size > 0) bundle.deployedEnvByLambda = deployedEnvByLambda;
-			}
-			if (stackHasIntrinsicEnv(stackName) && provider.resolveTemplateSsmParameters) {
-				const ssmParameters = await provider.resolveTemplateSsmParameters(stack.template);
-				if (Object.keys(ssmParameters.values).length > 0) bundle.ssmParameters = ssmParameters.values;
-				if (ssmParameters.secureStringLogicalIds.length > 0) bundle.ssmSecureStringLogicalIds = ssmParameters.secureStringLogicalIds;
+			const creds = await assumeAgentCoreExecutionRole(args.assumeRoleArn, stsRegion);
+			dockerEnv["AWS_ACCESS_KEY_ID"] = creds.accessKeyId;
+			dockerEnv["AWS_SECRET_ACCESS_KEY"] = creds.secretAccessKey;
+			dockerEnv["AWS_SESSION_TOKEN"] = creds.sessionToken;
+			if (stsRegion) dockerEnv["AWS_REGION"] = stsRegion;
+			assumeSucceeded = true;
+		} catch (err) {
+			logger.warn(`--assume-role: STS AssumeRole(${args.assumeRoleArn}) failed: ${err instanceof Error ? err.message : String(err)}. Falling back to the developer's shell credentials.`);
+		}
+	}
+	if (!assumeSucceeded) {
+		forwardAwsEnv$1(dockerEnv);
+		applyProfileCredentialsOverlay(dockerEnv, args.profileCredentials, false);
+		if (args.profileCredsFile) {
+			dockerEnv["AWS_SHARED_CREDENTIALS_FILE"] = args.profileCredsFile.containerPath;
+			dockerEnv["AWS_PROFILE"] = args.profileCredsFile.profileName;
+		}
+	}
+}
+/**
+* Resolve the role ARN to assume, honoring the three `--assume-role` forms.
+* Bare `--assume-role` uses the runtime's literal `RoleArn`; when that is an
+* intrinsic (the common L2 case — `Fn::GetAtt` to an auto-created role) it
+* resolves the execution-role ARN from `--from-cfn-stack` state first; when
+* that misses (issue #187 — `ListStackResources` returns the role's name,
+* not its ARN, so `attributes.Arn` is empty on the CFn state map) it falls
+* back to `stateProvider.resolveAgentCoreRuntimeRoleArn(<physicalId>)`
+* (a `bedrock-agentcore-control:GetAgentRuntime` call) so a same-stack
+* execution role still resolves. Only warns + falls back to dev creds
+* when all of those miss.
+*/
+async function resolveAssumeRoleArn(options, resolved, loaded, stateProvider) {
+	if (typeof options.assumeRole === "string") return options.assumeRole;
+	if (options.assumeRole !== true) return void 0;
+	if (resolved.roleArn) return resolved.roleArn;
+	if (loaded) {
+		const fromState = resolveExecutionRoleArnFromState(loaded, resolved.logicalId, "RoleArn");
+		if (fromState) {
+			getLogger().debug(`--assume-role: resolved RoleArn from state: ${fromState}`);
+			return fromState;
+		}
+		const runtimePhysicalId = loaded.resources[resolved.logicalId]?.physicalId;
+		if (stateProvider?.resolveAgentCoreRuntimeRoleArn && runtimePhysicalId) {
+			const liveArn = await stateProvider.resolveAgentCoreRuntimeRoleArn(runtimePhysicalId);
+			if (liveArn) {
+				getLogger().info(`--assume-role: auto-resolved execution role from GetAgentRuntime: ${liveArn}`);
+				return liveArn;
 			}
-			out.set(stackName, bundle);
-			logger.debug(`${provider.label}: loaded state for ${stackName} (${loaded.region})`);
-		} finally {
-			provider.dispose();
 		}
 	}
-	return out;
+	getLogger().warn("--assume-role passed without an ARN, but the runtime's RoleArn is not a literal ARN in the template " + (loaded ? "and could not be resolved from the deployed stack state. " : "and no --from-cfn-stack state is available to resolve it. ") + "Pass the ARN explicitly: --assume-role <arn>. Falling back to the developer's shell credentials.");
+}
+function emitResult(result) {
+	const logger = getLogger();
+	if (result.status >= 400) {
+		logger.warn(`Agent /invocations returned HTTP ${result.status}.`);
+		process.exitCode = 1;
+	}
+	if (result.streamed) {
+		process.stdout.write("\n");
+		return;
+	}
+	process.stdout.write(`${result.raw}\n`);
 }
 /**
-* Build the AWS pseudo-parameter bag for `--from-state` env-var
-* substitution. Mirrors `resolvePseudoParametersForInvoke` in
-* `local-invoke.ts` byte-for-byte — kept inlined here rather than
-* extracted into a shared helper because the two call sites differ in
-* region precedence (this one is per-stack so the resolved state
-* region takes priority).
+* Finish a `/ws` exchange: the frames were already streamed to stdout via the
+* onMessage sink, so just terminate with a newline (so the shell prompt resumes
+* cleanly) and note the frame count at debug level.
+*/
+function emitWsResult(result) {
+	process.stdout.write("\n");
+	getLogger().debug(`Agent /ws closed after ${result.frames} frame(s).`);
+}
+/**
+* Build the JSON-RPC request to send to an MCP runtime from `--event`:
+*   - no `--event` (empty object) → `tools/list` (discover the server's tools),
+*   - an object with a string `method` → that method + its `params`,
+*   - anything else → a fail-fast error.
 *
-* Region precedence: `--region` > `AWS_REGION` > `AWS_DEFAULT_REGION` >
-* the state record's region (returned by the active `LocalStateProvider`).
+* Exported for unit testing.
 */
-async function resolvePseudoParametersForStartApi(stateRegion, options) {
-	const logger = getLogger();
-	const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? stateRegion;
-	let accountId;
+function buildMcpRequest(event) {
+	if (event === void 0 || event === null) return {
+		method: "tools/list",
+		params: {}
+	};
+	if (typeof event !== "object" || Array.isArray(event)) throw new CdkLocalError("MCP --event must be a JSON object describing a JSON-RPC request (e.g. {\"method\":\"tools/call\",\"params\":{\"name\":\"...\",\"arguments\":{...}}}).", "LOCAL_INVOKE_AGENTCORE_MCP_EVENT_INVALID");
+	const obj = event;
+	if (Object.keys(obj).length === 0) return {
+		method: "tools/list",
+		params: {}
+	};
+	if (typeof obj["method"] !== "string") throw new CdkLocalError(`MCP --event must include a string "method" (a JSON-RPC method such as "tools/list" or "tools/call"). Got keys: ${Object.keys(obj).join(", ")}.`, "LOCAL_INVOKE_AGENTCORE_MCP_EVENT_INVALID");
+	return {
+		method: obj["method"],
+		...obj["params"] !== void 0 && { params: obj["params"] }
+	};
+}
+/** Print the MCP JSON-RPC response; exit 1 when it carried a JSON-RPC error. */
+function emitMcpResult(result) {
+	if (!result.ok) {
+		getLogger().warn("MCP server returned a JSON-RPC error.");
+		process.exitCode = 1;
+	}
+	process.stdout.write(`${result.raw}\n`);
+}
+/**
+* Build the JSON-RPC request to send to an A2A runtime from `--event`:
+*   - no `--event` (empty object) → `agent/getCard` (discover the agent's card),
+*   - an object with a string `method` → that method + its `params`,
+*   - anything else → a fail-fast error.
+*
+* Exported for unit testing.
+*/
+function buildA2aRequest(event) {
+	if (event === void 0 || event === null) return {
+		method: "agent/getCard",
+		params: {}
+	};
+	if (typeof event !== "object" || Array.isArray(event)) throw new CdkLocalError("A2A --event must be a JSON object describing a JSON-RPC request (e.g. {\"method\":\"tasks/send\",\"params\":{\"id\":\"...\",\"message\":{...}}}).", "LOCAL_INVOKE_AGENTCORE_A2A_EVENT_INVALID");
+	const obj = event;
+	if (Object.keys(obj).length === 0) return {
+		method: "agent/getCard",
+		params: {}
+	};
+	if (typeof obj["method"] !== "string") throw new CdkLocalError(`A2A --event must include a string "method" (a JSON-RPC method such as "agent/getCard" or "tasks/send"). Got keys: ${Object.keys(obj).join(", ")}.`, "LOCAL_INVOKE_AGENTCORE_A2A_EVENT_INVALID");
+	return {
+		method: obj["method"],
+		...obj["params"] !== void 0 && { params: obj["params"] }
+	};
+}
+/** Print the A2A JSON-RPC response; exit 1 when it carried a JSON-RPC error. */
+function emitA2aResult(result) {
+	if (!result.ok) {
+		getLogger().warn("A2A server returned a JSON-RPC error.");
+		process.exitCode = 1;
+	}
+	process.stdout.write(`${result.raw}\n`);
+}
+/** Map a `--platform` value to the architecture `buildContainerImage` expects. */
+function platformToArchitecture(platform) {
+	return platform === "linux/amd64" ? "x86_64" : "arm64";
+}
+function forwardAwsEnv$1(env) {
+	for (const key of [
+		"AWS_ACCESS_KEY_ID",
+		"AWS_SECRET_ACCESS_KEY",
+		"AWS_SESSION_TOKEN",
+		"AWS_REGION",
+		"AWS_DEFAULT_REGION"
+	]) {
+		const value = process.env[key];
+		if (value !== void 0) env[key] = value;
+	}
+}
+async function assumeAgentCoreExecutionRole(roleArn, region) {
+	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
 	try {
-		const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
-		const sts = new STSClient({ ...region && { region } });
+		const creds = (await sts.send(new AssumeRoleCommand({
+			RoleArn: roleArn,
+			RoleSessionName: `${getEmbedConfig().resourceNamePrefix}-invoke-agentcore-${Date.now()}`,
+			DurationSeconds: 3600
+		}))).Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new Error(`AssumeRole(${roleArn}) returned no usable credentials.`);
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			sessionToken: creds.SessionToken
+		};
+	} finally {
+		sts.destroy();
+	}
+}
+async function readEvent(options) {
+	if (options.event && options.eventStdin) throw new Error("--event and --event-stdin are mutually exclusive.");
+	if (options.eventStdin) return parseEvent(await readStdin(), "<stdin>");
+	if (options.event) {
+		let raw;
 		try {
-			accountId = (await sts.send(new GetCallerIdentityCommand({}))).Account;
-		} finally {
-			sts.destroy();
+			raw = readFileSync(options.event, "utf-8");
+		} catch (err) {
+			throw new Error(`Failed to read --event file '${options.event}': ${err instanceof Error ? err.message : String(err)}`);
 		}
+		return parseEvent(raw, options.event);
+	}
+	return {};
+}
+function parseEvent(raw, source) {
+	try {
+		return JSON.parse(raw);
 	} catch (err) {
-		logger.warn(`--from-state: resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped for AWS::AccountId; affected env entries will be dropped with per-key warnings.`);
+		throw new Error(`Failed to parse event payload from ${source} as JSON: ${err instanceof Error ? err.message : String(err)}`);
 	}
-	const partitionAndSuffix = region ? derivePartitionAndUrlSuffix(region) : void 0;
-	const bag = {
-		...accountId !== void 0 && { accountId },
-		...region !== void 0 && { region },
-		...partitionAndSuffix && {
-			partition: partitionAndSuffix.partition,
-			urlSuffix: partitionAndSuffix.urlSuffix
-		}
-	};
-	return Object.keys(bag).length === 0 ? void 0 : bag;
 }
-/** Validate `--debug-port-base`. */
-function parseDebugPort(raw) {
-	const parsed = parseInt(raw, 10);
-	if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) throw new Error(`--debug-port-base must be 1..65535 (got '${raw}')`);
-	return parsed;
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	return Buffer.concat(chunks).toString("utf-8");
 }
 /**
-* Resolve the mTLS configuration from CLI options. Returns `undefined`
-* when none of the three `--mtls-*` flags is set (the server stays
-* plain-HTTP). When any of the three is set, ALL THREE must be set —
-* partial configurations are rejected at parse time so the server
-* never boots in a half-configured state.
+* Read `process.stdin` line-buffered and yield each line as a string (trailing
+* `\r?\n` stripped). The async iterable completes when stdin EOFs (Ctrl-D /
+* end-of-pipe), and surrenders the underlying stream when its `return()` is
+* called — so the WS client can close down the source when the server closes
+* first without leaving stdin held open.
 *
-* Exported for unit testing.
+* Exported so a unit test can drive the iterable shape directly.
 */
-function resolveMtlsConfig(options) {
-	const present = [];
-	const absent = [];
-	if (options.mtlsTruststore !== void 0 && options.mtlsTruststore !== "") present.push("--mtls-truststore");
-	else absent.push("--mtls-truststore");
-	if (options.mtlsCert !== void 0 && options.mtlsCert !== "") present.push("--mtls-cert");
-	else absent.push("--mtls-cert");
-	if (options.mtlsKey !== void 0 && options.mtlsKey !== "") present.push("--mtls-key");
-	else absent.push("--mtls-key");
-	if (present.length === 0) return void 0;
-	if (absent.length > 0) throw new Error(`mTLS configuration is incomplete: ${present.join(", ")} set but ${absent.join(", ")} missing. All three of --mtls-truststore, --mtls-cert, and --mtls-key must be set together to enable mTLS, or all three left unset for plain HTTP.`);
-	return readMtlsMaterialsFromDisk({
-		truststorePath: options.mtlsTruststore,
-		certPath: options.mtlsCert,
-		keyPath: options.mtlsKey
+async function* readStdinLines() {
+	const { createInterface } = await import("node:readline");
+	const rl = createInterface({
+		input: process.stdin,
+		crlfDelay: Infinity
 	});
+	try {
+		for await (const line of rl) yield line;
+	} finally {
+		rl.close();
+	}
 }
-/**
-* Builder for the `start-api` subcommand.
-*/
-function createLocalStartApiCommand(opts = {}) {
+function readEnvOverridesFile$2(filePath) {
+	if (!filePath) return void 0;
+	let raw;
+	try {
+		raw = readFileSync(filePath, "utf-8");
+	} catch (err) {
+		throw new Error(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`--env-vars file '${filePath}' must contain a JSON object at the top level.`);
+	return parsed;
+}
+function createLocalInvokeAgentCoreCommand(opts = {}) {
 	setEmbedConfig(opts.embedConfig);
-	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and AWS_IAM auth (REST v1 `AuthorizationType: AWS_IAM` and Function URL `AuthType: AWS_IAM` — SigV4 signature verification only; IAM policy evaluation is NOT emulated). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[targets...]", `Optional API subset filter. Pass one or more identifiers to serve exactly that subset (the union; each on its own port). Each accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted in a TTY, a multi-select picker opens with every API pre-selected (Enter serves all, deselect to pick a subset); when omitted in a non-TTY (CI / pipe) every discovered API is served. Mirrors \`${getEmbedConfig().cliName} invoke\` / \`${getEmbedConfig().cliName} run-task\` target syntax.`).addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--all-stacks", "Serve every stack's API in a multi-stack app (each API on its own port) instead of erroring out. Mutually exclusive with a positional target subset, --stack, and an explicit --from-cfn-stack <name>; the bare --from-cfn-stack flag stays compatible (binds each routed stack to its own CFn stack).").default(false)).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when the CDK app's source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <targets...> argument instead. Accepts a SINGLE identifier; for a subset pass multiple positional targets. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).addOption(new Option("--mtls-truststore <path>", `PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj "/CN=${getEmbedConfig().resourceNamePrefix}-ca" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj "/CN=localhost"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj "/CN=client"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...`)).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--strict-sigv4", "Opt-in: DENY AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id — e.g. a federated / Cognito Identity Pool / cross-account signer — OR no local AWS credentials configured) instead of the default warn-and-pass. DEFAULT off: cdk-local warn-and-passes unverifiable IAM requests with a placeholder principalId so local dev exercises app logic without reproducing an auth boundary it cannot fully emulate. OAC-fronted Function URLs always warn-and-pass regardless.").default(false)).action(withErrorHandling(async (targets, options) => {
-		await localStartApiCommand(targets, options, opts.extraStateProviders);
+	const cmd = new Command("invoke-agentcore").description("Run a Bedrock AgentCore Runtime container locally and invoke it once over its protocol contract: HTTP (POST /invocations + GET /ping on 8080) or MCP (POST /mcp Streamable HTTP on 8000). Resolves the AWS::BedrockAgentCore::Runtime, pulls/builds its container, injects env vars + AWS credentials, and prints the response. For an MCP runtime, runs the session handshake then sends one JSON-RPC request (tools/list by default, or the method/params from --event). Target accepts a CDK display path (MyStack/MyAgent) or stack-qualified logical ID (MyStack:MyAgentRuntime1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick from a list. Supports the container artifact and the CodeConfiguration managed-runtime artifact (fromCodeAsset, built from source) on the HTTP + MCP protocols; the agent calls real AWS for managed services.").argument("[target]", "CDK display path or stack-qualified logical ID of the AgentCore Runtime to invoke (omit to pick interactively in a TTY)").action(withErrorHandling(async (target, options) => {
+		await localInvokeAgentCoreCommand(target, options, opts.extraStateProviders);
 	}));
+	addInvokeAgentCoreSpecificOptions(cmd);
 	[
 		...commonOptions(),
 		...appOptions(),
 		...contextOptions
-	].forEach((opt) => startApi.addOption(opt));
-	startApi.addOption(deprecatedRegionOption);
-	return startApi;
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+/**
+* Register the option block that `cdkl invoke-agentcore` adds on top of
+* the shared common / app / context option helpers. Shared between
+* `cdkl invoke-agentcore` and any host CLI (e.g. cdkd's
+* `local invoke-agentcore`) that wraps the single-shot AgentCore Runtime
+* container runner, so adding or renaming an `invoke-agentcore`-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 the shared common / app / context
+* options — host flags / invoke-agentcore flags / common flags grouped
+* in three `--help` clusters. Chainable: returns `cmd`.
+*/
+function addInvokeAgentCoreSpecificOptions(cmd) {
+	return cmd.addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--session-id <id>", "AgentCore runtime session id header value (default: a random UUID)")).addOption(new Option("--ws", "Stream over the HTTP-protocol agent's bidirectional /ws WebSocket endpoint (on 8080) instead of POST /invocations: send --event as the first frame and print every received frame to stdout until the agent closes. Ignored for an MCP runtime.").default(false)).addOption(new Option("--ws-interactive", "REPL mode for --ws: after the initial --event frame, read additional frames from stdin (one frame per line, trailing newline stripped) and send each as a text frame until stdin EOFs (Ctrl-D) or the agent closes. Only meaningful with --ws.").default(false)).addOption(new Option("--bearer-token <jwt>", "Bearer JWT to present when the runtime declares a customJwtAuthorizer. Verified against the runtime OIDC discovery URL (signature / issuer / expiry / audience) before the container starts, then forwarded to /invocations as Authorization: Bearer <jwt>.")).addOption(new Option("--no-verify-auth", "Skip inbound JWT verification even when the runtime declares a customJwtAuthorizer (local-dev escape hatch). A --bearer-token, if given, is still forwarded.")).addOption(new Option("--sigv4", "Sign the /invocations POST with AWS SigV4 (service bedrock-agentcore) using the resolved credentials, matching the cloud default when the runtime declares no customJwtAuthorizer. Opt-in: default unsigned. Mutually exclusive with --bearer-token; ignored on a JWT-protected runtime.").default(false)).addOption(new Option("--platform <platform>", "docker --platform for the agent container (linux/amd64 or linux/arm64)").choices(["linux/amd64", "linux/arm64"]).default("linux/arm64")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for the local-build path")).addOption(new Option("--no-build", "Skip docker build on the local-asset path (use the previously-built tag). No-op for the ECR / registry pull paths.")).addOption(new Option("--container-host <host>", "Host to bind the agent port to").default("127.0.0.1")).addOption(new Option("--timeout <ms>", "Per-request timeout in milliseconds. Applied to POST /invocations, POST /mcp, and the /ws open-to-close window. Raise this for long-running agent calls that exceed the default.").default(12e4).argParser(parseTimeoutMs)).addOption(new Option("--assume-role [arn]", "Assume the runtime's execution role and forward STS-issued temp credentials to the container so the agent runs with the deployed role. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) uses the runtime's RoleArn when it is a literal ARN; (3) `--no-assume-role` opts out. Off by default — the developer's shell credentials are forwarded unchanged.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. Bare form uses the resolved stack name; pass an explicit value when the CFn stack name differs.")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
 }
 
 //#endregion
@@ -18653,23 +20145,332 @@ function shellJoin(parts) {
 }
 
 //#endregion
-//#region src/local/ecs-service-resolver.ts
+//#region src/cli/commands/local-run-task.ts
+/**
+* `cdkl run-task <target>` — Phase 1 of the ECS local-execution
+* trilogy. Synthesizes the CDK app, locates the target
+* `AWS::ECS::TaskDefinition`, stands up a per-task docker network with
+* the AWS-published `amazon-ecs-local-container-endpoints` sidecar, and
+* starts every container in `dependsOn` order. The essential
+* container's exit code drives the CLI's exit.
+*/
+async function localRunTaskCommand(target, options, extraStateProviders) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(options);
+	const state = createEcsRunState();
+	let sigintHandler;
+	let sigintCount = 0;
+	let stateProvider;
+	let profileCredsFile;
+	let cleanupPromise;
+	const cleanup = async () => {
+		if (!cleanupPromise) cleanupPromise = (async () => {
+			try {
+				await cleanupEcsRun(state, { keepRunning: options.keepRunning });
+			} catch (err) {
+				getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			if (profileCredsFile) try {
+				await profileCredsFile.dispose();
+			} catch (err) {
+				getLogger().debug(`Failed to remove profile credentials tmpdir ${profileCredsFile.hostPath}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		})();
+		await cleanupPromise;
+	};
+	try {
+		await applyRoleArnIfSet({
+			roleArn: options.roleArn,
+			region: options.region
+		});
+		await ensureDockerAvailable();
+		const appCmd = resolveApp(options.app);
+		if (!appCmd) throw new Error(`No CDK app specified. Pass --app, set ${getEmbedConfig().envPrefix}_APP, or add "app" to cdk.json.`);
+		logger.info("Synthesizing CDK app...");
+		const synthesizer = new Synthesizer();
+		const context = parseContextOptions(options.context);
+		const synthOpts = {
+			app: appCmd,
+			output: options.output,
+			...options.region && { region: options.region },
+			...options.profile && { profile: options.profile },
+			...Object.keys(context).length > 0 && { context }
+		};
+		const { stacks } = await synthesizer.synthesize(synthOpts);
+		const resolvedTarget = await resolveSingleTarget(target, {
+			entries: listTargets(stacks).ecsTaskDefinitions,
+			message: "Select an ECS task definition to run",
+			noun: "ECS task definitions",
+			onMissing: () => new CdkLocalError(`${getEmbedConfig().cliName} run-task requires a <target> (an ECS task definition display path or logical ID). Run \`${getEmbedConfig().cliName} list\` to see them, or run it in a TTY to pick interactively.`, "LOCAL_RUN_TASK_TARGET_REQUIRED")
+		});
+		const candidate = pickCandidateStack$1(parseEcsTarget(resolvedTarget).stackPattern, stacks);
+		stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
+		const imageContext = await buildEcsImageResolutionContext$1(candidate, stateProvider, options);
+		const task = resolveEcsTaskTarget(resolvedTarget, stacks, imageContext);
+		logger.info(`Target: ${task.stack.stackName}/${task.taskDefinitionLogicalId} (family=${task.family}, containers=${task.containers.length})`);
+		const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === task.stack.stackName) ?? task.stack);
+		if (stateProvider && taskNeeds.needsCrossStackResolver) {
+			const consumerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? task.stack.region ?? "us-east-1";
+			const resolver = await stateProvider.buildCrossStackResolver(consumerRegion);
+			if (resolver) await applyCrossStackResolverToTask(task, {
+				resources: imageContext?.stateResources ?? {},
+				...imageContext?.pseudoParameters && { pseudoParameters: imageContext.pseudoParameters },
+				...imageContext?.stateParameters && { parameters: imageContext.stateParameters },
+				...imageContext?.stateSensitiveParameters?.length && { sensitiveParameters: new Set(imageContext.stateSensitiveParameters) },
+				consumerRegion,
+				crossStackResolver: resolver
+			});
+		} else if (!stateProvider && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to substitute them against deployed state.");
+		sigintHandler = () => {
+			sigintCount += 1;
+			if (sigintCount >= 2) {
+				process.stderr.write("Force-exit on second ^C; container cleanup skipped.\n");
+				process.exit(130);
+			}
+			logger.info("Stopping task...");
+			cleanup().then(() => process.exit(130));
+		};
+		process.on("SIGINT", sigintHandler);
+		let assumedCredentials;
+		let resolvedRoleArn;
+		if (options.assumeTaskRole === true) {
+			if (!task.taskRoleArn) throw new Error(`--assume-task-role passed without an ARN but the task definition has no resolvable TaskRoleArn. Either the task definition does not set TaskRoleArn, or it points at a resource ${getEmbedConfig().binaryName} cannot resolve to an IAM Role at synth time. Pass the ARN explicitly: --assume-task-role <arn>`);
+			resolvedRoleArn = await resolvePlaceholderAccount$1(task.taskRoleArn, options.region);
+			assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region);
+		} else if (typeof options.assumeTaskRole === "string") {
+			resolvedRoleArn = options.assumeTaskRole;
+			assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region);
+		}
+		const sidecarCredentials = await resolveSidecarCredentials(options, assumedCredentials);
+		if (options.profile && sidecarCredentials && !assumedCredentials) profileCredsFile = await writeProfileCredentialsFile(options.profile, sidecarCredentials);
+		const envOverrides = readEnvOverridesFile$1(options.envVars);
+		const runOpts = {
+			cluster: options.cluster,
+			containerHost: options.containerHost,
+			skipPull: options.pull === false,
+			keepRunning: options.keepRunning,
+			detach: options.detach
+		};
+		if (envOverrides) runOpts.envOverrides = envOverrides;
+		if (sidecarCredentials) runOpts.taskCredentials = sidecarCredentials;
+		if (resolvedRoleArn) runOpts.taskRoleArn = resolvedRoleArn;
+		if (options.platform) runOpts.platformOverride = options.platform;
+		if (options.region) runOpts.region = options.region;
+		if (options.ecrRoleArn) runOpts.ecrRoleArn = options.ecrRoleArn;
+		if (options.profile) runOpts.profile = options.profile;
+		const hostPortOverrides = parseHostPortOverrides(options.hostPort);
+		if (Object.keys(hostPortOverrides).length > 0) runOpts.hostPortOverrides = hostPortOverrides;
+		if (profileCredsFile) runOpts.profileCredentialsFile = {
+			hostPath: profileCredsFile.hostPath,
+			containerPath: profileCredsFile.containerPath,
+			profileName: profileCredsFile.profileName
+		};
+		const result = await runEcsTask(task, runOpts, state);
+		if (options.detach) {
+			logger.info(`Task containers started in detached mode; ${getEmbedConfig().binaryName} is exiting.`);
+			logger.info(`Use 'docker ps --filter network=${result.state.network?.networkName ?? "<network>"}' to inspect; tear down with 'docker rm -f' and 'docker network rm'.`);
+			sigintCount = 99;
+			return;
+		}
+		if (result.essentialContainerName) logger.info(`Essential container '${result.essentialContainerName}' exited with code ${result.exitCode}.`);
+		if (result.exitCode !== 0) process.exitCode = result.exitCode;
+	} finally {
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		if (stateProvider) stateProvider.dispose();
+		if (!options.detach) await cleanup();
+	}
+}
+/**
+* If `arn` contains the `${AWS::AccountId}` placeholder emitted by the
+* resolver for inline same-stack IAM Roles, substitute the live caller
+* account via STS `GetCallerIdentity`. Otherwise pass through unchanged.
+*/
+async function resolvePlaceholderAccount$1(arn, region) {
+	if (!arn.includes("${AWS::AccountId}")) return arn;
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const account = (await sts.send(new GetCallerIdentityCommand({}))).Account;
+		if (!account) throw new Error(`--assume-task-role: GetCallerIdentity returned no Account; cannot resolve placeholder ARN '${arn}'. Pass the ARN explicitly: --assume-task-role <arn>`);
+		return arn.split(TASK_ROLE_ACCOUNT_PLACEHOLDER).join(account);
+	} finally {
+		sts.destroy();
+	}
+}
+/**
+* Assume `roleArn` and return temp credentials.
+*/
+async function assumeTaskRole$1(roleArn, region) {
+	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const creds = (await sts.send(new AssumeRoleCommand({
+			RoleArn: roleArn,
+			RoleSessionName: `${getEmbedConfig().resourceNamePrefix}-run-task-${Date.now()}`,
+			DurationSeconds: 3600
+		}))).Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new Error(`AssumeRole(${roleArn}) returned no usable credentials.`);
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			sessionToken: creds.SessionToken
+		};
+	} finally {
+		sts.destroy();
+	}
+}
 /**
-* Walk the synth template to locate an `AWS::ECS::Service` by display
-* path or stack-qualified logical id, resolve its `TaskDefinition`
-* reference, and chain into the existing `resolveEcsTaskTarget` machinery
-* to produce a `ResolvedEcsService` carrying both the service knobs and
-* the underlying task descriptor.
+* Build the substitution context the ECS task resolver consumes.
+* Returns `undefined` when no container's `Image` field needs
+* substitution — the resolver behaves as before in that case.
+*/
+async function buildEcsImageResolutionContext$1(candidate, stateProvider, options) {
+	const logger = getLogger();
+	if (!candidate) return void 0;
+	const needs = detectEcsImageResolutionNeeds(candidate);
+	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
+	const ctx = {};
+	const wantsPseudoForEnvOrSecret = !!stateProvider && needs.needsEnvOrSecretSubstitution;
+	if (needs.needsPseudoParameters || wantsPseudoForEnvOrSecret) {
+		const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
+		if (!region) logger.warn(`Resolver references \${AWS::Region} but ${getEmbedConfig().binaryName} could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.`);
+		let accountId;
+		try {
+			accountId = await resolveCallerAccountId$1(region, options.profile);
+		} catch (err) {
+			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
+		}
+		const partitionAndSuffix = region ? derivePartitionAndUrlSuffix(region) : void 0;
+		ctx.pseudoParameters = {
+			...accountId !== void 0 && { accountId },
+			...region !== void 0 && { region },
+			...partitionAndSuffix && {
+				partition: partitionAndSuffix.partition,
+				urlSuffix: partitionAndSuffix.urlSuffix
+			}
+		};
+	}
+	const wantsState = needs.needsStateResources || needs.needsEnvOrSecretSubstitution;
+	if (stateProvider && wantsState) {
+		const loaded = await stateProvider.load(candidate.stackName, candidate.region);
+		if (loaded) ctx.stateResources = loaded.resources;
+		if (needs.needsEnvOrSecretSubstitution && stateProvider.resolveTemplateSsmParameters) {
+			const ssmParameters = await stateProvider.resolveTemplateSsmParameters(candidate.template);
+			if (Object.keys(ssmParameters.values).length > 0) ctx.stateParameters = ssmParameters.values;
+			if (ssmParameters.secureStringLogicalIds.length > 0) ctx.stateSensitiveParameters = ssmParameters.secureStringLogicalIds;
+		}
+	} else if (!stateProvider && needs.needsStateResources) logger.warn("Container Image references a same-stack AWS::ECR::Repository. Pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to substitute the deployed repository URI. Otherwise the resolver will surface its existing error.");
+	else if (!stateProvider && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics (Ref / Fn::GetAtt / Fn::Sub / Fn::Join). Pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to substitute them against deployed state. Without a state source these entries are dropped (per-key warnings will follow).");
+	return ctx;
+}
+function pickCandidateStack$1(stackPattern, stacks) {
+	if (stackPattern === null) {
+		if (stacks.length === 1) return stacks[0];
+		return;
+	}
+	const matched = matchStacks(stacks, [stackPattern]);
+	if (matched.length === 1) return matched[0];
+}
+async function resolveCallerAccountId$1(region, profile) {
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({
+		...region && { region },
+		...profile && { profile }
+	});
+	try {
+		return (await sts.send(new GetCallerIdentityCommand({}))).Account;
+	} finally {
+		sts.destroy();
+	}
+}
+/**
+* Read the `--env-vars` JSON file using the same SAM-style shape as
+* `cdkl invoke --env-vars`: top-level keys are container names, with
+* `Parameters` reserved for global entries.
+*/
+function readEnvOverridesFile$1(filePath) {
+	if (!filePath) return void 0;
+	let raw;
+	try {
+		raw = readFileSync(filePath, "utf-8");
+	} catch (err) {
+		throw new Error(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`--env-vars file '${filePath}' must contain a JSON object at the top level.`);
+	return parsed;
+}
+/**
+* Pick the credentials forwarded to the AWS-published
+* `amazon-ecs-local-container-endpoints` sidecar. Precedence:
+*   1. `--assume-task-role <arn>` (or bare `--assume-task-role` against
+*      a resolvable `TaskRoleArn`) → STS-assumed temp creds. Highest
+*      priority — when the user opted in to IAM emulation, those creds
+*      drive the sidecar regardless of `--profile`.
+*   2. `--profile <p>` → resolved via {@link resolveProfileCredentials}
+*      (the SDK's default credential provider chain — SSO / IAM
+*      Identity Center / fromIni / role-assumption). NEW in this PR.
+*   3. Neither set → `undefined`; the sidecar runs with its own
+*      default credential chain (typically empty inside a fresh
+*      container — user containers will get 4xx from the credentials
+*      endpoint, mimicking IAM-misconfigured prod).
+*
+* Extracted as an exported helper so a unit test can exercise every
+* branch without having to mock the full Synth + Docker + AWS pipeline
+* (the strategy used for the Lambda container path).
+*/
+async function resolveSidecarCredentials(options, assumedCredentials) {
+	if (assumedCredentials) return assumedCredentials;
+	if (options.profile) return resolveProfileCredentials(options.profile);
+}
+function createLocalRunTaskCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	const cmd = new Command("run-task").description("Run an AWS::ECS::TaskDefinition locally — pulls/builds images, sets up a per-task docker network with the AWS-published metadata-endpoints sidecar, and starts every container in dependsOn order. Target accepts a CDK display path (MyStack/MyService/TaskDef) or stack-qualified logical ID (MyStack:MyServiceTaskDefXYZ1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick the task definition from a list.").argument("[target]", "CDK display path or stack-qualified logical ID of the AWS::ECS::TaskDefinition to run (omit to pick interactively in a TTY)").action(withErrorHandling(async (target, options) => {
+		await localRunTaskCommand(target, options, opts.extraStateProviders);
+	}));
+	addRunTaskSpecificOptions(cmd);
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+/**
+* Register the option block that `cdkl run-task` adds on top of the shared
+* common / app / context option helpers. Shared between `cdkl run-task` and
+* any host CLI (e.g. cdkd's `local run-task`) that wraps the single-task
+* ECS local runner, so adding or renaming a `run-task`-only flag here
+* propagates to every embedder without duplicate `.addOption(...)` blocks.
 *
-* Target shape mirrors `cdkl run-task`: `<Stack>/<DisplayPath>` or
-* `<Stack>:<LogicalId>`; single-stack apps may omit the stack prefix.
+* Calling order only affects `--help` presentation (Commander parses
+* insertion-order-independent). The host-CLI convention is host-specific
+* options first, then this helper, then the shared common / app / context
+* options — host flags / run-task flags / common flags grouped in three
+* `--help` clusters. Chainable: returns `cmd`.
 *
-* Optional `context` (same as the task resolver) carries the ECR image
-* substitution data — pseudo parameters (Tier 1) + state-recorded
-* resources (Tier 2). The CLI builds it lazily when the candidate
-* service's task definition actually needs substitution.
+* NOTE: `run-task` does NOT compose with {@link addCommonEcsServiceOptions}
+* even though many flags overlap. The two ECS surfaces (single-task vs
+* multi-replica service) have intentionally divergent defaults
+* (`run-task` has no `--max-tasks` / `--restart-policy`; `start-service`
+* / `start-alb` have no `--host-port` / `--keep-running` / `--detach`),
+* and folding `run-task` into the service common block would mutate the
+* surface non-trivially. Each command keeps its own helper.
 */
-function resolveEcsServiceTarget(target, stacks, context) {
+function addRunTaskSpecificOptions(cmd) {
+	return cmd.addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default(getEmbedConfig().resourceNamePrefix)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).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.")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed function role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--keep-running", "Don't docker rm -f the user containers on task exit (network + sidecar are still torn down). Use when you want to docker exec into a stopped container for post-mortems.").default(false)).addOption(new Option("--detach", "Start the containers in the background and exit (skip log streaming + auto teardown). Useful in CI smoke tests; caller manages container lifecycle.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", `Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in container env vars / secrets / image URIs with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (\`cdk deploy\`). Bare form uses the ${getEmbedConfig().binaryName} stack name; pass an explicit value when the CFn stack name differs. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).`)).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
+}
+
+//#endregion
+//#region src/local/ecs-service-resolver.ts
+function resolveEcsServiceTarget(target, stacks, context, options) {
 	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
 	const parsed = parseEcsTarget(target);
 	const stack = pickStack$1(parsed, stacks);
@@ -18691,14 +20492,14 @@ function resolveEcsServiceTarget(target, stacks, context) {
 	if (!serviceLogicalId || !serviceResource) throw notFoundError(target, stack, resources, parsed);
 	if (serviceResource.Type === "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is an ECS TaskDefinition, not a Service. Use \`${getEmbedConfig().cliName} run-task\` for one-shot tasks; \`${getEmbedConfig().cliName} start-service\` is Service-only.`);
 	if (serviceResource.Type !== "AWS::ECS::Service") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is ${serviceResource.Type}, not an AWS::ECS::Service.`);
-	return extractServiceProperties(stack, serviceLogicalId, serviceResource, stacks, context);
+	return extractServiceProperties(stack, serviceLogicalId, serviceResource, stacks, context, options);
 }
 /**
 * Pure-functional extraction from the synth resource. Exposed for unit
 * testing the per-field resolution rules (DesiredCount default, missing
 * TaskDefinition, intrinsic shapes).
 */
-function extractServiceProperties(stack, serviceLogicalId, resource, stacks, context) {
+function extractServiceProperties(stack, serviceLogicalId, resource, stacks, context, options) {
 	const props = resource.Properties ?? {};
 	const warnings = [];
 	const taskDefRef = props["TaskDefinition"];
@@ -18708,7 +20509,10 @@ function extractServiceProperties(stack, serviceLogicalId, resource, stacks, con
 	const desiredCount = parseDesiredCount(props["DesiredCount"], serviceLogicalId);
 	const healthCheckGracePeriodSeconds = parseHealthCheckGrace(props["HealthCheckGracePeriodSeconds"], serviceLogicalId);
 	const serviceName = parseServiceName(props["ServiceName"], serviceLogicalId);
-	if (Array.isArray(props["LoadBalancers"]) && props["LoadBalancers"].length > 0) warnings.push(`ECS Service '${serviceLogicalId}' declares LoadBalancers, but local load-balancer emulation is deferred to a follow-up PR. Containers are NOT registered to a local listener; reach them via their published ports.`);
+	if (!options?.suppressLoadBalancerWarning && Array.isArray(props["LoadBalancers"]) && props["LoadBalancers"].length > 0) {
+		const { cliName } = getEmbedConfig();
+		warnings.push(`ECS Service '${serviceLogicalId}' declares LoadBalancers, but \`${cliName} start-service\` runs the replicas only; no local listener fronts them. Reach the containers via their published ports, or run \`${cliName} start-alb <Stack>/<Alb>\` to boot the same replicas behind a local front-door that round-robins the listener rules.`);
+	}
 	const serviceConnect = extractServiceConnect(props["ServiceConnectConfiguration"], task);
 	const out = {
 		stack,
@@ -18999,11 +20803,14 @@ async function getPublishedHostPort(containerId, containerPort, protocol = "tcp"
 * design's §O5 "--no-envoy by default" recommendation.
 *
 * Deferred to follow-up PRs:
-*   - Local load-balancer emulation (LB listener + target-group health
-*     check + round-robin) — separate PR per the issue's PR-split.
 *   - Envoy sidecar for Service Connect L7 routing / retries / circuit
 *     breaking (Cloud Map DNS-only mode ships now).
 *   - Rolling deployment (`--reload` / `--watch`).
+*
+* Local load-balancer emulation is now first-class via `start-alb`, which
+* boots the same replicas behind a local front-door that mirrors the
+* deployed ALB's listener-rule / forward / redirect / fixed-response /
+* authenticate-* surface; `start-service` runs the replicas only.
 */
 var EcsServiceRunnerError = class EcsServiceRunnerError extends Error {
 	constructor(message) {
@@ -21555,7 +23362,7 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		};
 		process.on("SIGINT", sigintHandler);
 		process.on("SIGTERM", sigintHandler);
-		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.boot, pt.runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService.get(pt.boot.target));
+		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);
 		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}.`);
@@ -21572,20 +23379,20 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		await cleanup();
 	}
 }
-async function bootOneTarget(boot, runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools) {
+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);
 	try {
-		return await runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools);
+		return await runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning);
 	} finally {
 		if (stateProvider) stateProvider.dispose();
 	}
 }
-async function runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools) {
+async function runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning) {
 	const logger = getLogger();
 	const target = boot.target;
 	const imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
-	const service = resolveEcsServiceTarget(target, stacks, imageContext);
+	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})`);
 	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).`);
@@ -22852,7 +24659,8 @@ function albStrategy(options) {
 				warnings
 			};
 		},
-		lbPortOverrides
+		lbPortOverrides,
+		suppressLoadBalancerWarning: true
 	};
 }
 /**
@@ -22890,5 +24698,97 @@ function addAlbSpecificOptions(cmd) {
 }
 
 //#endregion
-export { VtlEvaluationError as $, substituteImagePlaceholders as $n, pickFreePort as $t, availableApiIdentifiers as A, resolveSsmParameters as An, parseSseForJsonRpc as At, computeRequestIdentityHash as B, discoverRoutes as Bn, renderCodeDockerfile as Bt, createWatchPredicates as C, isCfnFlagPresent as Cn, A2A_CONTAINER_PORT as Ct, createFileWatcher as D, resolveCfnStackName as Dn, MCP_PATH as Dt, createAuthorizerCache as E, resolveCfnRegion as En, MCP_CONTAINER_PORT as Et, startApiServer as F, countTargets as Fn, waitForAgentCorePing as Ft, translateLambdaResponse as G, AGENTCORE_HTTP_PROTOCOL as Gn, getDockerImageBySourceHash as Gt, invokeRequestAuthorizer as H, resolveLambdaArnIntrinsic as Hn, writeProfileCredentialsFile as Ht, resolveSelectionExpression as I, listTargets as In, downloadAndExtractS3Bundle as It, buildRestV1Event as J, AgentCoreResolutionError as Jn, architectureToPlatform as Jt, applyAuthorizerOverlay as K, AGENTCORE_MCP_PROTOCOL as Kn, invokeRie as Kt, resolveServiceIntegrationParameters as L, discoverWebSocketApis as Ln, SUPPORTED_CODE_RUNTIMES as Lt, filterRoutesByApiIdentifiers as M, resolveWatchConfig as Mn, signAgentCoreInvocation as Mt, groupRoutesByServer as N, Synthesizer as Nn, AGENTCORE_SESSION_ID_HEADER as Nt, attachStageContext as O, CfnLocalStateProvider as On, MCP_PROTOCOL_VERSION as Ot, readMtlsMaterialsFromDisk as P, resolveSingleTarget as Pn, invokeAgentCore as Pt, tryParseStatus as Q, derivePseudoParametersFromRegion as Qn, ensureDockerAvailable as Qt, defaultCredentialsLoader as R, discoverWebSocketApisOrThrow as Rn, buildAgentCoreCodeImage as Rt, createLocalStartApiCommand as S, createLocalStateProvider as Sn, invokeAgentCoreWs as St, resolveProfileCredentials as T, resolveCfnFallbackRegion as Tn, a2aInvokeOnce as Tt, invokeTokenAuthorizer as U, AGENTCORE_A2A_PROTOCOL as Un, singleFlight as Ut, evaluateCachedLambdaPolicy as V, pickRefLogicalId as Vn, toCmdArgv as Vt, matchRoute as W, AGENTCORE_AGUI_PROTOCOL as Wn, AssetManifestLoader as Wt, pickResponseTemplate as X, resolveAgentCoreTarget as Xn, parseEcrUri as Xt, evaluateResponseParameters as Y, pickAgentCoreCandidateStack as Yn, buildContainerImage as Yt, selectIntegrationResponse as Z, resolveLambdaTarget as Zn, pullEcrImage as Zt, getContainerNetworkIp as _, substituteEnvVarsFromState as _n, applyCorsResponseHeaders as _t, resolveAlbTarget as a, resolveRuntimeFileExtension as an, LocalStartServiceError as ar, handleConnectionsRequest as at, parseHostPortOverrides as b, materializeLayerFromArn as bn, isFunctionUrlOacFronted as bt, MAX_TASKS_SUBNET_RANGE_CAP as c, TASK_ROLE_ACCOUNT_PLACEHOLDER as cn, appOptions as cr, buildDisconnectEvent as ct, parseMaxTasks as d, detectEcsImageResolutionNeeds as dn, deprecatedRegionOption as dr, buildJwksUrlFromIssuer as dt, pullImage as en, tryResolveImageFnJoin as er, HOST_GATEWAY_MIN_VERSION as et, parseRestartPolicy as f, parseEcsTarget as fn, parseContextOptions as fr, createJwksCache as ft, CloudMapRegistry as g, substituteAgainstStateAsync as gn, attachAuthorizers as gt, buildCloudMapIndex as h, substituteAgainstState as hn, verifyJwtViaDiscovery as ht, parseLbPortOverrides as i, resolveRuntimeCodeMountPath as in, LocalInvokeBuildError as ir, buildMgmtEndpointEnvUrl as it, filterRoutesByApiIdentifier as j, resolveApp as jn, AGENTCORE_SIGV4_SERVICE as jt, buildStageMap as k, collectSsmParameterRefs as kn, mcpInvokeOnce as kt, addCommonEcsServiceOptions as l, applyCrossStackResolverToTask as ln, commonOptions as lr, buildMessageEvent as lt, runEcsServiceEmulator as m, applyDeployedEnvFallback as mn, verifyJwtAuthorizer as mt, albStrategy as n, runDetached as nn, readCdkPathOrUndefined as nr, bufferToBody as nt, isApplicationLoadBalancer as o, resolveRuntimeImage as on, withErrorHandling as or, parseConnectionsPath as ot, resolveSharedSidecarCredentials as p, resolveEcsTaskTarget as pn, warnIfDeprecatedRegion as pr, verifyCognitoJwt as pt, buildHttpApiV2Event as q, AGENTCORE_RUNTIME_TYPE as qn, waitForRieReady as qt, createLocalStartAlbCommand as r, streamLogs as rn, CdkLocalError as rr, ConnectionRegistry as rt, resolveAlbFrontDoor as s, EcsTaskResolutionError as sn, applyRoleArnIfSet as sr, buildConnectEvent as st, addAlbSpecificOptions as t, removeContainer as tn, matchStacks as tr, probeHostGatewaySupport as tt, buildEcsImageResolutionContext as u, derivePartitionAndUrlSuffix as un, contextOptions as ur, buildCognitoJwksUrl as ut, cleanupEcsRun as v, substituteEnvVarsFromStateAsync as vn, buildCorsConfigByApiId as vt, resolveApiTargetSubset as w, rejectExplicitCfnStackWithMultipleStacks as wn, A2A_PATH as wt, runEcsTask as x, LocalStateSourceError as xn, matchPreflight as xt, createEcsRunState as y, resolveEnvVars as yn, buildCorsConfigFromCloudFrontChain as yt, buildMethodArn as z, parseSelectionExpressionPath as zn, computeCodeImageTag as zt };
-//# sourceMappingURL=local-start-alb-CIE0TMpn.js.map
+//#region src/cli/commands/local-list.ts
+async function localListCommand(options) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(options);
+	await applyRoleArnIfSet({
+		roleArn: options.roleArn,
+		region: void 0
+	});
+	const appCmd = resolveApp(options.app);
+	if (!appCmd) throw new Error(`No CDK app specified. Pass --app, set ${getEmbedConfig().envPrefix}_APP, or add "app" to cdk.json.`);
+	process.stderr.write("Synthesizing CDK app...\n");
+	const synthesizer = new Synthesizer();
+	const context = parseContextOptions(options.context);
+	const synthOpts = {
+		app: appCmd,
+		output: options.output,
+		...options.profile && { profile: options.profile },
+		...Object.keys(context).length > 0 && { context }
+	};
+	const { stacks } = await synthesizer.synthesize(synthOpts);
+	const listing = listTargets(stacks);
+	process.stdout.write(`${formatTargetListing(listing, getEmbedConfig().cliName, { long: options.long })}\n`);
+}
+/**
+* Render a {@link TargetListing} as the grouped text list `cdkl list`
+* prints. Each non-empty category is preceded by a blank line and a
+* header naming the command that runs it, then one target per line by
+* CDK display path. With {@link FormatTargetListingOptions.long}, each
+* target's stack-qualified logical ID is printed on an indented line
+* beneath it. Exported so a unit test can assert the output shape
+* without running synthesis.
+*/
+function formatTargetListing(listing, cliName, options = {}) {
+	if (countTargets(listing) === 0) return `No runnable targets (Lambda functions, APIs, ECS services / tasks, AgentCore Runtimes, load balancers) found in this CDK app.`;
+	const long = options.long ?? false;
+	return "\n" + [
+		formatSection("Lambda Functions", `${cliName} invoke <target>`, listing.lambdas, long),
+		formatSection("APIs", `${cliName} start-api [target...]`, listing.apis, long),
+		formatSection("ECS Services", `${cliName} start-service <target...>`, listing.ecsServices, long),
+		formatSection("ECS Task Definitions", `${cliName} run-task <target>`, listing.ecsTaskDefinitions, long),
+		formatSection("AgentCore Runtimes", `${cliName} invoke-agentcore <target>`, listing.agentCoreRuntimes, long),
+		formatSection("Application Load Balancers", `${cliName} start-alb <target...>`, listing.loadBalancers, long)
+	].filter((lines) => lines.length > 0).map((lines) => lines.join("\n")).join("\n\n");
+}
+function formatSection(title, command, entries, long) {
+	if (entries.length === 0) return [];
+	const lines = [`${title}  ->  ${command}`];
+	for (const entry of entries) {
+		const primary = entry.displayPath ?? entry.qualifiedId;
+		lines.push(entry.kind ? `  ${primary}  (${entry.kind})` : `  ${primary}`);
+		if (long && entry.displayPath) lines.push(`      ${entry.qualifiedId}`);
+	}
+	return lines;
+}
+function createLocalListCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	const cmd = new Command("list").alias("ls").description("List the runnable targets in the synthesized CDK app, grouped by the command that runs them: Lambda functions (invoke), API Gateway REST v1 / HTTP v2 / Function URL / WebSocket surfaces (start-api), ECS services (start-service), ECS task definitions (run-task), AgentCore Runtimes (invoke-agentcore), and Application Load Balancers (start-alb). Each target is shown by its CDK display path; pass -l to also print the stack-qualified logical ID. Tip: you usually do not need to copy these — just run the command (e.g. `invoke`) with no target in a terminal and pick from the list.").action(withErrorHandling(async (options) => {
+		await localListCommand(options);
+	}));
+	addListSpecificOptions(cmd);
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+/**
+* Register the option block that `cdkl list` adds on top of the shared
+* common / app / context option helpers. Shared between `cdkl list` and any
+* host CLI (e.g. cdkd's `local list`) that wraps the synthesis-driven
+* target enumeration, so adding or renaming a `list`-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 the shared common / app / context
+* options — host flags / list flags / common flags grouped in three
+* `--help` clusters. Chainable: returns `cmd`.
+*
+* Today `cdkl list` only contributes one non-common flag (`-l, --long`),
+* but the helper is still exposed so the surface-contract test pattern
+* (helper + common == createLocalListCommand) is uniform across every
+* `add<Cmd>SpecificOptions` extraction.
+*/
+function addListSpecificOptions(cmd) {
+	return cmd.addOption(new Option("-l, --long", "Also print each target's stack-qualified logical ID (<Stack>:<LogicalId>) beneath it").default(false));
+}
+
+//#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