cdk-local 0.73.6 → 0.74.0

package/dist/{local-list-DgwUotOK.js → local-list-Dn0Al276.js}

@@ -1,4 +1,4 @@
-import { a as runDockerStreaming, c as getEmbedConfig, i as runDockerForeground, n as formatDockerLoginError, o as spawnStreaming, r as getDockerCmd, s as getLogger, u as setEmbedConfig } from "./docker-cmd-voNPrcRh.js";
+import { a as runDockerStreaming, c as getEmbedConfig, i as runDockerForeground, n as formatDockerLoginError, o as spawnStreaming, r as getDockerCmd, s as getLogger, u as setEmbedConfig } from "./docker-cmd-Dqx2YENO.js";
 import { cpSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import * as path$1 from "node:path";
@@ -6498,7 +6498,10 @@ async function pullImage(image, skipPull) {
 	}
 	logger.debug(`Pulling ${image} (silent — pass --verbose to stream progress)`);
 	try {
-		await runDockerStreaming(["pull", image], { streamLive: false });
+		await runDockerStreaming(["pull", image], {
+			streamLive: false,
+			progressLabel: `Pulling ${image}`
+		});
 	} catch (err) {
 		const e = err;
 		if (e.exitCode === void 0 || e.exitCode === null) throw new DockerRunnerError(`docker pull ${image} failed: ${e.message ?? String(err)}`);
@@ -6773,7 +6776,8 @@ async function buildDockerImage(asset, cdkOutDir, options) {
 	try {
 		await runDockerStreaming(buildArgs, {
 			cwd: contextDir,
-			env: { BUILDX_NO_DEFAULT_ATTESTATIONS: "1" }
+			env: { BUILDX_NO_DEFAULT_ATTESTATIONS: "1" },
+			...options.progressLabel !== void 0 && { progressLabel: options.progressLabel }
 		});
 	} catch (err) {
 		const e = err;
@@ -7080,7 +7084,8 @@ async function buildContainerImage(asset, cdkOutDir, options) {
 	const actualTag = await buildDockerImage(asset, cdkOutDir, {
 		tag,
 		platform,
-		wrapError: (stderr) => new LocalInvokeBuildError(`docker build failed for container Lambda asset (${asset.source.directory ?? asset.source.executable?.join(" ")}): ${stderr}`)
+		wrapError: (stderr) => new LocalInvokeBuildError(`docker build failed for container Lambda asset (${asset.source.directory ?? asset.source.executable?.join(" ")}): ${stderr}`),
+		progressLabel: `Building container image (platform=${platform})`
 	});
 	if (actualTag !== tag) {
 		logger.debug(`Re-tagging executable-built image '${actualTag}' → '${tag}'`);
@@ -15269,7 +15274,8 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 	const appCmd = resolveApp(options.app);
 	if (!appCmd) throw new Error(`No CDK app specified. Pass --app, set ${getEmbedConfig().envPrefix}_APP, or add "app" to cdk.json.`);
 	const overrides = readEnvOverridesFile$4(options.envVars);
-	const debugPortBase = options.debugPortBase ? parseDebugPort(options.debugPortBase) : void 0;
+	const debugPortRaw = options.debugPortBase ?? options.debugPort;
+	const debugPortBase = debugPortRaw ? parseDebugPort(debugPortRaw) : void 0;
 	const perLambdaConcurrency = parsePerLambdaConcurrency(options.perLambdaConcurrency);
 	const inlineTmpDirs = /* @__PURE__ */ new Set();
 	const layerTmpDirs = /* @__PURE__ */ new Set();
@@ -15378,7 +15384,9 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 				layerTmpDirs,
 				stateByStack,
 				skipPull: options.pull === false,
+				skipBuild: options.build === false,
 				...options.profile !== void 0 && { profile: options.profile },
+				...options.ecrRoleArn !== void 0 && { ecrRoleArn: options.ecrRoleArn },
 				...options.layerRoleArn !== void 0 && { layerRoleArn: options.layerRoleArn },
 				...profileCredentials && { profileCredentials },
 				...profileCredsFile && { profileCredsFile },
@@ -16050,7 +16058,11 @@ async function buildContainerSpec(args) {
 		codeDir = lambda.codePath ?? materializeInlineCode$2(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
 		optDir = await materializeLambdaLayers$1(lambda.layers, layerTmpDirs, layerRoleArn);
 	} else {
-		imageRef = (await resolveContainerImageForStartApi(lambda, skipPull, args.profile)).imageRef;
+		imageRef = (await resolveContainerImageForStartApi(lambda, skipPull, args.profile, {
+			...args.skipBuild !== void 0 && { noBuild: args.skipBuild },
+			...args.ecrRoleArn !== void 0 && { ecrRoleArn: args.ecrRoleArn },
+			...args.stsRegion !== void 0 && { region: args.stsRegion }
+		})).imageRef;
 		platform = architectureToPlatform(lambda.architecture);
 	}
 	let templateEnv = getTemplateEnv$1(lambda.resource);
@@ -16171,23 +16183,30 @@ async function buildContainerSpec(args) {
 * Resolve a container Lambda's local docker image — local build from
 * `cdk.out` asset manifest first, ECR-pull fallback when the asset
 * manifest has no matching entry. Mirrors `cdkl invoke`'s
-* `resolveContainerImagePlan` shape; the start-api server doesn't
-* need the no-build flag (deterministic-tag cache reuse is automatic
-* across reloads because the per-Lambda tag is content-addressed).
+* `resolveContainerImagePlan` shape.
 *
-* Same-account / same-region only on the ECR-pull path (matches the
-* `cdkl invoke` PR 5 of #224 boundary). Cross-account /
-* cross-region ECR pull is the W2-1 deferred follow-up.
+* Issue #249 / C7 + C8 — `noBuild` and `ecrRoleArn` are accepted for
+* parity with `cdkl invoke` / `cdkl run-task`. `noBuild` short-circuits
+* the local-asset build path (the deterministic content-addressed tag
+* must already be in the local registry). `ecrRoleArn` lets the
+* ECR-pull fallback authenticate against cross-account / centralized
+* registries via STS AssumeRole — same-account / same-region pulls do
+* not need it.
 */
-async function resolveContainerImageForStartApi(lambda, skipPull, profile) {
+async function resolveContainerImageForStartApi(lambda, skipPull, profile, options) {
 	const logger = getLogger();
 	const localBuild = await resolveLocalBuildPlan$1(lambda);
-	if (localBuild) return { imageRef: await buildContainerImage(localBuild.asset, localBuild.cdkOutDir, { architecture: lambda.architecture }) };
+	if (localBuild) return { imageRef: await buildContainerImage(localBuild.asset, localBuild.cdkOutDir, {
+		architecture: lambda.architecture,
+		...options?.noBuild !== void 0 && { noBuild: options.noBuild }
+	}) };
 	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)...`);
+	logger.info(`No matching cdk.out asset for ${lambda.imageUri}; falling back to ECR pull...`);
 	return { imageRef: await pullEcrImage(lambda.imageUri, {
 		skipPull,
-		...profile !== void 0 && { profile }
+		...profile !== void 0 && { profile },
+		...options?.ecrRoleArn !== void 0 && { ecrRoleArn: options.ecrRoleArn },
+		...options?.region !== void 0 && { region: options.region }
 	}) };
 }
 /**
@@ -16925,7 +16944,7 @@ function createLocalStartApiCommand(opts = {}) {
 * `--help` clusters. Chainable: returns `cmd`.
 */
 function addStartApiSpecificOptions(cmd) {
-	return cmd.addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--all-stacks", "Serve every stack's API in a multi-stack app (each API on its own port) instead of erroring out. Mutually exclusive with a positional target subset, --stack, and an explicit --from-cfn-stack <name>; the bare --from-cfn-stack flag stays compatible (binds each routed stack to its own CFn stack).").default(false)).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when the CDK app's source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <targets...> argument instead. Accepts a SINGLE identifier; for a subset pass multiple positional targets. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).addOption(new Option("--mtls-truststore <path>", `PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj "/CN=${getEmbedConfig().resourceNamePrefix}-ca" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj "/CN=localhost"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj "/CN=client"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...`)).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--strict-sigv4", "Opt-in: DENY AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id — e.g. a federated / Cognito Identity Pool / cross-account signer — OR no local AWS credentials configured) instead of the default warn-and-pass. DEFAULT off: cdk-local warn-and-passes unverifiable IAM requests with a placeholder principalId so local dev exercises app logic without reproducing an auth boundary it cannot fully emulate. OAC-fronted Function URLs always warn-and-pass regardless.").default(false));
+	return cmd.addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--all-stacks", "Serve every stack's API in a multi-stack app (each API on its own port) instead of erroring out. Mutually exclusive with a positional target subset, --stack, and an explicit --from-cfn-stack <name>; the bare --from-cfn-stack flag stays compatible (binds each routed stack to its own CFn stack).").default(false)).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--no-build", "Skip docker build on every container Lambda local-asset build (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("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--debug-port <port>", "Alias of --debug-port-base for parity with `cdkl invoke --debug-port`. Reserves a contiguous --debug-port range (one per Lambda) starting at <port>.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries on the container-Lambda ECR-pull fallback. 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("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when the CDK app's source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <targets...> argument instead. Accepts a SINGLE identifier; for a subset pass multiple positional targets. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).addOption(new Option("--mtls-truststore <path>", `PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj "/CN=${getEmbedConfig().resourceNamePrefix}-ca" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj "/CN=localhost"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj "/CN=client"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...`)).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--strict-sigv4", "Opt-in: DENY AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id — e.g. a federated / Cognito Identity Pool / cross-account signer — OR no local AWS credentials configured) instead of the default warn-and-pass. DEFAULT off: cdk-local warn-and-passes unverifiable IAM requests with a placeholder principalId so local dev exercises app logic without reproducing an auth boundary it cannot fully emulate. OAC-fronted Function URLs always warn-and-pass regardless.").default(false));
 }
 
 //#endregion
@@ -17554,7 +17573,7 @@ function createLocalInvokeCommand(opts = {}) {
 * `--help` clusters. Chainable: returns `cmd`.
 */
 function addInvokeSpecificOptions(cmd) {
-	return cmd.addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull. Semantics differ by code path: ZIP Lambdas skip pulling the public Lambda base image; Container Lambdas on the local-build path are a no-op (docker build does not refresh the FROM cache by default); Container Lambdas on the ECR-pull fallback skip docker pull AND error if the image is not in the local cache (re-run without --no-pull or pre-pull manually).")).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."));
+	return cmd.addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--no-pull", "Skip docker pull. Semantics differ by code path: ZIP Lambdas skip pulling the public Lambda base image; Container Lambdas on the local-build path are a no-op (docker build does not refresh the FROM cache by default); Container Lambdas on the ECR-pull fallback skip docker pull AND error if the image is not in the local cache (re-run without --no-pull or pre-pull manually).")).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 IP the host uses to bind the RIE port to. Must be a numeric IP (Docker rejects hostnames here). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from state (requires an active state source); (3) `--no-assume-role` explicitly opts out. Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers. Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name; pass an explicit value when CFn stack name differs. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
 }
 
 //#endregion
@@ -17616,7 +17635,7 @@ async function buildAgentCoreCodeImage(options) {
 			"--file",
 			dockerfilePath,
 			options.sourceDir
-		]);
+		], { progressLabel: `Building agent image (runtime=${options.runtime})` });
 	} catch (err) {
 		const stderr = err.stderr?.trim();
 		throw new LocalInvokeBuildError(`docker build failed for AgentCore code artifact (${options.sourceDir})${stderr ? `: ${stderr}` : ""}`);
@@ -19219,7 +19238,7 @@ function createLocalInvokeAgentCoreCommand(opts = {}) {
 * in three `--help` clusters. Chainable: returns `cmd`.
 */
 function addInvokeAgentCoreSpecificOptions(cmd) {
-	return cmd.addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--session-id <id>", "AgentCore runtime session id header value (default: a random UUID)")).addOption(new Option("--ws", "Stream over the HTTP-protocol agent's bidirectional /ws WebSocket endpoint (on 8080) instead of POST /invocations: send --event as the first frame and print every received frame to stdout until the agent closes. Ignored for an MCP runtime.").default(false)).addOption(new Option("--ws-interactive", "REPL mode for --ws: after the initial --event frame, read additional frames from stdin (one frame per line, trailing newline stripped) and send each as a text frame until stdin EOFs (Ctrl-D) or the agent closes. Only meaningful with --ws.").default(false)).addOption(new Option("--bearer-token <jwt>", "Bearer JWT to present when the runtime declares a customJwtAuthorizer. Verified against the runtime OIDC discovery URL (signature / issuer / expiry / audience) before the container starts, then forwarded to /invocations as Authorization: Bearer <jwt>.")).addOption(new Option("--no-verify-auth", "Skip inbound JWT verification even when the runtime declares a customJwtAuthorizer (local-dev escape hatch). A --bearer-token, if given, is still forwarded.")).addOption(new Option("--sigv4", "Sign the /invocations POST with AWS SigV4 (service bedrock-agentcore) using the resolved credentials, matching the cloud default when the runtime declares no customJwtAuthorizer. Opt-in: default unsigned. Mutually exclusive with --bearer-token; ignored on a JWT-protected runtime.").default(false)).addOption(new Option("--platform <platform>", "docker --platform for the agent container (linux/amd64 or linux/arm64)").choices(["linux/amd64", "linux/arm64"]).default("linux/arm64")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for the local-build path")).addOption(new Option("--no-build", "Skip docker build on the local-asset path (use the previously-built tag). No-op for the ECR / registry pull paths.")).addOption(new Option("--container-host <host>", "Host to bind the agent port to").default("127.0.0.1")).addOption(new Option("--timeout <ms>", "Per-request timeout in milliseconds. Applied to POST /invocations, POST /mcp, and the /ws open-to-close window. Raise this for long-running agent calls that exceed the default.").default(12e4).argParser(parseTimeoutMs)).addOption(new Option("--assume-role [arn]", "Assume the runtime's execution role and forward STS-issued temp credentials to the container so the agent runs with the deployed role. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) uses the runtime's RoleArn when it is a literal ARN; (3) `--no-assume-role` opts out. Off by default — the developer's shell credentials are forwarded unchanged.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. Bare form uses the resolved stack name; pass an explicit value when the CFn stack name differs.")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
+	return cmd.addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).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 this command SUPPLIES (the supplier role) when the runtime declares a customJwtAuthorizer — `cdkl invoke-agentcore` is the local-dev client making the outbound call, so it always presents this token to its own invocation. Verified against the runtime's OIDC discovery URL (signature / issuer / expiry / audience) before the container starts, then forwarded to /invocations as Authorization: Bearer <jwt>. Contrast with `cdkl start-alb --bearer-token`, where the role is reversed — the ALB front-door RECEIVES inbound requests and injects this token only as a default when an inbound request has none (default-when-missing).")).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). Defaults to linux/arm64 because the cloud AgentCore Runtime requires arm64. Override to linux/amd64 only when iterating against an amd64 dev container locally; note the image will not run on the cloud runtime as-is.").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 IP the host uses to bind the agent port to. Must be a numeric IP (Docker rejects hostnames here). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--timeout <ms>", "Per-request timeout in milliseconds. Applied to POST /invocations, POST /mcp, and the /ws open-to-close window. Raise this for long-running agent calls that exceed the default.").default(12e4).argParser(parseTimeoutMs)).addOption(new Option("--assume-role [arn]", "Assume the runtime's execution role and forward STS-issued temp credentials to the container so the agent runs with the deployed role. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) uses the runtime's RoleArn when it is a literal ARN; (3) `--no-assume-role` opts out. Off by default — the developer's shell credentials are forwarded unchanged.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. Bare form uses the resolved stack name; pass an explicit value when the CFn stack name differs.")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
 }
 
 //#endregion
@@ -20130,10 +20149,19 @@ async function prepareOneImage(task, container, options) {
 			else if (entries.length === 1) asset = entries[0][1];
 			if (!asset) throw new EcsTaskRunnerError(`Container '${container.name}' references a CDK asset image but no matching entry was found in cdk.out. Re-synthesize the CDK app and retry.`);
 			const tag = `${getEmbedConfig().resourceNamePrefix}-run-task-${(image.assetHash ?? "single").slice(0, 16)}`;
+			if (options.skipBuild === true) {
+				const logger = getLogger().child("ecs-runner");
+				if (image.assetHash === void 0) throw new LocalInvokeBuildError(`Cannot honor --no-build for ECS container '${container.name}': the asset has no stable assetHash (synthetic tag '${tag}' may collide with unrelated prior runs). Drop --no-build, or re-synthesize with an explicit assetHash on the ContainerImage.fromAsset call.`);
+				logger.info(`Skipping docker build (--no-build) for container '${container.name}'; verifying ${tag} is in local registry...`);
+				if (!await isImageInLocalCache(tag)) throw new LocalInvokeBuildError(`image '${tag}' not in local registry and --no-build is set (ECS container '${container.name}'); remove --no-build or run \`docker build\` manually first.`);
+				logger.debug(`Local tag ${tag} is cached; skipping build for container '${container.name}'.`);
+				return tag;
+			}
 			const actualTag = await buildDockerImage(asset, cdkOutDir, {
 				tag,
 				...options.platformOverride !== void 0 && { platform: options.platformOverride },
-				wrapError: (stderr) => new LocalInvokeBuildError(`docker build failed for ECS container '${container.name}' (${asset.source.directory ?? asset.source.executable?.join(" ")}): ${stderr}`)
+				wrapError: (stderr) => new LocalInvokeBuildError(`docker build failed for ECS container '${container.name}' (${asset.source.directory ?? asset.source.executable?.join(" ")}): ${stderr}`),
+				progressLabel: `Building container image for '${container.name}'`
 			});
 			if (actualTag !== tag) try {
 				await runDockerStreaming([
@@ -20356,419 +20384,85 @@ function shellJoin(parts) {
 }
 
 //#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");
-	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,
-			profile: options.profile
-		});
-		await ensureDockerAvailable();
-		const appCmd = resolveApp(options.app);
-		if (!appCmd) throw new Error(`No CDK app specified. Pass --app, set ${getEmbedConfig().envPrefix}_APP, or add "app" to cdk.json.`);
-		logger.info("Synthesizing CDK app...");
-		const synthesizer = new Synthesizer();
-		const context = parseContextOptions(options.context);
-		const synthOpts = {
-			app: appCmd,
-			output: options.output,
-			...options.region && { region: options.region },
-			...options.profile && { profile: options.profile },
-			...Object.keys(context).length > 0 && { context }
-		};
-		const { stacks } = await synthesizer.synthesize(synthOpts);
-		const resolvedTarget = await resolveSingleTarget(target, {
-			entries: listTargets(stacks).ecsTaskDefinitions,
-			message: "Select an ECS task definition to run",
-			noun: "ECS task definitions",
-			onMissing: () => new CdkLocalError(`${getEmbedConfig().cliName} run-task requires a <target> (an ECS task definition display path or logical ID). Run \`${getEmbedConfig().cliName} list\` to see them, or run it in a TTY to pick interactively.`, "LOCAL_RUN_TASK_TARGET_REQUIRED")
-		});
-		const candidate = pickCandidateStack$1(parseEcsTarget(resolvedTarget).stackPattern, stacks);
-		stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
-		const imageContext = await buildEcsImageResolutionContext$1(candidate, stateProvider, options);
-		const task = resolveEcsTaskTarget(resolvedTarget, stacks, imageContext);
-		logger.info(`Target: ${task.stack.stackName}/${task.taskDefinitionLogicalId} (family=${task.family}, containers=${task.containers.length})`);
-		const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === task.stack.stackName) ?? task.stack);
-		if (stateProvider && taskNeeds.needsCrossStackResolver) {
-			const consumerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? task.stack.region ?? "us-east-1";
-			const resolver = await stateProvider.buildCrossStackResolver(consumerRegion);
-			if (resolver) await applyCrossStackResolverToTask(task, {
-				resources: imageContext?.stateResources ?? {},
-				...imageContext?.pseudoParameters && { pseudoParameters: imageContext.pseudoParameters },
-				...imageContext?.stateParameters && { parameters: imageContext.stateParameters },
-				...imageContext?.stateSensitiveParameters?.length && { sensitiveParameters: new Set(imageContext.stateSensitiveParameters) },
-				consumerRegion,
-				crossStackResolver: resolver
-			});
-		} else if (!stateProvider && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to substitute them against deployed state.");
-		sigintHandler = () => {
-			sigintCount += 1;
-			if (sigintCount >= 2) {
-				process.stderr.write("Force-exit on second ^C; container cleanup skipped.\n");
-				process.exit(130);
-			}
-			logger.info("Stopping task...");
-			cleanup().then(() => process.exit(130));
-		};
-		process.on("SIGINT", sigintHandler);
-		let assumedCredentials;
-		let resolvedRoleArn;
-		if (options.assumeTaskRole === true) {
-			if (!task.taskRoleArn) throw new Error(`--assume-task-role passed without an ARN but the task definition has no resolvable TaskRoleArn. Either the task definition does not set TaskRoleArn, or it points at a resource ${getEmbedConfig().binaryName} cannot resolve to an IAM Role at synth time. Pass the ARN explicitly: --assume-task-role <arn>`);
-			resolvedRoleArn = await resolvePlaceholderAccount$1(task.taskRoleArn, options.region, options.profile);
-			assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region, options.profile);
-		} else if (typeof options.assumeTaskRole === "string") {
-			resolvedRoleArn = options.assumeTaskRole;
-			assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region, options.profile);
-		}
-		const sidecarCredentials = await resolveSidecarCredentials(options, assumedCredentials);
-		if (options.profile && sidecarCredentials && !assumedCredentials) profileCredsFile = await writeProfileCredentialsFile(options.profile, sidecarCredentials);
-		const envOverrides = readEnvOverridesFile$1(options.envVars);
-		const runOpts = {
-			cluster: options.cluster,
-			containerHost: options.containerHost,
-			skipPull: options.pull === false,
-			keepRunning: options.keepRunning,
-			detach: options.detach
-		};
-		if (envOverrides) runOpts.envOverrides = envOverrides;
-		if (sidecarCredentials) runOpts.taskCredentials = sidecarCredentials;
-		if (resolvedRoleArn) runOpts.taskRoleArn = resolvedRoleArn;
-		if (options.platform) runOpts.platformOverride = options.platform;
-		if (options.region) runOpts.region = options.region;
-		if (options.ecrRoleArn) runOpts.ecrRoleArn = options.ecrRoleArn;
-		if (options.profile) runOpts.profile = options.profile;
-		const hostPortOverrides = parseHostPortOverrides(options.hostPort);
-		if (Object.keys(hostPortOverrides).length > 0) runOpts.hostPortOverrides = hostPortOverrides;
-		if (profileCredsFile) runOpts.profileCredentialsFile = {
-			hostPath: profileCredsFile.hostPath,
-			containerPath: profileCredsFile.containerPath,
-			profileName: profileCredsFile.profileName
-		};
-		const result = await runEcsTask(task, runOpts, state);
-		if (options.detach) {
-			logger.info(`Task containers started in detached mode; ${getEmbedConfig().binaryName} is exiting.`);
-			logger.info(`Use 'docker ps --filter network=${result.state.network?.networkName ?? "<network>"}' to inspect; tear down with 'docker rm -f' and 'docker network rm'.`);
-			sigintCount = 99;
-			return;
-		}
-		if (result.essentialContainerName) logger.info(`Essential container '${result.essentialContainerName}' exited with code ${result.exitCode}.`);
-		if (result.exitCode !== 0) process.exitCode = result.exitCode;
-	} finally {
-		if (sigintHandler) process.off("SIGINT", sigintHandler);
-		if (stateProvider) stateProvider.dispose();
-		if (!options.detach) await cleanup();
-	}
-}
-/**
-* If `arn` contains the `${AWS::AccountId}` placeholder emitted by the
-* resolver for inline same-stack IAM Roles, substitute the live caller
-* account via STS `GetCallerIdentity`. Otherwise pass through unchanged.
-*/
-async function resolvePlaceholderAccount$1(arn, region, profile) {
-	if (!arn.includes("${AWS::AccountId}")) return arn;
-	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
-	const sts = new STSClient(buildStsClientConfig({
-		region,
-		profile
-	}));
-	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();
+//#region src/local/ecs-service-resolver.ts
+function resolveEcsServiceTarget(target, stacks, context, options) {
+	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
+	const parsed = parseEcsTarget(target);
+	const stack = pickStack$1(parsed, stacks);
+	const resources = stack.template.Resources ?? {};
+	let serviceLogicalId;
+	let serviceResource;
+	if (parsed.isPath) {
+		const index = buildCdkPathIndex(stack.template);
+		const services = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId: l }) => resources[l]?.Type === "AWS::ECS::Service");
+		if (services.length === 0) throw notFoundError(target, stack, resources, parsed);
+		if (services.length > 1) throw new EcsTaskResolutionError(`Target '${target}' matches ${services.length} ECS services in ${stack.stackName}: ` + services.map((s) => s.logicalId).join(", ") + ". Refine the path or use the stack:LogicalId form.");
+		serviceLogicalId = services[0].logicalId;
+		serviceResource = resources[serviceLogicalId];
+	} else {
+		serviceResource = resources[parsed.pathOrId];
+		if (!serviceResource) throw notFoundError(target, stack, resources, parsed);
+		serviceLogicalId = parsed.pathOrId;
 	}
+	if (!serviceLogicalId || !serviceResource) throw notFoundError(target, stack, resources, parsed);
+	if (serviceResource.Type === "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is an ECS TaskDefinition, not a Service. Use \`${getEmbedConfig().cliName} run-task\` for one-shot tasks; \`${getEmbedConfig().cliName} start-service\` is Service-only.`);
+	if (serviceResource.Type !== "AWS::ECS::Service") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is ${serviceResource.Type}, not an AWS::ECS::Service.`);
+	return extractServiceProperties(stack, serviceLogicalId, serviceResource, stacks, context, options);
 }
 /**
-* Assume `roleArn` and return temp credentials.
+* Pure-functional extraction from the synth resource. Exposed for unit
+* testing the per-field resolution rules (DesiredCount default, missing
+* TaskDefinition, intrinsic shapes).
 */
-async function assumeTaskRole$1(roleArn, region, profile) {
-	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
-	const sts = new STSClient(buildStsClientConfig({
-		region,
-		profile
-	}));
-	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();
+function extractServiceProperties(stack, serviceLogicalId, resource, stacks, context, options) {
+	const props = resource.Properties ?? {};
+	const warnings = [];
+	const taskDefRef = props["TaskDefinition"];
+	if (taskDefRef === void 0 || taskDefRef === null) throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' in ${stack.stackName} has no TaskDefinition property.`);
+	const taskDefLogicalId = resolveTaskDefinitionReference(taskDefRef, stack, serviceLogicalId);
+	const task = resolveEcsTaskTarget(`${stack.stackName}:${taskDefLogicalId}`, stacks, context);
+	const desiredCount = parseDesiredCount(props["DesiredCount"], serviceLogicalId);
+	const healthCheckGracePeriodSeconds = parseHealthCheckGrace(props["HealthCheckGracePeriodSeconds"], serviceLogicalId);
+	const serviceName = parseServiceName(props["ServiceName"], serviceLogicalId);
+	const serviceDisplayName = deriveServiceDisplayName(props["ServiceName"], serviceLogicalId, resource.Metadata);
+	if (!options?.suppressLoadBalancerWarning && Array.isArray(props["LoadBalancers"]) && props["LoadBalancers"].length > 0) {
+		const { cliName } = getEmbedConfig();
+		warnings.push(`ECS Service '${serviceLogicalId}' declares LoadBalancers, but \`${cliName} start-service\` runs the replicas only; no local listener fronts them. Reach the containers via their published ports, or run \`${cliName} start-alb <Stack>/<Alb>\` to boot the same replicas behind a local front-door that round-robins the listener rules.`);
 	}
+	const serviceConnect = extractServiceConnect(props["ServiceConnectConfiguration"], task);
+	const out = {
+		stack,
+		serviceLogicalId,
+		resource,
+		serviceName,
+		serviceDisplayName,
+		desiredCount,
+		healthCheckGracePeriodSeconds,
+		task,
+		serviceRegistries: extractServiceRegistries(props["ServiceRegistries"], serviceLogicalId, warnings),
+		warnings
+	};
+	if (serviceConnect) out.serviceConnect = serviceConnect;
+	return out;
 }
 /**
-* Build the substitution context the ECS task resolver consumes.
-* Returns `undefined` when no container's `Image` field needs
-* substitution — the resolver behaves as before in that case.
-*/
-async function buildEcsImageResolutionContext$1(candidate, stateProvider, options) {
-	const logger = getLogger();
-	if (!candidate) return void 0;
-	const needs = detectEcsImageResolutionNeeds(candidate);
-	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
-	const ctx = {};
-	const wantsPseudoForEnvOrSecret = !!stateProvider && needs.needsEnvOrSecretSubstitution;
-	if (needs.needsPseudoParameters || wantsPseudoForEnvOrSecret) {
-		const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
-		if (!region) logger.warn(`Resolver references \${AWS::Region} but ${getEmbedConfig().binaryName} could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.`);
-		let accountId;
-		try {
-			accountId = await resolveCallerAccountId$1(region, options.profile);
-		} catch (err) {
-			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
-		}
-		const partitionAndSuffix = region ? derivePartitionAndUrlSuffix(region) : void 0;
-		ctx.pseudoParameters = {
-			...accountId !== void 0 && { accountId },
-			...region !== void 0 && { region },
-			...partitionAndSuffix && {
-				partition: partitionAndSuffix.partition,
-				urlSuffix: partitionAndSuffix.urlSuffix
-			}
-		};
-	}
-	const wantsState = needs.needsStateResources || needs.needsEnvOrSecretSubstitution;
-	if (stateProvider && wantsState) {
-		const loaded = await stateProvider.load(candidate.stackName, candidate.region);
-		if (loaded) ctx.stateResources = loaded.resources;
-		else {
-			const loadError = stateProvider.getLastLoadError?.();
-			if (loadError) ctx.stateLoadFailureMessage = loadError;
-		}
-		if (needs.needsEnvOrSecretSubstitution && stateProvider.resolveTemplateSsmParameters) {
-			const ssmParameters = await stateProvider.resolveTemplateSsmParameters(candidate.template);
-			if (Object.keys(ssmParameters.values).length > 0) ctx.stateParameters = ssmParameters.values;
-			if (ssmParameters.secureStringLogicalIds.length > 0) ctx.stateSensitiveParameters = ssmParameters.secureStringLogicalIds;
-		}
-	} else if (!stateProvider && needs.needsStateResources) logger.warn("Container Image references a same-stack AWS::ECR::Repository. Pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to substitute the deployed repository URI. Otherwise the resolver will surface its existing error.");
-	else if (!stateProvider && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics (Ref / Fn::GetAtt / Fn::Sub / Fn::Join). Pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to substitute them against deployed state. Without a state source these entries are dropped (per-key warnings will follow).");
-	return ctx;
-}
-function pickCandidateStack$1(stackPattern, stacks) {
-	if (stackPattern === null) {
-		if (stacks.length === 1) return stacks[0];
-		return;
-	}
-	const matched = matchStacks(stacks, [stackPattern]);
-	if (matched.length === 1) return matched[0];
-}
-async function resolveCallerAccountId$1(region, profile) {
-	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
-	const sts = new STSClient(buildStsClientConfig({
-		region,
-		profile
-	}));
-	try {
-		return (await sts.send(new GetCallerIdentityCommand({}))).Account;
-	} finally {
-		sts.destroy();
-	}
-}
-/**
-* Read the `--env-vars` JSON file using the same SAM-style shape as
-* `cdkl invoke --env-vars`: top-level keys are container names, with
-* `Parameters` reserved for global entries.
-*/
-function readEnvOverridesFile$1(filePath) {
-	if (!filePath) return void 0;
-	let raw;
-	try {
-		raw = readFileSync(filePath, "utf-8");
-	} catch (err) {
-		throw new Error(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
-	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (err) {
-		throw new Error(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`);
-	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`--env-vars file '${filePath}' must contain a JSON object at the top level.`);
-	return parsed;
-}
-/**
-* Pick the credentials forwarded to the AWS-published
-* `amazon-ecs-local-container-endpoints` sidecar. Precedence:
-*   1. `--assume-task-role <arn>` (or bare `--assume-task-role` against
-*      a resolvable `TaskRoleArn`) → STS-assumed temp creds. Highest
-*      priority — when the user opted in to IAM emulation, those creds
-*      drive the sidecar regardless of `--profile`.
-*   2. `--profile <p>` → resolved via {@link resolveProfileCredentials}
-*      (the SDK's default credential provider chain — SSO / IAM
-*      Identity Center / fromIni / role-assumption). NEW in this PR.
-*   3. Neither set → `undefined`; the sidecar runs with its own
-*      default credential chain (typically empty inside a fresh
-*      container — user containers will get 4xx from the credentials
-*      endpoint, mimicking IAM-misconfigured prod).
-*
-* Extracted as an exported helper so a unit test can exercise every
-* branch without having to mock the full Synth + Docker + AWS pipeline
-* (the strategy used for the Lambda container path).
-*/
-async function resolveSidecarCredentials(options, assumedCredentials) {
-	if (assumedCredentials) return assumedCredentials;
-	if (options.profile) return resolveProfileCredentials(options.profile);
-}
-function createLocalRunTaskCommand(opts = {}) {
-	setEmbedConfig(opts.embedConfig);
-	const cmd = new Command("run-task").description("Run an AWS::ECS::TaskDefinition locally — pulls/builds images, sets up a per-task docker network with the AWS-published metadata-endpoints sidecar, and starts every container in dependsOn order. Target accepts a CDK display path (MyStack/MyService/TaskDef) or stack-qualified logical ID (MyStack:MyServiceTaskDefXYZ1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick the task definition from a list.").argument("[target]", "CDK display path or stack-qualified logical ID of the AWS::ECS::TaskDefinition to run (omit to pick interactively in a TTY)").action(withErrorHandling(async (target, options) => {
-		await localRunTaskCommand(target, options, opts.extraStateProviders);
-	}));
-	addRunTaskSpecificOptions(cmd);
-	[
-		...commonOptions(),
-		...appOptions(),
-		...contextOptions
-	].forEach((opt) => cmd.addOption(opt));
-	cmd.addOption(regionOption);
-	return cmd;
-}
-/**
-* Register the option block that `cdkl run-task` adds on top of the shared
-* common / app / context option helpers. Shared between `cdkl run-task` and
-* any host CLI (e.g. cdkd's `local run-task`) that wraps the single-task
-* ECS local runner, so adding or renaming a `run-task`-only flag here
-* propagates to every embedder without duplicate `.addOption(...)` blocks.
-*
-* Calling order only affects `--help` presentation (Commander parses
-* insertion-order-independent). The host-CLI convention is host-specific
-* options first, then this helper, then the shared common / app / context
-* options — host flags / run-task flags / common flags grouped in three
-* `--help` clusters. Chainable: returns `cmd`.
-*
-* NOTE: `run-task` does NOT compose with {@link addCommonEcsServiceOptions}
-* even though many flags overlap. The two ECS surfaces (single-task vs
-* multi-replica service) have intentionally divergent defaults
-* (`run-task` has no `--max-tasks` / `--restart-policy`; `start-service`
-* / `start-alb` have no `--host-port` / `--keep-running` / `--detach`),
-* and folding `run-task` into the service common block would mutate the
-* surface non-trivially. Each command keeps its own helper.
-*/
-function addRunTaskSpecificOptions(cmd) {
-	return cmd.addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default(getEmbedConfig().resourceNamePrefix)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--host-port <containerPort=hostPort...>", "Publish a container port on a specific host port (e.g. 80=8080); repeatable. Default: host port == container port. Use this on macOS to map a privileged container port (< 1024) to a non-privileged host port and avoid the Docker Desktop admin-password prompt.")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed function role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--keep-running", "Don't docker rm -f the user containers on task exit (network + sidecar are still torn down). Use when you want to docker exec into a stopped container for post-mortems.").default(false)).addOption(new Option("--detach", "Start the containers in the background and exit (skip log streaming + auto teardown). Useful in CI smoke tests; caller manages container lifecycle.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", `Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in container env vars / secrets / image URIs with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (\`cdk deploy\`). Bare form uses the ${getEmbedConfig().binaryName} stack name; pass an explicit value when the CFn stack name differs. Fn::GetAtt in container Environment[].Value is warn-and-dropped: CFn ListStackResources does not return per-attribute values, and unlike Lambda (where \`cdkl invoke --from-cfn-stack\` recovers Fn::GetAtt from the deployed function via lambda:GetFunctionConfiguration), no ECS-side equivalent resolves attributes off a deployed task / service.`)).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
-}
-
-//#endregion
-//#region src/local/ecs-service-resolver.ts
-function resolveEcsServiceTarget(target, stacks, context, options) {
-	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
-	const parsed = parseEcsTarget(target);
-	const stack = pickStack$1(parsed, stacks);
-	const resources = stack.template.Resources ?? {};
-	let serviceLogicalId;
-	let serviceResource;
-	if (parsed.isPath) {
-		const index = buildCdkPathIndex(stack.template);
-		const services = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId: l }) => resources[l]?.Type === "AWS::ECS::Service");
-		if (services.length === 0) throw notFoundError(target, stack, resources, parsed);
-		if (services.length > 1) throw new EcsTaskResolutionError(`Target '${target}' matches ${services.length} ECS services in ${stack.stackName}: ` + services.map((s) => s.logicalId).join(", ") + ". Refine the path or use the stack:LogicalId form.");
-		serviceLogicalId = services[0].logicalId;
-		serviceResource = resources[serviceLogicalId];
-	} else {
-		serviceResource = resources[parsed.pathOrId];
-		if (!serviceResource) throw notFoundError(target, stack, resources, parsed);
-		serviceLogicalId = parsed.pathOrId;
-	}
-	if (!serviceLogicalId || !serviceResource) throw notFoundError(target, stack, resources, parsed);
-	if (serviceResource.Type === "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is an ECS TaskDefinition, not a Service. Use \`${getEmbedConfig().cliName} run-task\` for one-shot tasks; \`${getEmbedConfig().cliName} start-service\` is Service-only.`);
-	if (serviceResource.Type !== "AWS::ECS::Service") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is ${serviceResource.Type}, not an AWS::ECS::Service.`);
-	return extractServiceProperties(stack, serviceLogicalId, serviceResource, stacks, context, options);
-}
-/**
-* Pure-functional extraction from the synth resource. Exposed for unit
-* testing the per-field resolution rules (DesiredCount default, missing
-* TaskDefinition, intrinsic shapes).
-*/
-function extractServiceProperties(stack, serviceLogicalId, resource, stacks, context, options) {
-	const props = resource.Properties ?? {};
-	const warnings = [];
-	const taskDefRef = props["TaskDefinition"];
-	if (taskDefRef === void 0 || taskDefRef === null) throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' in ${stack.stackName} has no TaskDefinition property.`);
-	const taskDefLogicalId = resolveTaskDefinitionReference(taskDefRef, stack, serviceLogicalId);
-	const task = resolveEcsTaskTarget(`${stack.stackName}:${taskDefLogicalId}`, stacks, context);
-	const desiredCount = parseDesiredCount(props["DesiredCount"], serviceLogicalId);
-	const healthCheckGracePeriodSeconds = parseHealthCheckGrace(props["HealthCheckGracePeriodSeconds"], serviceLogicalId);
-	const serviceName = parseServiceName(props["ServiceName"], serviceLogicalId);
-	const serviceDisplayName = deriveServiceDisplayName(props["ServiceName"], serviceLogicalId, resource.Metadata);
-	if (!options?.suppressLoadBalancerWarning && Array.isArray(props["LoadBalancers"]) && props["LoadBalancers"].length > 0) {
-		const { cliName } = getEmbedConfig();
-		warnings.push(`ECS Service '${serviceLogicalId}' declares LoadBalancers, but \`${cliName} start-service\` runs the replicas only; no local listener fronts them. Reach the containers via their published ports, or run \`${cliName} start-alb <Stack>/<Alb>\` to boot the same replicas behind a local front-door that round-robins the listener rules.`);
-	}
-	const serviceConnect = extractServiceConnect(props["ServiceConnectConfiguration"], task);
-	const out = {
-		stack,
-		serviceLogicalId,
-		resource,
-		serviceName,
-		serviceDisplayName,
-		desiredCount,
-		healthCheckGracePeriodSeconds,
-		task,
-		serviceRegistries: extractServiceRegistries(props["ServiceRegistries"], serviceLogicalId, warnings),
-		warnings
-	};
-	if (serviceConnect) out.serviceConnect = serviceConnect;
-	return out;
-}
-/**
-* Parse `ServiceConnectConfiguration` against the producer TaskDef.
-* Returns `undefined` when the block is missing OR `Enabled: false`.
-*
-* Reject conditions (surface as resolver-time errors so the user sees
-* them BEFORE the docker network is created):
-*   - `Namespace` is not a literal string. CDK 2.x always emits a
-*     literal string here (verified 2026-05-22); cross-stack /
-*     intrinsic shapes are out of scope.
-*   - `Services[].PortName` doesn't match any of the TaskDef's
-*     `ContainerDefinitions[].PortMappings[].Name` entries.
-*
-* Note on `clientAliases[]` shape: each ClientAlias can declare a
-* `DnsName` (the bare short-name peers connect to, e.g. `orders`) AND
-* a `Port` (the listening port the alias maps to inside the consumer).
-* cdk-local surfaces both verbatim; the registry / `--add-host` overlay
-* publishes each `DnsName` as a bare alias pointing at the same IP as
-* the canonical fqdn.
+* Parse `ServiceConnectConfiguration` against the producer TaskDef.
+* Returns `undefined` when the block is missing OR `Enabled: false`.
+*
+* Reject conditions (surface as resolver-time errors so the user sees
+* them BEFORE the docker network is created):
+*   - `Namespace` is not a literal string. CDK 2.x always emits a
+*     literal string here (verified 2026-05-22); cross-stack /
+*     intrinsic shapes are out of scope.
+*   - `Services[].PortName` doesn't match any of the TaskDef's
+*     `ContainerDefinitions[].PortMappings[].Name` entries.
+*
+* Note on `clientAliases[]` shape: each ClientAlias can declare a
+* `DnsName` (the bare short-name peers connect to, e.g. `orders`) AND
+* a `Port` (the listening port the alias maps to inside the consumer).
+* cdk-local surfaces both verbatim; the registry / `--add-host` overlay
+* publishes each `DnsName` as a bare alias pointing at the same IP as
+* the canonical fqdn.
 */
 function extractServiceConnect(raw, task) {
 	if (!raw || typeof raw !== "object") return void 0;
@@ -21846,7 +21540,7 @@ async function softReloadReplica(args) {
 const defaultDockerInspectWorkdirImpl = async (containerId) => {
 	const { execFile } = await import("node:child_process");
 	const { promisify } = await import("node:util");
-	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	const { getDockerCmd } = await import("./docker-cmd-Dqx2YENO.js").then((n) => n.t);
 	const { stdout } = await promisify(execFile)(getDockerCmd(), [
 		"inspect",
 		"--format",
@@ -21865,7 +21559,7 @@ let dockerInspectWorkdirImpl = defaultDockerInspectWorkdirImpl;
 const defaultDockerCpImpl = async (src, dst) => {
 	const { execFile } = await import("node:child_process");
 	const { promisify } = await import("node:util");
-	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	const { getDockerCmd } = await import("./docker-cmd-Dqx2YENO.js").then((n) => n.t);
 	await promisify(execFile)(getDockerCmd(), [
 		"cp",
 		src,
@@ -21880,7 +21574,7 @@ let dockerCpImpl = defaultDockerCpImpl;
 const defaultDockerRestartImpl = async (containerId) => {
 	const { execFile } = await import("node:child_process");
 	const { promisify } = await import("node:util");
-	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	const { getDockerCmd } = await import("./docker-cmd-Dqx2YENO.js").then((n) => n.t);
 	await promisify(execFile)(getDockerCmd(), ["restart", containerId]);
 };
 let dockerRestartImpl = defaultDockerRestartImpl;
@@ -21920,7 +21614,7 @@ async function disconnectOldFromSharedNetwork(oldInstance) {
 const defaultDockerNetworkDisconnectImpl = async (networkName, containerId) => {
 	const { execFile } = await import("node:child_process");
 	const { promisify } = await import("node:util");
-	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	const { getDockerCmd } = await import("./docker-cmd-Dqx2YENO.js").then((n) => n.t);
 	await promisify(execFile)(getDockerCmd(), [
 		"network",
 		"disconnect",
@@ -22097,7 +21791,7 @@ function pickEssentialContainerId(instance, service) {
 const defaultWaitForExitImpl = async (containerId) => {
 	const { execFile } = await import("node:child_process");
 	const { promisify } = await import("node:util");
-	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	const { getDockerCmd } = await import("./docker-cmd-Dqx2YENO.js").then((n) => n.t);
 	const { stdout } = await promisify(execFile)(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
 	const code = parseInt(stdout.trim(), 10);
 	return Number.isFinite(code) ? code : -1;
@@ -22117,7 +21811,7 @@ const EXIT_LOG_TAIL_LINES = 50;
 const defaultReadContainerLogsImpl = async (containerId) => {
 	const { execFile } = await import("node:child_process");
 	const { promisify } = await import("node:util");
-	const { getDockerCmd } = await import("./docker-cmd-voNPrcRh.js").then((n) => n.t);
+	const { getDockerCmd } = await import("./docker-cmd-Dqx2YENO.js").then((n) => n.t);
 	const { stdout, stderr } = await promisify(execFile)(getDockerCmd(), [
 		"logs",
 		"--tail",
@@ -24965,7 +24659,8 @@ async function runImageOverrideBuilds(overrides) {
 		try {
 			await runDockerStreaming(args, {
 				cwd: entry.contextDir,
-				env: { BUILDX_NO_DEFAULT_ATTESTATIONS: "1" }
+				env: { BUILDX_NO_DEFAULT_ATTESTATIONS: "1" },
+				progressLabel: `Building override image for '${target}'`
 			});
 		} catch (err) {
 			const e = err;
@@ -25401,7 +25096,7 @@ async function reloadAllServices(args) {
 async function loadAssetContextForTarget(args) {
 	const { target, controller, stacks, cdkOutDir, assetLoader, logger } = args;
 	const parsed = parseEcsTarget(target);
-	const candidate = pickCandidateStack(parsed.stackPattern, stacks);
+	const candidate = pickCandidateStack$1(parsed.stackPattern, stacks);
 	if (!candidate) {
 		logger.debug(`loadAssetContext: stack pattern '${parsed.stackPattern}' from target '${target}' not in the assembly. Classifier will see no asset context (rebuild).`);
 		return;
@@ -25465,7 +25160,7 @@ async function loadAssetContextForTarget(args) {
 */
 async function rollOneTarget(args) {
 	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, verdict, imageOverrideTag, logger } = args;
-	const candidate = pickCandidateStack(parseEcsTarget(newBoot.target).stackPattern, stacks);
+	const candidate = pickCandidateStack$1(parseEcsTarget(newBoot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 	try {
 		let resolved;
@@ -25517,7 +25212,7 @@ async function rollOneTarget(args) {
 	}
 }
 async function bootOneTarget(boot, runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag) {
-	const candidate = pickCandidateStack(parseEcsTarget(boot.target).stackPattern, stacks);
+	const candidate = pickCandidateStack$1(parseEcsTarget(boot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 	try {
 		return await runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag);
@@ -25556,7 +25251,7 @@ async function resolveServiceAndRunnerOpts(boot, stacks, options, discovery, ski
 	const logger = getLogger();
 	const target = boot.target;
 	const quiet = opts.quiet === true;
-	const imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
+	const imageContext = await buildEcsImageResolutionContext$1(target, stacks, options, stateProvider);
 	const service = resolveEcsServiceTarget(target, stacks, imageContext, { suppressLoadBalancerWarning });
 	if (!quiet) logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
 	if (!quiet && service.serviceConnect) logger.info(`Service Connect: namespace='${service.serviceConnect.namespaceName}', ${service.serviceConnect.services.length} service(s) registered for peer discovery.`);
@@ -25577,21 +25272,23 @@ async function resolveServiceAndRunnerOpts(boot, stacks, options, discovery, ski
 			await applyCrossStackResolverToTask(service.task, subContext);
 		}
 	} 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.");
+	const effectiveAssumeRole = resolveEcsAssumeRoleOption(options);
 	let assumedCredentials;
 	let resolvedRoleArn;
-	if (options.assumeTaskRole === true) {
-		if (!service.task.taskRoleArn) throw new LocalStartServiceError(`--assume-task-role passed without an ARN but service '${service.serviceLogicalId}' has no resolvable TaskRoleArn. Pass the ARN explicitly: --assume-task-role <arn>`);
-		resolvedRoleArn = await resolvePlaceholderAccount(service.task.taskRoleArn, options.region, options.profile);
-		assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region, options.profile);
-	} else if (typeof options.assumeTaskRole === "string") {
-		resolvedRoleArn = options.assumeTaskRole;
-		assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region, options.profile);
-	}
-	const envOverrides = readEnvOverridesFile(options.envVars);
+	if (effectiveAssumeRole === true) {
+		if (!service.task.taskRoleArn) throw new LocalStartServiceError(`--assume-role passed without an ARN but service '${service.serviceLogicalId}' has no resolvable TaskRoleArn. Pass the ARN explicitly: --assume-role <arn>`);
+		resolvedRoleArn = await resolvePlaceholderAccount$1(service.task.taskRoleArn, options.region, options.profile);
+		assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region, options.profile);
+	} else if (typeof effectiveAssumeRole === "string") {
+		resolvedRoleArn = effectiveAssumeRole;
+		assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region, options.profile);
+	}
+	const envOverrides = readEnvOverridesFile$1(options.envVars);
 	const taskOpts = {
 		cluster: options.cluster,
 		containerHost: options.containerHost,
 		skipPull,
+		skipBuild: options.build === false,
 		keepRunning: false,
 		detach: true
 	};
@@ -25882,7 +25579,7 @@ function describeRuleActionForSummary(action) {
 function describeForwardTargetForSummary(t) {
 	return t.kind === "lambda" ? `<Lambda: ${t.lambda.logicalId}>` : `<ECS: ${t.serviceTarget}>`;
 }
-async function resolvePlaceholderAccount(arn, region, profile) {
+async function resolvePlaceholderAccount$1(arn, region, profile) {
 	if (!arn.includes("${AWS::AccountId}")) return arn;
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient(buildStsClientConfig({
@@ -25897,7 +25594,7 @@ async function resolvePlaceholderAccount(arn, region, profile) {
 		sts.destroy();
 	}
 }
-async function assumeTaskRole(roleArn, region, profile) {
+async function assumeTaskRole$1(roleArn, region, profile) {
 	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient(buildStsClientConfig({
 		region,
@@ -25924,9 +25621,9 @@ async function assumeTaskRole(roleArn, region, profile) {
 * site-level binding test that locks the `--from-cfn-stack` SSM-parameter
 * resolution call (issue #94).
 */
-async function buildEcsImageResolutionContext(target, stacks, options, stateProvider) {
+async function buildEcsImageResolutionContext$1(target, stacks, options, stateProvider) {
 	const logger = getLogger();
-	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+	const candidate = pickCandidateStack$1(parseEcsTarget(target).stackPattern, stacks);
 	if (!candidate) return void 0;
 	const needs = detectEcsImageResolutionNeeds(candidate);
 	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
@@ -25937,7 +25634,7 @@ async function buildEcsImageResolutionContext(target, stacks, options, stateProv
 		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);
+			accountId = await resolveCallerAccountId$1(region, options.profile);
 		} catch (err) {
 			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
 		}
@@ -25968,7 +25665,7 @@ async function buildEcsImageResolutionContext(target, stacks, options, stateProv
 	else if (!stateProvider && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics. Pass a state-source flag (e.g. --from-cfn-stack or a host-provided extension) to substitute them against the deployed state.");
 	return ctx;
 }
-function pickCandidateStack(stackPattern, stacks) {
+function pickCandidateStack$1(stackPattern, stacks) {
 	if (stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		return;
@@ -25976,7 +25673,7 @@ function pickCandidateStack(stackPattern, stacks) {
 	const matched = matchStacks(stacks, [stackPattern]);
 	if (matched.length === 1) return matched[0];
 }
-async function resolveCallerAccountId(region, profile) {
+async function resolveCallerAccountId$1(region, profile) {
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient(buildStsClientConfig({
 		region,
@@ -25988,7 +25685,7 @@ async function resolveCallerAccountId(region, profile) {
 		sts.destroy();
 	}
 }
-function readEnvOverridesFile(filePath) {
+function readEnvOverridesFile$1(filePath) {
 	if (!filePath) return void 0;
 	let raw;
 	try {
@@ -26133,12 +25830,12 @@ async function resolveAndBuildImageOverrides(args) {
 	const { perTarget, stacks, options, extraStateProviders, logger } = args;
 	const resolvedForPeek = [];
 	for (const target of perTarget) {
-		const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+		const candidate = pickCandidateStack$1(parseEcsTarget(target).stackPattern, stacks);
 		const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 		let imageContext;
 		let service;
 		try {
-			imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
+			imageContext = await buildEcsImageResolutionContext$1(target, stacks, options, stateProvider);
 			service = resolveEcsServiceTarget(target, stacks, imageContext, { suppressLoadBalancerWarning: true });
 		} catch (err) {
 			logger.debug(`--image-override peek failed for '${target}': ${err instanceof Error ? err.message : String(err)}.`);
@@ -26197,13 +25894,74 @@ function enforceStrictOverrides(strict, uncoveredPinnedTargets) {
 	throw new LocalStartServiceError(`--strict-overrides set, but ${uncoveredPinnedTargets.length} pinned target(s) remain uncovered: ${uncoveredPinnedTargets.join(", ")}. Pass --image-override <service>=<dockerfile> for each, drop --strict-overrides, or drop --from-cfn-stack to iterate on local CDK assets.`);
 }
 /**
+* Build the canonical `--cluster <name>` Option for every ECS surface.
+*
+* Shared between `cdkl run-task` and the `start-service` / `start-alb`
+* pair so the default (the active embed config's `resourceNamePrefix`)
+* is defined exactly once — issue #249 / C12. Building it as a fresh
+* Option per call (not a module-level const) is load-bearing: the
+* embed config is host-installed at command-factory time, and a
+* module-level Option would freeze the host-default prefix at
+* import time.
+*/
+function ecsClusterOption() {
+	return new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default(getEmbedConfig().resourceNamePrefix);
+}
+/**
+* Add the `--assume-task-role` flag plus its `--assume-role` alias to
+* an ECS command. Issue #249 / C6 — every non-ECS command calls the
+* same concept `--assume-role`, so the ECS surface accepts the
+* cross-command name as a NON-BREAKING alias. Precedence when both
+* are passed: `--assume-role` (new) wins. {@link resolveEcsAssumeRoleOption}
+* computes the effective value and fires a one-time deprecation warn
+* when only the legacy `--assume-task-role` is set.
+*
+* Breaking unification of all three parsers (`invoke`, `start-api`,
+* ECS) is tracked separately under issue #256.
+*/
+function addEcsAssumeRoleOptions(cmd) {
+	return cmd.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 task role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override. DEPRECATED alias of `--assume-role`; both forms work, but `--assume-role` is the cross-command name and will become the only form in a future release.")).addOption(new Option("--assume-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 task role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override. Cross-command alias matching the same flag on `invoke` / `invoke-agentcore` / `start-api`; supersedes the older `--assume-task-role` (which still works)."));
+}
+/**
+* Module-level latch for the `--assume-task-role` deprecation warn.
+* Per-process single-fire, so a `--watch` reload that re-enters the
+* resolver on every source-change firing does not spam the user.
+*
+* Test-only `__resetAssumeTaskRoleDeprecationLatch` lets the unit suite
+* drive the latch through repeated invocations.
+*/
+let assumeTaskRoleDeprecationWarned = false;
+/**
+* Collapse `--assume-task-role` (legacy) and `--assume-role` (new) into
+* a single effective value. When BOTH are set, `--assume-role` wins
+* (matches Commander's "later wins" default for repeatable flags, and
+* gives the cross-command name priority). When ONLY `--assume-task-role`
+* is set, fires a **per-process one-time** deprecation warn naming the
+* replacement — the latch above prevents `--watch` reloads from
+* re-emitting the warn on every source-change firing.
+*
+* Issue #249 / C6.
+*/
+function resolveEcsAssumeRoleOption(options) {
+	if (options.assumeRole !== void 0) return options.assumeRole;
+	if (options.assumeTaskRole !== void 0) {
+		if (!assumeTaskRoleDeprecationWarned) {
+			assumeTaskRoleDeprecationWarned = true;
+			getLogger().warn("--assume-task-role is deprecated; use --assume-role instead. Both forms continue to work, but --assume-role is the cross-command name.");
+		}
+		return options.assumeTaskRole;
+	}
+}
+/**
 * Add the CLI options shared by both ECS-service commands (`start-service` and
 * `start-alb`) to a command. The command-specific argument / description and
 * the one unique option (`--host-port` vs `--lb-port`) are added by each
 * factory.
 */
 function addCommonEcsServiceOptions(cmd) {
-	cmd.addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default(getEmbedConfig().resourceNamePrefix)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--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 task 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.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--max-tasks <n>", `Hard cap on local replica count. Caps the template DesiredCount so local dev machines don't run an unbounded number of containers. Cannot exceed ${83} due to the per-replica link-local /24 subnet allocator's range.`).default(3).argParser(parseMaxTasks)).addOption(new Option("--restart-policy <policy>", "How to react when an essential container exits. 'on-failure' (default) restarts only on non-zero exit; 'always' restarts on every exit; 'none' shuts the replica down and runs the service degraded.").default("on-failure").argParser(parseRestartPolicy)).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 in container Environment[].Value is warn-and-dropped: CFn ListStackResources does not return per-attribute values, and unlike Lambda (where \`cdkl invoke --from-cfn-stack\` recovers Fn::GetAtt from the deployed function via lambda:GetFunctionConfiguration), no ECS-side equivalent resolves attributes off a deployed task / service.`)).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).addOption(new Option("--no-logs", "Disable foreground streaming of each replica container stdout/stderr. By default every booted replica streams its docker logs to the host terminal with a [svc=<service> r=<replica-index> c=<container>] prefix (parity with `run-task`). Pass --no-logs for multi-replica / multi-service runs whose interleaved log volume is unreadable; `docker logs -f <id>` in a separate terminal stays available.")).addOption(new Option("--shadow-ready-timeout <ms>", `Issue #265 — milliseconds the \`--watch\` rolling primitive waits for a shadow replica's first essential-container port to accept a TCP connection before swapping Cloud Map + front-door registrations off the old replica. Defaults to 60000 (60s) which covers realistic prod-shaped Node app cold-starts (TS->JS compile, full node_modules graph, framework boot, DB pool init). Bump higher when the reload log surfaces "TCP probe <ip>:<port> did not accept within <N>ms" — typical for Java / heavy ORM init / \`--inspect-brk\` attach pauses. Honored by --watch on \`${getEmbedConfig().binaryName} start-service\` and \`${getEmbedConfig().binaryName} start-alb\`. Env var: \`${getEmbedConfig().envPrefix}_SHADOW_READY_TIMEOUT_MS\` (flag wins over env).`).argParser(parseShadowReadyTimeout));
+	cmd.addOption(ecsClusterOption()).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"));
+	addEcsAssumeRoleOptions(cmd);
+	cmd.addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--no-build", "Skip docker build on the local CDK-asset path for every container (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 ECR-pull / public-registry images. Per-container --image-override mappings take precedence (the override tag is used as-is, --no-build does not apply). Compatible with --no-pull.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--max-tasks <n>", `Hard cap on local replica count. Caps the template DesiredCount so local dev machines don't run an unbounded number of containers. Cannot exceed ${83} due to the per-replica link-local /24 subnet allocator's range.`).default(3).argParser(parseMaxTasks)).addOption(new Option("--restart-policy <policy>", "How to react when an essential container exits. 'on-failure' (default) restarts only on non-zero exit; 'always' restarts on every exit; 'none' shuts the replica down and runs the service degraded.").default("on-failure").argParser(parseRestartPolicy)).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 in container Environment[].Value is warn-and-dropped: CFn ListStackResources does not return per-attribute values, and unlike Lambda (where \`cdkl invoke --from-cfn-stack\` recovers Fn::GetAtt from the deployed function via lambda:GetFunctionConfiguration), no ECS-side equivalent resolves attributes off a deployed task / service.`)).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region.")).addOption(new Option("--no-logs", "Disable foreground streaming of each replica container stdout/stderr. By default every booted replica streams its docker logs to the host terminal with a [svc=<service> r=<replica-index> c=<container>] prefix (parity with `run-task`). Pass --no-logs for multi-replica / multi-service runs whose interleaved log volume is unreadable; `docker logs -f <id>` in a separate terminal stays available.")).addOption(new Option("--shadow-ready-timeout <ms>", `Issue #265 — milliseconds the \`--watch\` rolling primitive waits for a shadow replica's first essential-container port to accept a TCP connection before swapping Cloud Map + front-door registrations off the old replica. Defaults to 60000 (60s) which covers realistic prod-shaped Node app cold-starts (TS->JS compile, full node_modules graph, framework boot, DB pool init). Bump higher when the reload log surfaces "TCP probe <ip>:<port> did not accept within <N>ms" — typical for Java / heavy ORM init / \`--inspect-brk\` attach pauses. Honored by --watch on \`${getEmbedConfig().binaryName} start-service\` and \`${getEmbedConfig().binaryName} start-alb\`. Env var: \`${getEmbedConfig().envPrefix}_SHADOW_READY_TIMEOUT_MS\` (flag wins over env).`).argParser(parseShadowReadyTimeout));
 	[
 		...commonOptions(),
 		...appOptions(),
@@ -26232,6 +25990,345 @@ function addImageOverrideOptions(cmd) {
 	return cmd.addOption(new Option("--image-override <service=dockerfile or dockerfile...>", "Replace a service target's deployed-registry image with a local `docker build` of the supplied Dockerfile (repeatable). Two forms: <service>=<dockerfile> binds the service explicitly; a bare <dockerfile> opens a multi-select picker against the still-uncovered pinned targets (one Dockerfile across N services). Mix freely. Lets `--from-cfn-stack` still reach real AWS state while you iterate locally on the application container.")).addOption(new Option("--image-build-arg <KEY=VAL...>", "Global `docker build --build-arg KEY=VAL` pair applied to every --image-override build (repeatable). Lets a CDK Dockerfile that branches on an ARG (env target, base image tag, package mirror) honor that ARG locally without editing the Dockerfile.")).addOption(new Option("--image-build-secret <id=src...>", "Global `docker build --secret id=<id>,src=<src>` entry applied to every --image-override build (repeatable). Enables `RUN --mount=type=secret,id=<id>` in the Dockerfile — the standard private-registry / npm-token recipe (e.g. `--image-build-secret npmrc=./.npmrc`).")).addOption(new Option("--image-target <stage or svc=stage...>", "Repeatable. Bare `<stage>` is a global --target for every --image-override build; `<service>=<stage>` (issue #240) scopes the --target to one overridden target so a monorepo with different multi-stage Dockerfiles per service can stop each at its own intermediate stage. Per-service form overrides the global on the named target.")).addOption(new Option("--no-interactive-overrides", "Suppress the interactive boot prompt that walks each pinned target asking for a Dockerfile path, and the multi-select prompt fired by `--image-override <dockerfile>` (picker form). Useful for CI / scripted invocations.")).addOption(new Option("--strict-overrides", "Fail fast at boot when any pinned target remains uncovered after `--image-override` + the boot prompt resolve. Off by default; the boot WARN per uncovered pinned target still fires regardless.").default(false));
 }
 
+//#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");
+	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,
+			profile: options.profile
+		});
+		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);
+		const effectiveAssumeRole = resolveEcsAssumeRoleOption(options);
+		let assumedCredentials;
+		let resolvedRoleArn;
+		if (effectiveAssumeRole === true) {
+			if (!task.taskRoleArn) throw new Error(`--assume-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-role <arn>`);
+			resolvedRoleArn = await resolvePlaceholderAccount(task.taskRoleArn, options.region, options.profile);
+			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region, options.profile);
+		} else if (typeof effectiveAssumeRole === "string") {
+			resolvedRoleArn = effectiveAssumeRole;
+			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region, options.profile);
+		}
+		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,
+			skipBuild: options.build === 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, profile) {
+	if (!arn.includes("${AWS::AccountId}")) return arn;
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient(buildStsClientConfig({
+		region,
+		profile
+	}));
+	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, profile) {
+	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient(buildStsClientConfig({
+		region,
+		profile
+	}));
+	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;
+		else {
+			const loadError = stateProvider.getLastLoadError?.();
+			if (loadError) ctx.stateLoadFailureMessage = loadError;
+		}
+		if (needs.needsEnvOrSecretSubstitution && stateProvider.resolveTemplateSsmParameters) {
+			const ssmParameters = await stateProvider.resolveTemplateSsmParameters(candidate.template);
+			if (Object.keys(ssmParameters.values).length > 0) ctx.stateParameters = ssmParameters.values;
+			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(buildStsClientConfig({
+		region,
+		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(options.profile);
+}
+function createLocalRunTaskCommand(opts = {}) {
+	setEmbedConfig(opts.embedConfig);
+	const cmd = new Command("run-task").description("Run an AWS::ECS::TaskDefinition locally — pulls/builds images, sets up a per-task docker network with the AWS-published metadata-endpoints sidecar, and starts every container in dependsOn order. Target accepts a CDK display path (MyStack/MyService/TaskDef) or stack-qualified logical ID (MyStack:MyServiceTaskDefXYZ1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick the task definition from a list.").argument("[target]", "CDK display path or stack-qualified logical ID of the AWS::ECS::TaskDefinition to run (omit to pick interactively in a TTY)").action(withErrorHandling(async (target, options) => {
+		await localRunTaskCommand(target, options, opts.extraStateProviders);
+	}));
+	addRunTaskSpecificOptions(cmd);
+	[
+		...commonOptions(),
+		...appOptions(),
+		...contextOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(regionOption);
+	return cmd;
+}
+/**
+* Register the option block that `cdkl run-task` adds on top of the shared
+* common / app / context option helpers. Shared between `cdkl run-task` and
+* any host CLI (e.g. cdkd's `local run-task`) that wraps the single-task
+* ECS local runner, so adding or renaming a `run-task`-only flag here
+* propagates to every embedder without duplicate `.addOption(...)` blocks.
+*
+* Calling order only affects `--help` presentation (Commander parses
+* insertion-order-independent). The host-CLI convention is host-specific
+* options first, then this helper, then the shared common / app / context
+* options — host flags / run-task flags / common flags grouped in three
+* `--help` clusters. Chainable: returns `cmd`.
+*
+* NOTE: `run-task` does NOT compose with {@link addCommonEcsServiceOptions}
+* even though many flags overlap. The two ECS surfaces (single-task vs
+* multi-replica service) have intentionally divergent defaults
+* (`run-task` has no `--max-tasks` / `--restart-policy`; `start-service`
+* / `start-alb` have no `--host-port` / `--keep-running` / `--detach`),
+* and folding `run-task` into the service common block would mutate the
+* surface non-trivially. Each command keeps its own helper.
+*/
+function addRunTaskSpecificOptions(cmd) {
+	cmd.addOption(ecsClusterOption()).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."));
+	addEcsAssumeRoleOptions(cmd);
+	cmd.addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--no-build", "Skip docker build on every CDK-asset container (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 ECR-pull / public-registry containers. Compatible with --no-pull.")).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 in container Environment[].Value is warn-and-dropped: CFn ListStackResources does not return per-attribute values, and unlike Lambda (where \`cdkl invoke --from-cfn-stack\` recovers Fn::GetAtt from the deployed function via lambda:GetFunctionConfiguration), no ECS-side equivalent resolves attributes off a deployed task / service.`)).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
+	return cmd;
+}
+
 //#endregion
 //#region src/cli/commands/local-start-service.ts
 /**
@@ -27156,7 +27253,7 @@ function createLocalStartAlbCommand(opts = {}) {
 */
 function addAlbSpecificOptions(cmd) {
 	addImageOverrideOptions(cmd);
-	return cmd.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", "Terminate TLS locally for cloud-HTTPS listeners. Default: a cloud-HTTPS listener is served over plain HTTP locally (X-Forwarded-Proto: https is preserved so the upstream app still sees the deployed listener protocol). Implied by --tls-cert / --tls-key. Use this when local-dev cookies need Secure / SameSite=None, when the upstream app inspects TLS metadata, or for mTLS / SNI testing — otherwise plain HTTP is friendlier (no self-signed cert warnings in curl / browser).")).addOption(new Option("--tls-cert <path>", "PEM-encoded server certificate for HTTPS front-door listeners. Implies --tls. Must be set together with --tls-key. Pass --tls alone (without --tls-cert / --tls-key) 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. Implies --tls. 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.")).addOption(new Option("--watch", "Hot-reload: re-synth + per-replica reload of every ECS service behind the ALB when the CDK source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). A per-firing classifier picks the per-replica primitive: source-only edits on interpreted-language handlers (Node/Python/Ruby/shell) take a bind-mount FAST PATH (`docker cp` the new source into each replica + `docker restart`; no rebuild, front-door pool entry unchanged since the IP/port are preserved). Dockerfile / dependency manifest / compiled-language source / ambiguous edits fall through to the rebuild rolling primitive — boot a shadow under a bumped generation suffix, wait for its container port to accept a TCP connection, atomically register it in the front-door pool, then drop the old entry and retire the old container. Either path rolls one replica at a time, so a continuous external request stream against the listener port sees zero connection refusals across the reload. The host front-door (TLS, JWKS cache, Lambda-target containers, listener sockets) stays up across the reload. Lambda target groups behind the ALB are a no-op on reload (the warm RIE container keeps its boot-time image). Off by default; existing replica(s) keep serving when synth fails mid-reload.").default(false));
+	return cmd.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", "Terminate TLS locally for cloud-HTTPS listeners. Default: a cloud-HTTPS listener is served over plain HTTP locally (X-Forwarded-Proto: https is preserved so the upstream app still sees the deployed listener protocol). Implied by --tls-cert / --tls-key. Use this when local-dev cookies need Secure / SameSite=None, when the upstream app inspects TLS metadata, or for mTLS / SNI testing — otherwise plain HTTP is friendlier (no self-signed cert warnings in curl / browser).")).addOption(new Option("--tls-cert <path>", "PEM-encoded server certificate for HTTPS front-door listeners. Implies --tls. Must be set together with --tls-key. Pass --tls alone (without --tls-cert / --tls-key) 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. Implies --tls. 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 this command INJECTS only when an inbound request has none (the default-when-missing role) — `cdkl start-alb` is the local ALB front-door RECEIVING outside-in requests, so this token is the fallback the front-door slots in as Authorization: Bearer <jwt> if the caller did not already supply one. Verified against the same JWKS / OIDC discovery URL the deployed ALB would (signature + iss + aud + exp). Cookie pass-through (AWSELBAuthSessionCookie-*) also bypasses the guard. Contrast with `cdkl invoke-agentcore --bearer-token`, where the role is reversed — that command is the outbound client and ALWAYS presents this token (the supplier).")).addOption(new Option("--watch", "Hot-reload: re-synth + per-replica reload of every ECS service behind the ALB when the CDK source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). A per-firing classifier picks the per-replica primitive: source-only edits on interpreted-language handlers (Node/Python/Ruby/shell) take a bind-mount FAST PATH (`docker cp` the new source into each replica + `docker restart`; no rebuild, front-door pool entry unchanged since the IP/port are preserved). Dockerfile / dependency manifest / compiled-language source / ambiguous edits fall through to the rebuild rolling primitive — boot a shadow under a bumped generation suffix, wait for its container port to accept a TCP connection, atomically register it in the front-door pool, then drop the old entry and retire the old container. Either path rolls one replica at a time, so a continuous external request stream against the listener port sees zero connection refusals across the reload. The host front-door (TLS, JWKS cache, Lambda-target containers, listener sockets) stays up across the reload. Lambda target groups behind the ALB are a no-op on reload (the warm RIE container keeps its boot-time image). Off by default; existing replica(s) keep serving when synth fails mid-reload.").default(false));
 }
 
 //#endregion
@@ -27252,5 +27349,5 @@ function addListSpecificOptions(cmd) {
 }
 
 //#endregion
-export { AGENTCORE_SIGV4_SERVICE as $, formatStateRemedy as $n, evaluateResponseParameters as $t, isLocalCdkAssetImage as A, resolveCfnStackName as An, defaultCredentialsLoader as At, createLocalRunTaskCommand as B, parseSelectionExpressionPath as Bn, invokeRequestAuthorizer as Bt, buildImageOverrideTag as C, substituteEnvVarsFromStateAsync as Cn, filterRoutesByApiIdentifier as Ct, resolveImageOverrides as D, rejectExplicitCfnStackWithMultipleStacks as Dn, startApiServer as Dt, parseImageOverrideFlags as E, isCfnFlagPresent as En, readMtlsMaterialsFromDisk as Et, DEFAULT_SHADOW_READY_TIMEOUT_MS as F, resolveSingleTarget as Fn, verifyJwtAuthorizer as Ft, A2A_CONTAINER_PORT as G, AGENTCORE_AGUI_PROTOCOL as Gn, buildCorsConfigFromCloudFrontChain as Gt, addInvokeAgentCoreSpecificOptions as H, pickRefLogicalId as Hn, attachAuthorizers as Ht, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as I, countTargets as In, verifyJwtViaDiscovery as It, MCP_CONTAINER_PORT as J, AGENTCORE_RUNTIME_TYPE as Jn, matchRoute as Jt, A2A_PATH as K, AGENTCORE_HTTP_PROTOCOL as Kn, isFunctionUrlOacFronted as Kt, setShadowReadyTimeoutMs as L, listTargets as Ln, buildMethodArn as Lt, buildCloudMapIndex as M, collectSsmParameterRefs as Mn, buildJwksUrlFromIssuer as Mt, CloudMapRegistry as N, resolveSsmParameters as Nn, createJwksCache as Nt, runImageOverrideBuilds as O, resolveCfnFallbackRegion as On, resolveSelectionExpression as Ot, classifySourceChange as P, resolveWatchConfig as Pn, verifyCognitoJwt as Pt, parseSseForJsonRpc as Q, derivePseudoParametersFromRegion as Qn, buildRestV1Event as Qt, getContainerNetworkIp as R, discoverWebSocketApis as Rn, computeRequestIdentityHash as Rt, ImageOverrideError as S, substituteEnvVarsFromState as Sn, availableApiIdentifiers as St, mergeForService as T, createLocalStateProvider as Tn, groupRoutesByServer as Tt, createLocalInvokeAgentCoreCommand as U, resolveLambdaArnIntrinsic as Un, applyCorsResponseHeaders as Ut, attachContainerLogStreamer as V, discoverRoutes as Vn, invokeTokenAuthorizer as Vt, invokeAgentCoreWs as W, AGENTCORE_A2A_PROTOCOL as Wn, buildCorsConfigByApiId as Wt, MCP_PROTOCOL_VERSION as X, pickAgentCoreCandidateStack as Xn, applyAuthorizerOverlay as Xt, MCP_PATH as Y, AgentCoreResolutionError as Yn, translateLambdaResponse as Yt, mcpInvokeOnce as Z, resolveAgentCoreTarget as Zn, buildHttpApiV2Event as Zt, buildEcsImageResolutionContext as _, resolveRuntimeFileExtension as _n, createFileWatcher as _t, albStrategy as a, probeHostGatewaySupport as an, SUPPORTED_CODE_RUNTIMES as at, resolveSharedSidecarCredentials as b, substituteAgainstState as bn, materializeLayerFromArn as bt, resolveAlbTarget as c, buildMgmtEndpointEnvUrl as cn, renderCodeDockerfile as ct, addStartServiceSpecificOptions as d, buildConnectEvent as dn, createLocalInvokeCommand as dt, pickResponseTemplate as en, substituteImagePlaceholders as er, signAgentCoreInvocation as et, createLocalStartServiceCommand as f, buildDisconnectEvent as fn, addStartApiSpecificOptions as ft, addImageOverrideOptions as g, resolveRuntimeCodeMountPath as gn, createAuthorizerCache as gt, addCommonEcsServiceOptions as h, buildContainerImage as hn, resolveApiTargetSubset as ht, addAlbSpecificOptions as i, HOST_GATEWAY_MIN_VERSION as in, resolveProfileCredentials as ir, downloadAndExtractS3Bundle as it, listPinnedTargets as j, CfnLocalStateProvider as jn, buildCognitoJwksUrl as jt, describePinnedImageUri as k, resolveCfnRegion as kn, resolveServiceIntegrationParameters as kt, isApplicationLoadBalancer as l, handleConnectionsRequest as ln, toCmdArgv as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, architectureToPlatform as mn, createWatchPredicates as mt, createLocalListCommand as n, tryParseStatus as nn, LocalInvokeBuildError as nr, invokeAgentCore as nt, createLocalStartAlbCommand as o, bufferToBody as on, buildAgentCoreCodeImage as ot, serviceStrategy as p, buildMessageEvent as pn, createLocalStartApiCommand as pt, a2aInvokeOnce as q, AGENTCORE_MCP_PROTOCOL as qn, matchPreflight as qt, formatTargetListing as r, VtlEvaluationError as rn, buildStsClientConfig as rr, waitForAgentCorePing as rt, parseLbPortOverrides as s, ConnectionRegistry as sn, computeCodeImageTag as st, addListSpecificOptions as t, selectIntegrationResponse as tn, tryResolveImageFnJoin as tr, AGENTCORE_SESSION_ID_HEADER as tt, resolveAlbFrontDoor as u, parseConnectionsPath as un, addInvokeSpecificOptions as ut, parseMaxTasks as v, resolveRuntimeImage as vn, attachStageContext as vt, enforceImageOverrideOrphans as w, LocalStateSourceError as wn, filterRoutesByApiIdentifiers as wt, runEcsServiceEmulator as x, substituteAgainstStateAsync as xn, resolveEnvVars as xt, parseRestartPolicy as y, EcsTaskResolutionError as yn, buildStageMap as yt, addRunTaskSpecificOptions as z, discoverWebSocketApisOrThrow as zn, evaluateCachedLambdaPolicy as zt };
-//# sourceMappingURL=local-list-DgwUotOK.js.map
+export { MCP_PROTOCOL_VERSION as $, pickAgentCoreCandidateStack as $n, applyAuthorizerOverlay as $t, mergeForService as A, rejectExplicitCfnStackWithMultipleStacks as An, startApiServer as At, DEFAULT_SHADOW_READY_TIMEOUT_MS as B, listTargets as Bn, buildMethodArn as Bt, parseRestartPolicy as C, substituteAgainstState as Cn, materializeLayerFromArn as Ct, ImageOverrideError as D, LocalStateSourceError as Dn, filterRoutesByApiIdentifiers as Dt, runEcsServiceEmulator as E, substituteEnvVarsFromStateAsync as En, filterRoutesByApiIdentifier as Et, isLocalCdkAssetImage as F, collectSsmParameterRefs as Fn, buildJwksUrlFromIssuer as Ft, addInvokeAgentCoreSpecificOptions as G, pickRefLogicalId as Gn, attachAuthorizers as Gt, setShadowReadyTimeoutMs as H, discoverWebSocketApisOrThrow as Hn, evaluateCachedLambdaPolicy as Ht, listPinnedTargets as I, resolveSsmParameters as In, createJwksCache as It, A2A_CONTAINER_PORT as J, AGENTCORE_AGUI_PROTOCOL as Jn, buildCorsConfigFromCloudFrontChain as Jt, createLocalInvokeAgentCoreCommand as K, resolveLambdaArnIntrinsic as Kn, applyCorsResponseHeaders as Kt, buildCloudMapIndex as L, resolveWatchConfig as Ln, verifyCognitoJwt as Lt, resolveImageOverrides as M, resolveCfnRegion as Mn, resolveServiceIntegrationParameters as Mt, runImageOverrideBuilds as N, resolveCfnStackName as Nn, defaultCredentialsLoader as Nt, buildImageOverrideTag as O, createLocalStateProvider as On, groupRoutesByServer as Ot, describePinnedImageUri as P, CfnLocalStateProvider as Pn, buildCognitoJwksUrl as Pt, MCP_PATH as Q, AgentCoreResolutionError as Qn, translateLambdaResponse as Qt, CloudMapRegistry as R, resolveSingleTarget as Rn, verifyJwtAuthorizer as Rt, parseMaxTasks as S, EcsTaskResolutionError as Sn, buildStageMap as St, resolveSharedSidecarCredentials as T, substituteEnvVarsFromState as Tn, availableApiIdentifiers as Tt, getContainerNetworkIp as U, parseSelectionExpressionPath as Un, invokeRequestAuthorizer as Ut, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as V, discoverWebSocketApis as Vn, computeRequestIdentityHash as Vt, attachContainerLogStreamer as W, discoverRoutes as Wn, invokeTokenAuthorizer as Wt, a2aInvokeOnce as X, AGENTCORE_MCP_PROTOCOL as Xn, matchPreflight as Xt, A2A_PATH as Y, AGENTCORE_HTTP_PROTOCOL as Yn, isFunctionUrlOacFronted as Yt, MCP_CONTAINER_PORT as Z, AGENTCORE_RUNTIME_TYPE as Zn, matchRoute as Zt, addCommonEcsServiceOptions as _, architectureToPlatform as _n, createWatchPredicates as _t, albStrategy as a, tryParseStatus as an, LocalInvokeBuildError as ar, invokeAgentCore as at, buildEcsImageResolutionContext$1 as b, resolveRuntimeFileExtension as bn, createFileWatcher as bt, resolveAlbTarget as c, probeHostGatewaySupport as cn, SUPPORTED_CODE_RUNTIMES as ct, addStartServiceSpecificOptions as d, buildMgmtEndpointEnvUrl as dn, renderCodeDockerfile as dt, buildHttpApiV2Event as en, resolveAgentCoreTarget as er, mcpInvokeOnce as et, createLocalStartServiceCommand as f, handleConnectionsRequest as fn, toCmdArgv as ft, MAX_TASKS_SUBNET_RANGE_CAP as g, buildMessageEvent as gn, createLocalStartApiCommand as gt, createLocalRunTaskCommand as h, buildDisconnectEvent as hn, addStartApiSpecificOptions as ht, addAlbSpecificOptions as i, selectIntegrationResponse as in, tryResolveImageFnJoin as ir, AGENTCORE_SESSION_ID_HEADER as it, parseImageOverrideFlags as j, resolveCfnFallbackRegion as jn, resolveSelectionExpression as jt, enforceImageOverrideOrphans as k, isCfnFlagPresent as kn, readMtlsMaterialsFromDisk as kt, isApplicationLoadBalancer as l, bufferToBody as ln, buildAgentCoreCodeImage as lt, addRunTaskSpecificOptions as m, buildConnectEvent as mn, createLocalInvokeCommand as mt, createLocalListCommand as n, evaluateResponseParameters as nn, formatStateRemedy as nr, AGENTCORE_SIGV4_SERVICE as nt, createLocalStartAlbCommand as o, VtlEvaluationError as on, buildStsClientConfig as or, waitForAgentCorePing as ot, serviceStrategy as p, parseConnectionsPath as pn, addInvokeSpecificOptions as pt, invokeAgentCoreWs as q, AGENTCORE_A2A_PROTOCOL as qn, buildCorsConfigByApiId as qt, formatTargetListing as r, pickResponseTemplate as rn, substituteImagePlaceholders as rr, signAgentCoreInvocation as rt, parseLbPortOverrides as s, HOST_GATEWAY_MIN_VERSION as sn, resolveProfileCredentials as sr, downloadAndExtractS3Bundle as st, addListSpecificOptions as t, buildRestV1Event as tn, derivePseudoParametersFromRegion as tr, parseSseForJsonRpc as tt, resolveAlbFrontDoor as u, ConnectionRegistry as un, computeCodeImageTag as ut, addEcsAssumeRoleOptions as v, buildContainerImage as vn, resolveApiTargetSubset as vt, resolveEcsAssumeRoleOption as w, substituteAgainstStateAsync as wn, resolveEnvVars as wt, ecsClusterOption as x, resolveRuntimeImage as xn, attachStageContext as xt, addImageOverrideOptions as y, resolveRuntimeCodeMountPath as yn, createAuthorizerCache as yt, classifySourceChange as z, countTargets as zn, verifyJwtViaDiscovery as zt };
+//# sourceMappingURL=local-list-Dn0Al276.js.map