cdk-local 0.61.1 → 0.62.1

package/dist/local-list-BPbd4EMs.js

@@ -0,0 +1,2036 @@
+import { c as getEmbedConfig, s as getLogger, u as setEmbedConfig } from "./docker-cmd-voNPrcRh.js";
+import { $n as resolveCdkPathToLogicalIds, $t as resolveRuntimeCodeMountPath, An as countTargets, At as waitForAgentCorePing, Bt as getDockerImageBySourceHash, Dt as signAgentCoreInvocation, En as resolveApp, Gn as resolveAgentCoreTarget, Gt as parseEcrUri, Ht as waitForRieReady, Jt as pickFreePort, Kn as resolveLambdaTarget, Kt as pullEcrImage, Lt as writeProfileCredentialsFile, Nt as buildAgentCoreCodeImage, On as Synthesizer, Qn as readCdkPathOrUndefined, Qt as streamLogs, Rn as AGENTCORE_A2A_PROTOCOL, Rt as singleFlight, St as MCP_PATH, Ut as architectureToPlatform, Vn as AGENTCORE_MCP_PROTOCOL, Vt as invokeRie, Wn as pickAgentCoreCandidateStack, Wt as buildContainerImage, Xn as matchStacks, Xt as removeContainer, Yt as pullImage, Zn as buildCdkPathIndex, Zt as runDetached, _n as createLocalStateProvider, _t as invokeAgentCoreWs, an as derivePartitionAndUrlSuffix, ar as appOptions, b as resolveProfileCredentials$1, bn as resolveCfnFallbackRegion, bt as a2aInvokeOnce, cn as resolveEcsTaskTarget, cr as deprecatedRegionOption, dn as substituteAgainstStateAsync, en as resolveRuntimeFileExtension, er as CdkLocalError, g as runEcsTask, h as parseHostPortOverrides, hn as materializeLayerFromArn, i as addCommonEcsServiceOptions, in as applyCrossStackResolverToTask, ir as applyRoleArnIfSet, jn as listTargets, jt as downloadAndExtractS3Bundle, kn as resolveSingleTarget, kt as invokeAgentCore, l as runEcsServiceEmulator, ln as applyDeployedEnvFallback, lr as parseContextOptions, m as createEcsRunState, mn as resolveEnvVars, n as resolveAlbFrontDoor, nr as LocalStartServiceError, on as detectEcsImageResolutionNeeds, or as commonOptions, p as cleanupEcsRun, pn as substituteEnvVarsFromStateAsync, qn as derivePseudoParametersFromRegion, qt as ensureDockerAvailable, rn as TASK_ROLE_ACCOUNT_PLACEHOLDER, rr as withErrorHandling, sn as parseEcsTarget, sr as contextOptions, st as createJwksCache, t as isApplicationLoadBalancer, tn as resolveRuntimeImage, ur as warnIfDeprecatedRegion, ut as verifyJwtViaDiscovery, vt as A2A_CONTAINER_PORT, wt as mcpInvokeOnce, xt as MCP_CONTAINER_PORT, yt as A2A_PATH, zn as AGENTCORE_AGUI_PROTOCOL, zt as AssetManifestLoader } from "./elb-front-door-resolver-CsCmMUqz.js";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { dirname } from "node:path";
+import { Command, Option } from "commander";
+import { randomUUID } from "node:crypto";
+
+//#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(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(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(templateEnv)) {
+					const pseudo = await resolvePseudoParametersForInvoke(lambda.stack.region, options);
+					if (pseudo) subContext.pseudoParameters = pseudo;
+				}
+				if (envHasIntrinsicValue(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$2(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(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$1(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(lambda, options);
+	return resolveContainerImagePlan(lambda, options);
+}
+async function resolveZipImagePlan(lambda, options) {
+	let inlineTmpDir;
+	let codeDir = lambda.codePath;
+	if (codeDir === null) {
+		inlineTmpDir = materializeInlineCode(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(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(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(lambda, options) {
+	const logger = getLogger();
+	const platform = architectureToPlatform(lambda.architecture);
+	const localBuild = await resolveLocalBuildPlan(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(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(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(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$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;
+}
+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(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$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;
+	}
+}
+/**
+* Resolve `--profile <p>` to a concrete credential set. Mirrors the
+* helper in `local-start-api.ts`.
+*/
+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.");
+		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(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)").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.")).action(withErrorHandling(async (target, options) => {
+		await localInvokeCommand(target, options, opts.extraStateProviders);
+	}));
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((option) => invoke.addOption(option));
+	invoke.addOption(deprecatedRegionOption);
+	return invoke;
+}
+
+//#endregion
+//#region src/cli/commands/local-invoke-agentcore.ts
+/**
+* Parser for `--timeout <ms>`. Accepts a positive integer; rejects 0,
+* negatives, fractions, and non-numeric input.
+*/
+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 {
+		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 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 {
+		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		await cleanup();
+	}
+}
+/**
+* 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.
+*/
+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;
+	}
+	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;
+}
+/**
+* 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`).
+*
+* Throws a {@link CdkLocalError} when none are available — `--sigv4` cannot
+* proceed without credentials, unlike the unsigned path.
+*/
+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"}.`);
+	}
+	if (options.profile) {
+		const creds = await resolveProfileCredentials$1(options.profile);
+		if (creds?.accessKeyId && creds.secretAccessKey) return {
+			accessKeyId: creds.accessKeyId,
+			secretAccessKey: creds.secretAccessKey,
+			...creds.sessionToken && { sessionToken: creds.sessionToken }
+		};
+	}
+	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");
+}
+/**
+* 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.
+*/
+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
+	});
+}
+/**
+* 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.
+*
+* 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 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(`--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 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();
+	}
+}
+/**
+* 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 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;
+}
+/**
+* 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).
+*
+* 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$1(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;
+}
+/**
+* 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).
+*/
+async function buildAgentCoreImageContext(candidate, stateProvider, options) {
+	const logger = getLogger();
+	const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
+	let accountId;
+	try {
+		accountId = await resolveCallerAccountId$1(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 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 {
+		context,
+		loaded: loaded ?? void 0
+	};
+}
+/** STS `GetCallerIdentity` for the `${AWS::AccountId}` pseudo parameter (threads `--profile`). */
+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();
+	}
+}
+/**
+* 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 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(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;
+			}
+		}
+	}
+	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`);
+}
+/**
+* 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.
+*
+* Exported for unit testing.
+*/
+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(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 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 {
+			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) {
+		throw new Error(`Failed to parse event payload from ${source} as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+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");
+}
+/**
+* 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 so a unit test can drive the iterable shape directly.
+*/
+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();
+	}
+}
+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;
+}
+function createLocalInvokeAgentCoreCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	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)").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.")).action(withErrorHandling(async (target, options) => {
+		await localInvokeAgentCoreCommand(target, options, opts.extraStateProviders);
+	}));
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+
+//#endregion
+//#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(parseEcsTarget(resolvedTarget).stackPattern, stacks);
+		stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
+		const imageContext = await buildEcsImageResolutionContext(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(task.taskRoleArn, options.region);
+			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+		} else if (typeof options.assumeTaskRole === "string") {
+			resolvedRoleArn = options.assumeTaskRole;
+			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+		}
+		const sidecarCredentials = await resolveSidecarCredentials(options, assumedCredentials);
+		if (options.profile && sidecarCredentials && !assumedCredentials) profileCredsFile = await writeProfileCredentialsFile(options.profile, sidecarCredentials);
+		const envOverrides = readEnvOverridesFile(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(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(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();
+	}
+}
+/**
+* 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(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(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(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(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(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$1(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)").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.")).action(withErrorHandling(async (target, options) => {
+		await localRunTaskCommand(target, options, opts.extraStateProviders);
+	}));
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+
+//#endregion
+//#region src/cli/commands/local-start-service.ts
+/**
+* `cdkl start-service` strategy — a pure ECS replica runner. It picks
+* `AWS::ECS::Service` targets and boots each with NO front-door (the ALB
+* front-door is its own command, `cdkl start-alb`). This keeps `start-service`
+* a leaf compute runner, symmetric with `invoke` / `run-task`.
+*/
+function serviceStrategy() {
+	return {
+		pickEntries: (stacks) => listTargets(stacks).ecsServices,
+		pickerMessage: "Select one or more ECS services to run",
+		pickerNoun: "ECS services",
+		onMissing: () => new LocalStartServiceError(`${getEmbedConfig().cliName} start-service requires at least one <target>. Pass one or more service paths like 'Stack/Orders' 'Stack/Frontend', or run it in a TTY to pick interactively.`),
+		resolveBoots: (_stacks, chosenTargets) => ({
+			boots: chosenTargets.map((target) => ({ target })),
+			warnings: []
+		}),
+		lbPortOverrides: {}
+	};
+}
+/**
+* `cdkl start-service <Stack/Service>` — Phase 2 of #262. Spins up
+* `DesiredCount` task replicas locally (clamped by `--max-tasks`) using the
+* existing `ecs-task-runner` per replica. Long-running; ^C cleans every replica
+* + sidecar + shared network. Pure compute: to put a local ALB front-door in
+* front of an ALB-fronted service, use `cdkl start-alb`.
+*/
+function createLocalStartServiceCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	return addCommonEcsServiceOptions(new Command("start-service").description(`Run one or more AWS::ECS::Service resources locally as a long-running emulator. Spins up DesiredCount task replicas per service (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as \`${getEmbedConfig().cliName} run-task\`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Each <target> accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix. When two or more <target>s are supplied, every service is booted into a shared Cloud Map / Service Connect registry so peer services discover each other via docker --add-host overlay. Omit <targets> in an interactive terminal to multi-select the services from a list. To put a local ALB front-door in front of an ALB-fronted service, use \`${getEmbedConfig().cliName} start-alb\` instead.`).argument("[targets...]", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ECS::Service resources to run (omit to multi-select interactively in a TTY)").addOption(new Option("--host-port <containerPort=hostPort...>", "Publish a container port on a specific host port (e.g. 80=8080); repeatable. Default: host port == container port. Use this on macOS to map a privileged container port (< 1024) to a non-privileged host port and avoid the Docker Desktop admin-password prompt. (Single-replica services only — multi-replica services do not publish host ports.)")).action(withErrorHandling(async (targets, options) => {
+		await runEcsServiceEmulator(targets, options, serviceStrategy(), opts.extraStateProviders);
+	})));
+}
+
+//#endregion
+//#region src/cli/commands/local-start-alb.ts
+/**
+* Issue #86 v1 — parse `--lb-port <listenerPort>=<hostPort>` overrides into a
+* `listenerPort -> hostPort` map. The local ALB front-door binds the listener
+* port on the host by default, but a privileged listener port (e.g. 80 / 443)
+* fails to bind as non-root on macOS, so the user opts in to a non-privileged
+* host port (e.g. `--lb-port 80=8080`). Repeatable; each value is
+* `<listenerPort>=<hostPort>` with both in 1-65535.
+*/
+function parseLbPortOverrides(values) {
+	const out = {};
+	for (const raw of values ?? []) {
+		const m = /^(\d+)=(\d+)$/.exec(raw.trim());
+		if (!m) throw new LocalStartServiceError(`Invalid --lb-port '${raw}'. Expected <listenerPort>=<hostPort> (e.g. 80=8080).`);
+		const listenerPort = Number(m[1]);
+		const hostPort = Number(m[2]);
+		for (const [label, p] of [["listener", listenerPort], ["host", hostPort]]) if (p < 1 || p > 65535) throw new LocalStartServiceError(`Invalid --lb-port '${raw}': ${label} port must be 1-65535.`);
+		out[listenerPort] = hostPort;
+	}
+	return out;
+}
+/**
+* Resolve an ALB target string (`Stack/Path` display path or `Stack:LogicalId`)
+* to its stack + `AWS::ElasticLoadBalancingV2::LoadBalancer` logical id. Mirrors
+* the ECS service resolver's target grammar.
+*/
+function resolveAlbTarget(target, stacks) {
+	if (stacks.length === 0) throw new LocalStartServiceError("No stacks found in the synthesized assembly.");
+	const parsed = parseEcsTarget(target);
+	const stack = pickStack(parsed.stackPattern, stacks, target);
+	const resources = stack.template.Resources ?? {};
+	if (parsed.isPath) {
+		const index = buildCdkPathIndex(stack.template);
+		const albs = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId }) => {
+			const r = resources[logicalId];
+			return r !== void 0 && isApplicationLoadBalancer(r);
+		});
+		if (albs.length === 0) throw notFound(target, stack, resources);
+		if (albs.length > 1) throw new LocalStartServiceError(`Target '${target}' matches ${albs.length} load balancers in ${stack.stackName}: ${albs.map((a) => a.logicalId).join(", ")}. Refine the path or use the stack:LogicalId form.`);
+		return {
+			stack,
+			albLogicalId: albs[0].logicalId
+		};
+	}
+	const res = resources[parsed.pathOrId];
+	if (!res || !isApplicationLoadBalancer(res)) throw notFound(target, stack, resources);
+	return {
+		stack,
+		albLogicalId: parsed.pathOrId
+	};
+}
+function pickStack(stackPattern, stacks, target) {
+	if (stackPattern === null) {
+		if (stacks.length === 1) return stacks[0];
+		throw new LocalStartServiceError(`Target '${target}' has no stack prefix, and the assembly contains ${stacks.length} stacks: ${stacks.map((s) => s.stackName).join(", ")}. Pass it as 'Stack/Path' or 'Stack:LogicalId'.`);
+	}
+	const matched = matchStacks(stacks, [stackPattern]);
+	if (matched.length === 0) throw new LocalStartServiceError(`No stack matches '${stackPattern}'. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+	if (matched.length > 1) throw new LocalStartServiceError(`Multiple stacks match '${stackPattern}': ${matched.map((s) => s.stackName).join(", ")}. Refine the pattern.`);
+	return matched[0];
+}
+function notFound(target, stack, resources) {
+	const albs = Object.entries(resources).filter(([, r]) => r.Type === "AWS::ElasticLoadBalancingV2::LoadBalancer").map(([logicalId]) => logicalId);
+	const available = albs.length > 0 ? ` Available load balancers in ${stack.stackName}: ${albs.join(", ")}.` : ` ${stack.stackName} declares no AWS::ElasticLoadBalancingV2::LoadBalancer resources.`;
+	return new LocalStartServiceError(`Target '${target}' did not match an application Load Balancer in ${stack.stackName}.${available}`);
+}
+/**
+* `cdkl start-alb` strategy — name the ALB, boot the ECS service(s) behind it,
+* and expose each listener via a local front-door. Mirrors how `start-api`
+* names the API and serves its backing Lambdas.
+*/
+function albStrategy(options) {
+	const lbPortOverrides = parseLbPortOverrides(options.lbPort);
+	return {
+		pickEntries: (stacks) => listTargets(stacks).loadBalancers,
+		pickerMessage: "Select one or more Application Load Balancers to run",
+		pickerNoun: "Application Load Balancers",
+		onMissing: () => new LocalStartServiceError(`${getEmbedConfig().cliName} start-alb requires at least one <target>. Pass one or more ALB paths like 'Stack/MyAlb', or run it in a TTY to pick interactively.`),
+		resolveBoots: (stacks, chosenTargets) => {
+			const warnings = [];
+			const serviceTargets = /* @__PURE__ */ new Set();
+			const listeners = [];
+			const claimedHostPorts = /* @__PURE__ */ new Map();
+			for (const albTarget of chosenTargets) {
+				const { stack, albLogicalId } = resolveAlbTarget(albTarget, stacks);
+				const resolution = resolveAlbFrontDoor(stack, albLogicalId);
+				warnings.push(...resolution.warnings);
+				const qualifyTarget = (t) => {
+					if (t.kind === "lambda") return {
+						kind: "lambda",
+						lambda: resolveLambdaTarget(`${stack.stackName}:${t.lambdaLogicalId}`, stacks),
+						targetGroupArn: `${stack.stackName}:${t.targetGroupLogicalId}`,
+						multiValueHeaders: t.multiValueHeaders,
+						weight: t.weight
+					};
+					const serviceTarget = `${stack.stackName}:${t.serviceLogicalId}`;
+					serviceTargets.add(serviceTarget);
+					return {
+						kind: "ecs",
+						serviceTarget,
+						targetContainerName: t.targetContainerName,
+						targetContainerPort: t.targetContainerPort,
+						weight: t.weight
+					};
+				};
+				const qualify = (action) => {
+					if (action.kind === "forward") return {
+						kind: "forward",
+						targets: action.targets.map(qualifyTarget)
+					};
+					if (action.kind === "redirect") return {
+						kind: "redirect",
+						statusCode: action.statusCode,
+						...action.protocol !== void 0 && { protocol: action.protocol },
+						...action.host !== void 0 && { host: action.host },
+						...action.port !== void 0 && { port: action.port },
+						...action.path !== void 0 && { path: action.path },
+						...action.query !== void 0 && { query: action.query }
+					};
+					return {
+						kind: "fixed-response",
+						statusCode: action.statusCode,
+						...action.contentType !== void 0 && { contentType: action.contentType },
+						...action.messageBody !== void 0 && { messageBody: action.messageBody }
+					};
+				};
+				for (const listener of resolution.listeners) {
+					const hostPort = lbPortOverrides[listener.listenerPort] ?? listener.listenerPort;
+					const claimedBy = claimedHostPorts.get(hostPort);
+					if (claimedBy !== void 0) {
+						warnings.push(`Listener port ${listener.listenerPort} would bind host port ${hostPort}, already claimed by listener port ${claimedBy}; the local front-door fronts only the first. Use --lb-port to remap one of them.`);
+						continue;
+					}
+					claimedHostPorts.set(hostPort, listener.listenerPort);
+					listeners.push({
+						listenerPort: listener.listenerPort,
+						hostPort,
+						protocol: listener.listenerProtocol,
+						...listener.defaultAction ? { defaultAction: qualify(listener.defaultAction) } : {},
+						...listener.defaultAuthGuard ? { defaultAuthGuard: listener.defaultAuthGuard } : {},
+						rules: listener.rules.map((r) => ({
+							priority: r.priority,
+							pathPatterns: r.pathPatterns,
+							hostPatterns: r.hostPatterns,
+							httpHeaderConditions: r.httpHeaderConditions,
+							httpRequestMethods: r.httpRequestMethods,
+							queryStringConditions: r.queryStringConditions,
+							sourceIpCidrs: r.sourceIpCidrs,
+							action: qualify(r.action),
+							...r.authGuard ? { authGuard: r.authGuard } : {}
+						}))
+					});
+				}
+			}
+			const boots = [...serviceTargets].map((target) => ({ target }));
+			const resolvedPorts = new Set(listeners.map((l) => l.listenerPort));
+			for (const portStr of Object.keys(lbPortOverrides)) {
+				const port = Number(portStr);
+				if (!resolvedPorts.has(port)) warnings.push(`--lb-port override for listener port ${port} matched no ALB listener resolved for the named target(s); it was ignored.`);
+			}
+			return {
+				boots,
+				...listeners.length > 0 ? { frontDoor: { listeners } } : {},
+				warnings
+			};
+		},
+		lbPortOverrides
+	};
+}
+/**
+* `cdkl start-alb <Stack/Alb>` — Issue #86 v1. Names an
+* `AWS::ElasticLoadBalancingV2::LoadBalancer`, discovers the ECS service(s)
+* behind its HTTP `forward` listeners, boots their replicas, and stands up a
+* local front-door on each listener port that round-robins across the replicas.
+* The symmetric ALB counterpart of `start-api`.
+*/
+function createLocalStartAlbCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	return addCommonEcsServiceOptions(new Command("start-alb").description("Run an Application Load Balancer locally: name the ALB, and cdk-local boots the ECS service(s) behind its listeners and stands up a local front-door on each listener port that round-robins across the running replicas and routes its listener rules across the backing services — a stable host endpoint, like behind a real load balancer. The symmetric ALB counterpart of `start-api`. Each <target> accepts a CDK display path (MyStack/MyAlb) or stack-qualified logical ID; single-stack apps may omit the stack prefix. Supports HTTP and HTTPS listeners (TLS terminated locally with --tls-cert/--tls-key or an auto-generated self-signed cert); all six ALB rule-condition fields (path-pattern / host-header / http-header / http-request-method / query-string / source-ip); forward (single and weighted), redirect, and fixed-response actions; and ECS or Lambda targets (a Lambda target group is invoked locally via the Lambda RIE). authenticate-cognito / authenticate-oidc actions enforce a local Bearer-JWT check (or AWSELBAuthSessionCookie pass-through) against the same JWKS / OIDC discovery URL the deployed ALB would; use --bearer-token <jwt> to inject a default token or --no-verify-auth to disable the guard. Omit <targets> in an interactive terminal to multi-select the load balancers from a list.").argument("[targets...]", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ElasticLoadBalancingV2::LoadBalancer resources to run (omit to multi-select interactively in a TTY)").addOption(new Option("--lb-port <listenerPort=hostPort...>", "Bind the local front-door on a specific host port (e.g. 80=8080); repeatable. Default: host port == ALB listener port. Use this on macOS to remap a privileged listener port (< 1024) to a non-privileged host port.")).addOption(new Option("--tls-cert <path>", "PEM-encoded server certificate for HTTPS front-door listeners. Must be set together with --tls-key. Omit both flags to auto-generate a self-signed cert (cached under $XDG_CACHE_HOME/cdk-local/alb-https/, default ~/.cache/cdk-local/alb-https/); requires openssl on PATH. The deployed Listener Certificates[] are NOT fetched (ACM private keys are not retrievable by design). The auto-generated cert lists DNS:localhost,IP:127.0.0.1 as SubjectAltName, so a client validating a non-loopback --container-host will fail the SAN check — pass --tls-cert / --tls-key with a SAN covering that host instead.")).addOption(new Option("--tls-key <path>", "PEM-encoded server private key matching --tls-cert. Must be set together with --tls-cert.")).addOption(new Option("--no-verify-auth", "Disable local enforcement of authenticate-cognito / authenticate-oidc actions. Every request is served as if the auth check passed. Useful for local dev where you do not want to mint a Bearer token at all.")).addOption(new Option("--bearer-token <jwt>", "Default Bearer JWT injected as Authorization: Bearer <jwt> when the inbound request has none. Verified against the same JWKS / OIDC discovery URL the deployed ALB would (signature + iss + aud + exp). Local-dev convenience; cookie pass-through (AWSELBAuthSessionCookie-*) also works.")).action(withErrorHandling(async (targets, options) => {
+		await runEcsServiceEmulator(targets, options, albStrategy(options), opts.extraStateProviders);
+	})));
+}
+
+//#endregion
+//#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.").addOption(new Option("-l, --long", "Also print each target's stack-qualified logical ID (<Stack>:<LogicalId>) beneath it").default(false)).action(withErrorHandling(async (options) => {
+		await localListCommand(options);
+	}));
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+
+//#endregion
+export { createLocalRunTaskCommand as a, createLocalStartServiceCommand as i, formatTargetListing as n, createLocalInvokeAgentCoreCommand as o, createLocalStartAlbCommand as r, createLocalInvokeCommand as s, createLocalListCommand as t };
+//# sourceMappingURL=local-list-BPbd4EMs.js.map