cdk-local 0.129.0 → 0.130.0

package/dist/{local-studio-HawiuYRz.js → local-studio-BlFoXpwl.js}

@@ -6687,719 +6687,763 @@ function resolveRuntimeCodeMountPath(runtime) {
 }
 
 //#endregion
-//#region src/local/docker-runner.ts
-const execFileAsync$5 = promisify(execFile);
+//#region src/assets/docker-build.ts
 /**
-* Wraps `docker pull` / `docker run` / `docker rm` for `cdkl invoke`.
+* Build a Docker image from a CDK asset source. Returns the local image
+* tag the caller should use for `docker tag` / `docker push` (publisher)
+* or `docker run` (local-invoke).
 *
-* Mirrors the style of `src/assets/docker-asset-publisher.ts` (execFile for
-* one-shot calls, spawn for long-running ones). Kept as a separate file so
-* the command layer's wiring stays small; PR 5 (container Lambda) is
-* expected to add a second non-build call site, at which point the
-* common surface can be lifted into a shared helper.
-*/
-var DockerRunnerError = class DockerRunnerError extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "DockerRunnerError";
-		Object.setPrototypeOf(this, DockerRunnerError.prototype);
-	}
-};
-/**
-* Pull the image. No-op when `skipPull` is true.
+* Two source modes (mirrors CDK CLI):
+*   - `executable`: run the user-supplied command, capture stdout, return
+*     it as the local tag. The script is responsible for building AND
+*     tagging; cdk-local just reads the tag from stdout. Used for Bazel /
+*     custom build pipelines that produce images outside `docker build`.
+*   - `directory`: standard `docker build <dir>` with the full BuildKit
+*     flag set described above. Caller must pass `options.tag`.
 *
-* In verbose mode (`--verbose` / global log level `debug`), streams the
-* full `docker pull` progress to stdout so the user sees per-layer
-* downloads. In the default compact mode the call is silent (cached
-* images are the common case; a fresh pull still shows progress only
-* via `--verbose`). Errors are always surfaced: the captured stderr is
-* folded into the thrown `DockerRunnerError` message.
+* `executable` takes precedence when both fields are set (matches CDK CLI).
 */
-async function pullImage(image, skipPull, platform) {
-	const logger = getLogger().child("docker");
-	if (skipPull) {
-		logger.debug(`Skipping docker pull for ${image} (--no-pull)`);
-		return;
-	}
-	const platformArgs = platform ? ["--platform", platform] : [];
-	if (getLogger().getLevel() === "debug") {
-		logger.info(`Pulling ${image}${platform ? ` (${platform})` : ""}...`);
+async function buildDockerImage(asset, cdkOutDir, options) {
+	const source = asset.source;
+	const logger = getLogger().child("docker-build");
+	if (source.executable && source.executable.length > 0) {
+		const [cmd, ...args] = source.executable;
+		if (!cmd) throw options.wrapError("asset source.executable[] is empty");
+		const cwd = source.directory ? `${cdkOutDir}/${source.directory}` : cdkOutDir;
+		logger.debug(`Building Docker image via executable: ${source.executable.join(" ")} (cwd=${cwd})`);
+		let result;
 		try {
-			await runDockerForeground([
-				"pull",
-				...platformArgs,
-				image
-			]);
+			result = await spawnStreaming(cmd, args, { cwd });
 		} catch (err) {
-			throw new DockerRunnerError(`docker pull ${image} failed: ${err.message}`);
+			const e = err;
+			throw options.wrapError(e.stderr || e.message || String(err));
 		}
-		return;
+		const tag = result.stdout.trim();
+		if (!tag) throw options.wrapError(`docker build executable produced no output (expected the local image tag on stdout): ${cmd} ${args.join(" ")}`);
+		return tag;
 	}
-	logger.debug(`Pulling ${image} (silent — pass --verbose to stream progress)`);
+	if (!source.directory) throw options.wrapError(`DockerImageAssetSource must set either 'directory' or 'executable' (got: ${JSON.stringify(source)})`);
+	if (!options.tag) throw options.wrapError("buildDockerImage(directory mode) requires options.tag");
+	const buildArgs = buildDockerBuildCommand(source, options.tag, options.platform);
+	const contextDir = `${cdkOutDir}/${source.directory}`;
+	buildArgs.push(".");
+	logger.debug(`${getDockerCmd()} ${buildArgs.join(" ")} (cwd=${contextDir})`);
 	try {
-		await runDockerStreaming([
-			"pull",
-			...platformArgs,
-			image
-		], {
-			streamLive: false,
-			progressLabel: `Pulling ${image}`
+		await runDockerStreaming(buildArgs, {
+			cwd: contextDir,
+			env: { BUILDX_NO_DEFAULT_ATTESTATIONS: "1" },
+			...options.progressLabel !== void 0 && { progressLabel: options.progressLabel }
 		});
 	} catch (err) {
 		const e = err;
-		if (e.exitCode === void 0 || e.exitCode === null) throw new DockerRunnerError(`docker pull ${image} failed: ${e.message ?? String(err)}`);
-		const detail = e.stderr?.trim() || e.stdout?.trim() || "(no output)";
-		throw new DockerRunnerError(`docker pull ${image} exited with code ${e.exitCode}: ${detail}`);
+		throw options.wrapError(e.stderr || e.message || String(err));
 	}
+	return options.tag;
 }
 /**
-* Run the container detached. Returns the container ID.
+* Construct the `docker build` argv (without the trailing context directory).
 *
-* The caller is responsible for:
-*   - polling `host:port` for RIE readiness,
-*   - issuing the invoke,
-*   - calling `removeContainer` from a `try`/`finally` so the container
-*     is cleaned up on any error path including SIGINT.
+* Exported for unit-test inspection — keeps the flag-ordering assertions
+* independent of the spawn machinery.
 */
-async function runDetached(opts) {
+function buildDockerBuildCommand(source, tag, platformOverride) {
 	const args = [
-		"run",
-		"-d",
-		"--rm"
+		"build",
+		"--tag",
+		tag
 	];
-	if (opts.name) args.push("--name", opts.name);
-	if (opts.network) args.push("--network", opts.network);
-	if (opts.platform) args.push("--platform", opts.platform);
-	if (opts.extraHosts) for (const entry of opts.extraHosts) args.push("--add-host", `${entry.host}:${entry.ip}`);
-	const host = opts.host ?? "127.0.0.1";
-	args.push("-p", `${host}:${opts.hostPort}:${opts.containerPort ?? 8080}`);
-	if (opts.debugPort !== void 0) args.push("-p", `${host}:${opts.debugPort}:${opts.debugPort}`);
-	for (const mount of opts.mounts) {
-		const ro = mount.readOnly ? ":ro" : "";
-		args.push("-v", `${mount.hostPath}:${mount.containerPath}${ro}`);
-	}
-	if (opts.extraMounts) for (const mount of opts.extraMounts) {
-		const ro = mount.readOnly ? ":ro" : "";
-		args.push("-v", `${mount.hostPath}:${mount.containerPath}${ro}`);
-	}
-	const sensitiveKeys = opts.sensitiveEnvKeys && opts.sensitiveEnvKeys.size > 0 ? new Set([...SENSITIVE_ENV_KEYS, ...opts.sensitiveEnvKeys]) : SENSITIVE_ENV_KEYS;
-	const passthroughEnv = appendEnvFlags(args, opts.env, sensitiveKeys);
-	if (opts.tmpfs) args.push("--tmpfs", `${opts.tmpfs.target}:rw,size=${opts.tmpfs.sizeMb}m`);
-	if (opts.workingDir) args.push("--workdir", opts.workingDir);
-	let entryPointTail = [];
-	if (opts.entryPoint && opts.entryPoint.length > 0) {
-		args.push("--entrypoint", opts.entryPoint[0]);
-		entryPointTail = opts.entryPoint.slice(1);
-	}
-	args.push(opts.image, ...entryPointTail, ...opts.cmd);
-	getLogger().child("docker").debug(`${getDockerCmd()} ${redactAwsCredentialsInArgs(args).join(" ")}`);
-	try {
-		const { stdout } = await execFileAsync$5(getDockerCmd(), args, {
-			maxBuffer: 10 * 1024 * 1024,
-			...execEnvForSecrets(passthroughEnv)
-		});
-		return stdout.trim();
-	} catch (error) {
-		const err = error;
-		throw new DockerRunnerError(`docker run failed: ${err.stderr?.trim() || err.message || String(error)}`);
-	}
+	if (source.dockerBuildArgs) for (const [k, v] of Object.entries(source.dockerBuildArgs)) args.push("--build-arg", `${k}=${v}`);
+	if (source.dockerBuildContexts) for (const [k, v] of Object.entries(source.dockerBuildContexts)) args.push("--build-context", `${k}=${v}`);
+	if (source.dockerBuildSecrets) for (const [k, v] of Object.entries(source.dockerBuildSecrets)) args.push("--secret", `id=${k},${v}`);
+	if (source.dockerBuildSsh) args.push("--ssh", source.dockerBuildSsh);
+	if (source.dockerBuildTarget) args.push("--target", source.dockerBuildTarget);
+	if (source.dockerFile) args.push("--file", source.dockerFile);
+	if (source.networkMode) args.push("--network", source.networkMode);
+	const platform = platformOverride ?? source.platform;
+	if (platform) args.push("--platform", platform);
+	if (source.dockerOutputs) for (const output of source.dockerOutputs) args.push(`--output=${output}`);
+	if (source.cacheFrom) for (const c of source.cacheFrom) args.push("--cache-from", cacheOptionToFlag(c));
+	if (source.cacheTo) args.push("--cache-to", cacheOptionToFlag(source.cacheTo));
+	if (source.cacheDisabled) args.push("--no-cache");
+	return args;
+}
+function cacheOptionToFlag(option) {
+	let flag = `type=${option.type}`;
+	if (option.params) for (const [k, v] of Object.entries(option.params)) flag += `,${k}=${v}`;
+	return flag;
 }
+
+//#endregion
+//#region src/local/ecr-puller.ts
 /**
-* `docker logs -f <id>` plumbed to stdout/stderr. Returns a function that
-* stops the stream (used by the caller in a `finally` block).
+* ECR pull fallback for `cdkl invoke` / `cdkl start-api` /
+* `cdkl run-task`. When the image URI resolves to an ECR repo but
+* doesn't match any cdk.out asset (typical when invoking a stack
+* deployed elsewhere or sharing a centralized registry), cdk-local
+* authenticates against the target registry and runs `docker pull`.
+*
+* **Cross-account / cross-region** (#455):
+*   - Same-account, same-region: fast path. No STS hop. The default
+*     credential chain is used directly for `ecr:GetAuthorizationToken`.
+*   - `ecrRoleArn` is provided: `sts:AssumeRole` is issued via the
+*     default credential chain to obtain temporary credentials for the
+*     target account. The resulting credentials authenticate the ECR
+*     client (regardless of region — the ECR client is built for the
+*     URI's region, which can differ from the caller's profile region).
+*   - Cross-account, NO `ecrRoleArn`: cdk-local falls through to the
+*     default credential chain. This works when the caller has been
+*     granted cross-account `ecr:GetAuthorizationToken` +
+*     `ecr:BatchGetImage` permissions on the target repository via an
+*     IAM policy; otherwise AWS rejects the call with `AccessDenied`
+*     and the user is pointed at `--ecr-role-arn`.
+*
+* The `--no-pull` semantics (C3 in the design doc):
+*   - When NOT set: `ecrLogin` + `docker pull <uri>`.
+*   - When set: skip `docker pull`. If the image isn't in the local
+*     cache, the subsequent `docker run` will fail; we surface a clearer
+*     "image not in local cache" error here so the user knows to drop
+*     `--no-pull` or pre-pull manually.
 */
-function streamLogs(containerId) {
-	const proc = spawn(getDockerCmd(), [
-		"logs",
-		"-f",
-		containerId
-	], { stdio: [
-		"ignore",
-		"pipe",
-		"pipe"
-	] });
-	proc.stdout?.on("data", (chunk) => process.stdout.write(chunk));
-	proc.stderr?.on("data", (chunk) => process.stderr.write(chunk));
-	proc.on("error", () => {});
-	return () => {
-		if (!proc.killed) proc.kill("SIGTERM");
+/** Regex matching the `<acct>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>` shape. */
+const ECR_URI_REGEX = /^(\d{12})\.dkr\.ecr\.([^.]+)\.amazonaws\.com(?:\.cn)?\/([^:]+):(.+)$/;
+/**
+* Parse an ECR image URI. Returns `undefined` for non-ECR URIs (typically:
+* Docker Hub, public.ecr.aws, gcr.io, ...) — those are user-managed
+* images we don't try to authenticate against.
+*/
+function parseEcrUri(imageUri) {
+	const m = ECR_URI_REGEX.exec(imageUri);
+	if (!m) return void 0;
+	return {
+		accountId: m[1],
+		region: m[2],
+		repository: m[3],
+		tag: m[4]
 	};
 }
 /**
-* Best-effort `docker rm -f <id>`. Errors are swallowed (logged at debug)
-* because this typically runs from a `finally` and the parent has its own
-* error to surface.
+* Module-level cache for STS-issued AssumeRole credentials, keyed by
+* `(ecrRoleArn, callerRegion)`. Closes the reviewer's MAJOR finding: ECS
+* run-task with N containers under one `--ecr-role-arn` would otherwise issue
+* N× `AssumeRole` and N× `GetCallerIdentity` for identical credentials valid
+* for 3600s. The cache keeps a 5-minute safety margin against the recorded
+* `Expiration` so STS-side / local-clock skew never lets a stale entry through.
+*
+* Cache key is intentionally `(roleArn, region)` rather than full caller
+* identity — STS issues per-region session creds, and a switch of `--region`
+* between two `local invoke` calls in the same process must re-issue.
+*
+* NOT cleared on process exit — Node's module scope evaporates with the
+* process, and no inter-process sharing is desired (each `cdkl invoke`
+* is its own isolated runtime).
 */
-async function removeContainer(containerId) {
-	if (!containerId) return;
-	const logger = getLogger().child("docker");
-	try {
-		await execFileAsync$5(getDockerCmd(), [
-			"rm",
-			"-f",
-			containerId
-		]);
-		logger.debug(`Removed container ${containerId}`);
-	} catch (error) {
-		const err = error;
-		logger.debug(`docker rm -f ${containerId} failed: ${err.stderr || err.message || String(error)}`);
-	}
-}
+const ASSUMED_ROLE_CACHE = /* @__PURE__ */ new Map();
 /**
-* Verify the docker daemon is reachable. Surfaces a friendlier error than
-* the raw `ENOENT` / "Cannot connect to the Docker daemon" the user would
-* otherwise see at the first run call. Called once up front.
+* Module-level cache for `STS:GetCallerIdentity`. The result is identity-only
+* (`Account`) and invariant for the lifetime of the process under one set of
+* default credentials. Keyed by `callerRegion` to avoid a cross-region leak
+* when the caller flips `AWS_REGION` mid-process (STS is global but the SDK
+* uses regional endpoints; the result is invariant in practice, but we key
+* on region for safety).
 */
-async function ensureDockerAvailable() {
-	const cmd = getDockerCmd();
-	try {
-		await execFileAsync$5(cmd, [
-			"version",
-			"--format",
-			"{{.Server.Version}}"
-		]);
-	} catch (error) {
-		const err = error;
-		if (err.code === "ENOENT") throw new DockerRunnerError(`${cmd} is not installed or not on PATH. ${getEmbedConfig().cliName} invoke needs Docker (or a compatible CLI specified via CDK_DOCKER) — install it and retry.`);
-		throw new DockerRunnerError(`${cmd} daemon is not reachable: ${err.stderr?.trim() || err.message || String(error)}. Start Docker Desktop / the docker daemon and retry.`);
-	}
+const CALLER_IDENTITY_CACHE = /* @__PURE__ */ new Map();
+/** 5-minute safety margin against the recorded STS expiration timestamp. */
+const STS_CREDENTIAL_SAFETY_MARGIN_MS = 300 * 1e3;
+function isCredentialFresh(creds) {
+	if (!creds.expiration) return false;
+	return creds.expiration.getTime() - Date.now() > STS_CREDENTIAL_SAFETY_MARGIN_MS;
 }
 /**
-* Allocate a free TCP port on `127.0.0.1`. Used to pick a host port for
-* publishing the RIE :8080 endpoint without colliding with whatever else
-* the user has running. The OS assigns a port via `port: 0` and we
-* close the probe before returning so docker can bind it next.
+* Pull (or verify locally cached) a container image from ECR.
 *
-* There is a tiny race window between close and `docker run -p` — in
-* practice it's never been observed for local invoke; if it ever
-* surfaces, the caller can retry with a fresh port.
+* Auto-detects cross-account from `STS:GetCallerIdentity` and assumes
+* the supplied role when set. Returns the image URI the caller should
+* pass to `docker run` (same as the input — no rewriting).
 */
-function pickFreePort() {
-	return new Promise((resolvePort, rejectPort) => {
-		const server = createServer();
-		server.unref();
-		server.on("error", rejectPort);
-		server.listen(0, "127.0.0.1", () => {
-			const address = server.address();
-			if (!address || typeof address === "string") {
-				server.close();
-				rejectPort(/* @__PURE__ */ new Error("Could not allocate a host port"));
-				return;
-			}
-			const port = address.port;
-			server.close(() => resolvePort(port));
-		});
+async function pullEcrImage(imageUri, options) {
+	const logger = getLogger().child("ecr-puller");
+	const parsed = parseEcrUri(imageUri);
+	if (!parsed) throw new LocalInvokeBuildError(`Image URI '${imageUri}' is not an ECR URI. ${getEmbedConfig().cliName} invoke v1 only authenticates against ECR for the deployed-image fallback path.`);
+	const callerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"];
+	if (options.skipPull) {
+		logger.info(`Skipping ECR pull (--no-pull). Verifying ${imageUri} is in local cache...`);
+		await verifyImageInLocalCache(imageUri);
+		return imageUri;
+	}
+	const callerIdentityKey = `${options.profile ?? "_noprofile"}|${callerRegion ?? "_unset"}`;
+	let callerAccount = CALLER_IDENTITY_CACHE.get(callerIdentityKey);
+	if (callerAccount === void 0) {
+		const sts = new STSClient(buildStsClientConfig({
+			region: callerRegion,
+			profile: options.profile
+		}));
+		try {
+			const identity = await sts.send(new GetCallerIdentityCommand({}));
+			if (!identity.Account) throw new LocalInvokeBuildError("STS GetCallerIdentity returned no Account. Verify your AWS credentials.");
+			callerAccount = identity.Account;
+			CALLER_IDENTITY_CACHE.set(callerIdentityKey, callerAccount);
+		} finally {
+			sts.destroy();
+		}
+	}
+	const crossAccount = callerAccount !== parsed.accountId;
+	const crossRegion = callerRegion !== void 0 && callerRegion !== parsed.region;
+	let assumed;
+	if (options.ecrRoleArn) {
+		const cacheKey = `${options.profile ?? "_noprofile"}|${options.ecrRoleArn}|${callerRegion ?? "_unset"}`;
+		const cached = ASSUMED_ROLE_CACHE.get(cacheKey);
+		if (cached && isCredentialFresh(cached)) {
+			assumed = cached;
+			logger.debug(`Reusing cached AssumeRole credentials for ${options.ecrRoleArn}`);
+		} else {
+			assumed = await assumeRoleForEcr(options.ecrRoleArn, callerRegion, options.profile, logger);
+			ASSUMED_ROLE_CACHE.set(cacheKey, assumed);
+			logger.info(`Assumed role ${options.ecrRoleArn} for ECR pull (account=${parsed.accountId}, region=${parsed.region})`);
+		}
+	} else if (crossAccount) logger.info(`Cross-account ECR pull: image account ${parsed.accountId} != caller ${callerAccount}. Using the caller's credentials; pass --ecr-role-arn <arn> if AWS rejects with AccessDenied.`);
+	if (crossRegion) logger.info(`Cross-region ECR pull: image region ${parsed.region} != caller ${callerRegion ?? "(unset)"}. Authenticating against the image region directly.`);
+	const ecr = new ECRClient({
+		region: parsed.region,
+		...assumed ? { credentials: assumed } : options.profile ? { profile: options.profile } : {}
 	});
+	try {
+		await ecrLogin(ecr, parsed.accountId, parsed.region);
+	} finally {
+		ecr.destroy();
+	}
+	logger.info(`Pulling ${imageUri}...`);
+	try {
+		await runDockerForeground(["pull", imageUri]);
+	} catch (err) {
+		throw new LocalInvokeBuildError(`docker pull ${imageUri} failed: ${err.message}`);
+	}
+	return imageUri;
 }
 /**
-* Env keys whose VALUES are sensitive (AWS credentials). These are
-* routed through docker's value-from-process-env form by
-* {@link appendEnvFlags} so the value never appears in `docker run`'s
-* argv (`ps` / `/proc/<pid>/cmdline`), and they are also redacted by
-* {@link redactAwsCredentialsInArgs} as a defense for any path that
-* still emits the inline `-e <KEY>=<value>` form into the debug log.
+* Assume the supplied role via the SDK default credential chain and
+* return the resulting temporary credentials. The STS client is built
+* with the caller's profile region (or unset) — STS is a global
+* service so the region is informational, but threading it through
+* mirrors the convention used by `src/utils/role-arn.ts`.
 */
-const SENSITIVE_ENV_KEYS = new Set([
-	"AWS_ACCESS_KEY_ID",
-	"AWS_SECRET_ACCESS_KEY",
-	"AWS_SESSION_TOKEN"
-]);
+async function assumeRoleForEcr(roleArn, callerRegion, profile, logger) {
+	logger.debug(`Assuming role ${roleArn} for ECR pull...`);
+	const sts = new STSClient(buildStsClientConfig({
+		region: callerRegion,
+		profile
+	}));
+	try {
+		const creds = (await sts.send(new AssumeRoleCommand({
+			RoleArn: roleArn,
+			RoleSessionName: `${getEmbedConfig().resourceNamePrefix}-ecr-${Date.now()}`,
+			DurationSeconds: 3600
+		}))).Credentials;
+		if (!creds || !creds.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new LocalInvokeBuildError(`AssumeRole(${roleArn}) returned no usable credentials. Verify the role's trust policy allows your identity to assume it.`);
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			sessionToken: creds.SessionToken,
+			...creds.Expiration && { expiration: creds.Expiration }
+		};
+	} catch (err) {
+		if (err instanceof LocalInvokeBuildError) throw err;
+		throw new LocalInvokeBuildError(`Failed to assume role ${roleArn} for ECR pull: ${err instanceof Error ? err.message : String(err)}. Verify the role exists and its trust policy permits the caller's identity to assume it.`);
+	} finally {
+		sts.destroy();
+	}
+}
 /**
-* Append `-e` flags for `env` to `args`, routing keys in `sensitiveKeys`
-* through docker's value-from-process-env form (`-e KEY`, with NO
-* `=value`). Docker reads the value from its OWN environment at run time,
-* so the secret never lands in `docker run`'s argv — invisible to
-* `ps aux` / `/proc/<pid>/cmdline` (other users on a shared host) and to
-* shell history. Non-sensitive keys keep the inline `-e KEY=VALUE` form
-* (fine for non-secret config, and keeps `--debug` output readable).
-*
-* Returns the `{ KEY: value }` map of routed-through keys; the caller MUST
-* merge it into the spawned docker process's `env` (see
-* {@link execEnvForSecrets}) so docker can resolve each passed-through
-* key. Values still appear in `docker inspect` Config.Env — that is
-* inherent to container env and matches production behavior.
-*
-* Unlike `--env-file`, this handles multi-line values (e.g. PEM secrets)
-* and needs no temp file on disk.
+* Authenticate the local docker daemon against the target ECR registry.
+* Self-contained in this module so the local-invoke path stays
+* independent of any full asset-publish path's larger surface area.
 */
-function appendEnvFlags(args, env, sensitiveKeys) {
-	const passthrough = {};
-	for (const [k, v] of Object.entries(env)) if (sensitiveKeys.has(k)) {
-		args.push("-e", k);
-		passthrough[k] = v;
-	} else args.push("-e", `${k}=${v}`);
-	return passthrough;
+async function ecrLogin(client, accountId, region) {
+	getLogger().child("ecr-puller").debug(`ECR login (account=${accountId}, region=${region})`);
+	const authData = (await client.send(new GetAuthorizationTokenCommand({}))).authorizationData?.[0];
+	if (!authData?.authorizationToken) throw new LocalInvokeBuildError("Failed to get ECR authorization token");
+	const [username, password] = Buffer.from(authData.authorizationToken, "base64").toString().split(":");
+	if (!username || password === void 0) throw new LocalInvokeBuildError("ECR authorization token has unexpected shape (missing username/password)");
+	const endpoint = authData.proxyEndpoint || `https://${accountId}.dkr.ecr.${region}.amazonaws.com`;
+	try {
+		await runDockerStreaming([
+			"login",
+			"--username",
+			username,
+			"--password-stdin",
+			endpoint
+		], { input: password });
+	} catch (err) {
+		const e = err;
+		throw new LocalInvokeBuildError(`ECR login failed: ${formatDockerLoginError(e.stderr || e.message || String(err), endpoint)}`);
+	}
 }
 /**
-* Build the `env` option for an `execFile` / `spawn` call that runs a
-* `docker run` whose args include passed-through sensitive keys (from
-* {@link appendEnvFlags}). Returns `{ env: {...process.env, ...passthrough} }`
-* so docker inherits the normal environment PLUS the sensitive values it
-* must resolve, or `{}` when there is nothing to pass through (preserving
-* the default inherited-environment behavior).
+* `docker image inspect <uri>` returns non-zero when the image is not in
+* the local cache. Surface a clearer error than docker's raw output so
+* the user knows the `--no-pull` path requires a pre-cached image.
 */
-function execEnvForSecrets(passthrough) {
-	if (Object.keys(passthrough).length === 0) return {};
-	return { env: {
-		...process.env,
-		...passthrough
-	} };
+async function verifyImageInLocalCache(imageUri) {
+	try {
+		await runDockerStreaming([
+			"image",
+			"inspect",
+			imageUri
+		]);
+	} catch {
+		throw new LocalInvokeBuildError(`Image '${imageUri}' is not in the local docker cache and --no-pull was set. Either remove --no-pull (${getEmbedConfig().productName} will pull from ECR) or pre-pull the image manually with \`docker pull\`.`);
+	}
 }
 /**
-* Returns a copy of `args` with any `-e <KEY>=<value>` pair whose KEY is
-* in {@link SENSITIVE_ENV_KEYS} replaced with `-e <KEY>=***`. The actual
-* `args` passed to `spawn` are never mutated — this is for log output
-* only. With {@link appendEnvFlags} routing credentials through the
-* value-less `-e KEY` form this rarely fires, but it stays as defense for
-* any inline-form credential that slips into a logged command.
+* Check whether a docker image is in the local registry. Pure boolean —
+* the caller decides what message to surface on miss. Reused by the
+* `docker-image-builder` `--no-build` path so both the ECR-pull verifier
+* (above) and the local-build verifier route through one `docker image
+* inspect` shape.
 */
-function redactAwsCredentialsInArgs(args) {
-	const out = [];
-	for (let i = 0; i < args.length; i++) {
-		const cur = args[i];
-		const next = args[i + 1];
-		if (cur === "-e" && typeof next === "string") {
-			const eqIdx = next.indexOf("=");
-			if (eqIdx > 0) {
-				const key = next.substring(0, eqIdx);
-				if (SENSITIVE_ENV_KEYS.has(key)) {
-					out.push("-e", `${key}=***`);
-					i++;
-					continue;
-				}
-			}
-		}
-		out.push(cur);
+async function isImageInLocalCache(imageRef) {
+	try {
+		await runDockerStreaming([
+			"image",
+			"inspect",
+			imageRef
+		]);
+		return true;
+	} catch {
+		return false;
 	}
-	return out;
 }
 
 //#endregion
-//#region src/assets/docker-build.ts
+//#region src/local/docker-image-builder.ts
 /**
-* Build a Docker image from a CDK asset source. Returns the local image
-* tag the caller should use for `docker tag` / `docker push` (publisher)
-* or `docker run` (local-invoke).
-*
-* Two source modes (mirrors CDK CLI):
-*   - `executable`: run the user-supplied command, capture stdout, return
-*     it as the local tag. The script is responsible for building AND
-*     tagging; cdk-local just reads the tag from stdout. Used for Bazel /
-*     custom build pipelines that produce images outside `docker build`.
-*   - `directory`: standard `docker build <dir>` with the full BuildKit
-*     flag set described above. Caller must pass `options.tag`.
+* Build a Lambda container image from a CDK asset entry. Returns the
+* local image tag the caller should pass to `docker run`.
 *
-* `executable` takes precedence when both fields are set (matches CDK CLI).
+* When `options.noBuild` is set, skips `docker build` entirely and
+* verifies the deterministic local tag is already in the docker
+* registry; throws `LocalInvokeBuildError` with an actionable message
+* when the tag is missing.
 */
-async function buildDockerImage(asset, cdkOutDir, options) {
-	const source = asset.source;
-	const logger = getLogger().child("docker-build");
-	if (source.executable && source.executable.length > 0) {
-		const [cmd, ...args] = source.executable;
-		if (!cmd) throw options.wrapError("asset source.executable[] is empty");
-		const cwd = source.directory ? `${cdkOutDir}/${source.directory}` : cdkOutDir;
-		logger.debug(`Building Docker image via executable: ${source.executable.join(" ")} (cwd=${cwd})`);
-		let result;
+async function buildContainerImage(asset, cdkOutDir, options) {
+	const tag = computeLocalTag(asset.source);
+	const platform = architectureToPlatform(options.architecture);
+	const logger = getLogger().child("local-invoke-build");
+	if (options.noBuild === true) {
+		logger.info(`Skipping docker build (--no-build). Verifying ${tag} is in local registry...`);
+		if (!await isImageInLocalCache(tag)) throw new LocalInvokeBuildError(`image '${tag}' not in local registry and --no-build is set; remove --no-build or run \`docker build\` manually first.`);
+		logger.debug(`Local tag ${tag} is cached; skipping build.`);
+		return tag;
+	}
+	logger.info(`Building container image (platform=${platform})...`);
+	logger.debug(`Local tag: ${tag}`);
+	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}`),
+		progressLabel: `Building container image (platform=${platform})`
+	});
+	if (actualTag !== tag) {
+		logger.debug(`Re-tagging executable-built image '${actualTag}' → '${tag}'`);
 		try {
-			result = await spawnStreaming(cmd, args, { cwd });
+			await runDockerStreaming([
+				"tag",
+				actualTag,
+				tag
+			]);
 		} catch (err) {
 			const e = err;
-			throw options.wrapError(e.stderr || e.message || String(err));
+			throw new LocalInvokeBuildError(`docker tag failed re-tagging '${actualTag}' → '${tag}': ${e.stderr?.trim() || e.message || String(err)}`);
 		}
-		const tag = result.stdout.trim();
-		if (!tag) throw options.wrapError(`docker build executable produced no output (expected the local image tag on stdout): ${cmd} ${args.join(" ")}`);
-		return tag;
 	}
-	if (!source.directory) throw options.wrapError(`DockerImageAssetSource must set either 'directory' or 'executable' (got: ${JSON.stringify(source)})`);
-	if (!options.tag) throw options.wrapError("buildDockerImage(directory mode) requires options.tag");
-	const buildArgs = buildDockerBuildCommand(source, options.tag, options.platform);
-	const contextDir = `${cdkOutDir}/${source.directory}`;
-	buildArgs.push(".");
-	logger.debug(`${getDockerCmd()} ${buildArgs.join(" ")} (cwd=${contextDir})`);
-	try {
-		await runDockerStreaming(buildArgs, {
-			cwd: contextDir,
-			env: { BUILDX_NO_DEFAULT_ATTESTATIONS: "1" },
-			...options.progressLabel !== void 0 && { progressLabel: options.progressLabel }
-		});
-	} catch (err) {
-		const e = err;
-		throw options.wrapError(e.stderr || e.message || String(err));
-	}
-	return options.tag;
+	return tag;
 }
 /**
-* Construct the `docker build` argv (without the trailing context directory).
+* Translate Lambda's `Architectures` enum to a Docker `--platform` value.
 *
-* Exported for unit-test inspection — keeps the flag-ordering assertions
-* independent of the spawn machinery.
+* Critical bug fix C2 from the design doc — without this the build /
+* run step uses the host's default arch, which races on M1/M2 Macs
+* (arm64 host) with x86_64 Lambdas. Threaded into BOTH the build (here)
+* and the run path (`docker-runner.runDetached`).
 */
-function buildDockerBuildCommand(source, tag, platformOverride) {
-	const args = [
-		"build",
-		"--tag",
-		tag
-	];
-	if (source.dockerBuildArgs) for (const [k, v] of Object.entries(source.dockerBuildArgs)) args.push("--build-arg", `${k}=${v}`);
-	if (source.dockerBuildContexts) for (const [k, v] of Object.entries(source.dockerBuildContexts)) args.push("--build-context", `${k}=${v}`);
-	if (source.dockerBuildSecrets) for (const [k, v] of Object.entries(source.dockerBuildSecrets)) args.push("--secret", `id=${k},${v}`);
-	if (source.dockerBuildSsh) args.push("--ssh", source.dockerBuildSsh);
-	if (source.dockerBuildTarget) args.push("--target", source.dockerBuildTarget);
-	if (source.dockerFile) args.push("--file", source.dockerFile);
-	if (source.networkMode) args.push("--network", source.networkMode);
-	const platform = platformOverride ?? source.platform;
-	if (platform) args.push("--platform", platform);
-	if (source.dockerOutputs) for (const output of source.dockerOutputs) args.push(`--output=${output}`);
-	if (source.cacheFrom) for (const c of source.cacheFrom) args.push("--cache-from", cacheOptionToFlag(c));
-	if (source.cacheTo) args.push("--cache-to", cacheOptionToFlag(source.cacheTo));
-	if (source.cacheDisabled) args.push("--no-cache");
-	return args;
+function architectureToPlatform(architecture) {
+	return architecture === "arm64" ? "linux/arm64" : "linux/amd64";
 }
-function cacheOptionToFlag(option) {
-	let flag = `type=${option.type}`;
-	if (option.params) for (const [k, v] of Object.entries(option.params)) flag += `,${k}=${v}`;
-	return flag;
+/**
+* The Docker `--platform` value matching the host CPU arch.
+*
+* `process.arch` is `arm64` on Apple Silicon and `x64` on Intel/amd64
+* hosts; everything else is treated as amd64 for the purpose of the
+* emulation comparison (the only two `--platform` values cdk-local emits
+* are `linux/arm64` / `linux/amd64`).
+*/
+function hostPlatform() {
+	return process.arch === "arm64" ? "linux/arm64" : "linux/amd64";
 }
-
-//#endregion
-//#region src/local/ecr-puller.ts
+/** Process-global dedupe so a warm pool / per-request boot warns once per arch. */
+const warnedEmulatedPlatforms = /* @__PURE__ */ new Set();
 /**
-* ECR pull fallback for `cdkl invoke` / `cdkl start-api` /
-* `cdkl run-task`. When the image URI resolves to an ECR repo but
-* doesn't match any cdk.out asset (typical when invoking a stack
-* deployed elsewhere or sharing a centralized registry), cdk-local
-* authenticates against the target registry and runs `docker pull`.
+* Warn once per process when a container is about to run at a `--platform`
+* whose CPU arch differs from the host's — i.e. it will run under CPU
+* emulation.
 *
-* **Cross-account / cross-region** (#455):
-*   - Same-account, same-region: fast path. No STS hop. The default
-*     credential chain is used directly for `ecr:GetAuthorizationToken`.
-*   - `ecrRoleArn` is provided: `sts:AssumeRole` is issued via the
-*     default credential chain to obtain temporary credentials for the
-*     target account. The resulting credentials authenticate the ECR
-*     client (regardless of region — the ECR client is built for the
-*     URI's region, which can differ from the caller's profile region).
-*   - Cross-account, NO `ecrRoleArn`: cdk-local falls through to the
-*     default credential chain. This works when the caller has been
-*     granted cross-account `ecr:GetAuthorizationToken` +
-*     `ecr:BatchGetImage` permissions on the target repository via an
-*     IAM policy; otherwise AWS rejects the call with `AccessDenied`
-*     and the user is pointed at `--ecr-role-arn`.
+* The arch is chosen automatically from the function's declared
+* `Architectures`, so the user gets no signal that emulation is in play
+* until a container dies. Emulated containers usually run fine, but some
+* compiled custom-runtime binaries (notably a Swift `provided.*`
+* bootstrap) crash under emulation with `exec format error` or
+* `illegal instruction`, which is opaque without this hint. Surface the
+* two real fixes: enable Rosetta for x86/amd64 emulation in the Docker
+* engine settings, or build the function for the host arch.
 *
-* The `--no-pull` semantics (C3 in the design doc):
-*   - When NOT set: `ecrLogin` + `docker pull <uri>`.
-*   - When set: skip `docker pull`. If the image isn't in the local
-*     cache, the subsequent `docker run` will fail; we surface a clearer
-*     "image not in local cache" error here so the user knows to drop
-*     `--no-pull` or pre-pull manually.
+* Deduped by target platform so a warm pool / per-request boot doesn't
+* spam. `platform` is the resolved `--platform` value (`undefined` =>
+* docker picks the host arch, so there is nothing to warn about).
 */
-/** Regex matching the `<acct>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>` shape. */
-const ECR_URI_REGEX = /^(\d{12})\.dkr\.ecr\.([^.]+)\.amazonaws\.com(?:\.cn)?\/([^:]+):(.+)$/;
+function warnIfEmulatedPlatform(platform, opts = {}) {
+	if (!platform) return;
+	const host = hostPlatform();
+	if (platform === host) return;
+	if (warnedEmulatedPlatforms.has(platform)) return;
+	warnedEmulatedPlatforms.add(platform);
+	const logger = opts.logger ?? getLogger();
+	const what = opts.label ? `'${opts.label}' ` : "";
+	logger.warn(`Running ${what}under ${platform} emulation on a ${host} host. Emulated containers can crash some compiled custom-runtime binaries (e.g. a Swift 'provided.*' bootstrap) with 'exec format error' or 'illegal instruction'. If you hit that, enable Rosetta for x86/amd64 emulation in your Docker engine settings, or build the function for ${host}.`);
+}
 /**
-* Parse an ECR image URI. Returns `undefined` for non-ECR URIs (typically:
-* Docker Hub, public.ecr.aws, gcr.io, ...) — those are user-managed
-* images we don't try to authenticate against.
+* Build a stable local tag derived from the asset's build context.
+*
+* Fingerprints every field that affects the produced image so an iteration
+* that doesn't change those fields hits Docker's layer cache; an iteration
+* that DOES change them gets a fresh tag (the old tag stays around in
+* `docker images` but harmlessly). The fingerprint covers the full CDK
+* `DockerImageSource` schema so `dockerBuildSecrets` / `dockerBuildContexts`
+* / `cacheFrom` / etc. changes also bust the local cache as expected.
 */
-function parseEcrUri(imageUri) {
-	const m = ECR_URI_REGEX.exec(imageUri);
-	if (!m) return void 0;
-	return {
-		accountId: m[1],
-		region: m[2],
-		repository: m[3],
-		tag: m[4]
-	};
+function computeLocalTag(source) {
+	const hash = createHash("sha256");
+	pushField(hash, "directory", source.directory ?? "");
+	pushField(hash, "executable", (source.executable ?? []).join(" "));
+	pushField(hash, "dockerFile", source.dockerFile ?? "");
+	pushField(hash, "dockerBuildTarget", source.dockerBuildTarget ?? "");
+	pushField(hash, "networkMode", source.networkMode ?? "");
+	pushField(hash, "platform", source.platform ?? "");
+	pushField(hash, "dockerBuildSsh", source.dockerBuildSsh ?? "");
+	pushField(hash, "cacheDisabled", source.cacheDisabled ? "1" : "0");
+	pushMap(hash, "dockerBuildArgs", source.dockerBuildArgs);
+	pushMap(hash, "dockerBuildContexts", source.dockerBuildContexts);
+	pushMap(hash, "dockerBuildSecrets", source.dockerBuildSecrets);
+	pushField(hash, "dockerOutputs", (source.dockerOutputs ?? []).join(""));
+	pushField(hash, "cacheFrom", (source.cacheFrom ?? []).map((o) => JSON.stringify(o)).join(""));
+	pushField(hash, "cacheTo", source.cacheTo ? JSON.stringify(source.cacheTo) : "");
+	return `${getEmbedConfig().resourceNamePrefix}-invoke-${hash.digest("hex").slice(0, 16)}`;
+}
+function pushField(hash, name, value) {
+	hash.update(name);
+	hash.update("=");
+	hash.update(value);
+	hash.update("\0");
+}
+function pushMap(hash, name, value) {
+	hash.update(name);
+	hash.update("={");
+	if (value) for (const [k, v] of Object.entries(value)) {
+		hash.update(k);
+		hash.update("=");
+		hash.update(v);
+		hash.update(";");
+	}
+	hash.update("}\0");
 }
+
+//#endregion
+//#region src/local/docker-runner.ts
+const execFileAsync$5 = promisify(execFile);
 /**
-* Module-level cache for STS-issued AssumeRole credentials, keyed by
-* `(ecrRoleArn, callerRegion)`. Closes the reviewer's MAJOR finding: ECS
-* run-task with N containers under one `--ecr-role-arn` would otherwise issue
-* N× `AssumeRole` and N× `GetCallerIdentity` for identical credentials valid
-* for 3600s. The cache keeps a 5-minute safety margin against the recorded
-* `Expiration` so STS-side / local-clock skew never lets a stale entry through.
-*
-* Cache key is intentionally `(roleArn, region)` rather than full caller
-* identity — STS issues per-region session creds, and a switch of `--region`
-* between two `local invoke` calls in the same process must re-issue.
+* Wraps `docker pull` / `docker run` / `docker rm` for `cdkl invoke`.
 *
-* NOT cleared on process exit — Node's module scope evaporates with the
-* process, and no inter-process sharing is desired (each `cdkl invoke`
-* is its own isolated runtime).
-*/
-const ASSUMED_ROLE_CACHE = /* @__PURE__ */ new Map();
-/**
-* Module-level cache for `STS:GetCallerIdentity`. The result is identity-only
-* (`Account`) and invariant for the lifetime of the process under one set of
-* default credentials. Keyed by `callerRegion` to avoid a cross-region leak
-* when the caller flips `AWS_REGION` mid-process (STS is global but the SDK
-* uses regional endpoints; the result is invariant in practice, but we key
-* on region for safety).
+* Mirrors the style of `src/assets/docker-asset-publisher.ts` (execFile for
+* one-shot calls, spawn for long-running ones). Kept as a separate file so
+* the command layer's wiring stays small; PR 5 (container Lambda) is
+* expected to add a second non-build call site, at which point the
+* common surface can be lifted into a shared helper.
 */
-const CALLER_IDENTITY_CACHE = /* @__PURE__ */ new Map();
-/** 5-minute safety margin against the recorded STS expiration timestamp. */
-const STS_CREDENTIAL_SAFETY_MARGIN_MS = 300 * 1e3;
-function isCredentialFresh(creds) {
-	if (!creds.expiration) return false;
-	return creds.expiration.getTime() - Date.now() > STS_CREDENTIAL_SAFETY_MARGIN_MS;
-}
+var DockerRunnerError = class DockerRunnerError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DockerRunnerError";
+		Object.setPrototypeOf(this, DockerRunnerError.prototype);
+	}
+};
 /**
-* Pull (or verify locally cached) a container image from ECR.
+* Pull the image. No-op when `skipPull` is true.
 *
-* Auto-detects cross-account from `STS:GetCallerIdentity` and assumes
-* the supplied role when set. Returns the image URI the caller should
-* pass to `docker run` (same as the input — no rewriting).
+* In verbose mode (`--verbose` / global log level `debug`), streams the
+* full `docker pull` progress to stdout so the user sees per-layer
+* downloads. In the default compact mode the call is silent (cached
+* images are the common case; a fresh pull still shows progress only
+* via `--verbose`). Errors are always surfaced: the captured stderr is
+* folded into the thrown `DockerRunnerError` message.
 */
-async function pullEcrImage(imageUri, options) {
-	const logger = getLogger().child("ecr-puller");
-	const parsed = parseEcrUri(imageUri);
-	if (!parsed) throw new LocalInvokeBuildError(`Image URI '${imageUri}' is not an ECR URI. ${getEmbedConfig().cliName} invoke v1 only authenticates against ECR for the deployed-image fallback path.`);
-	const callerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"];
-	if (options.skipPull) {
-		logger.info(`Skipping ECR pull (--no-pull). Verifying ${imageUri} is in local cache...`);
-		await verifyImageInLocalCache(imageUri);
-		return imageUri;
+async function pullImage(image, skipPull, platform) {
+	const logger = getLogger().child("docker");
+	if (skipPull) {
+		logger.debug(`Skipping docker pull for ${image} (--no-pull)`);
+		return;
 	}
-	const callerIdentityKey = `${options.profile ?? "_noprofile"}|${callerRegion ?? "_unset"}`;
-	let callerAccount = CALLER_IDENTITY_CACHE.get(callerIdentityKey);
-	if (callerAccount === void 0) {
-		const sts = new STSClient(buildStsClientConfig({
-			region: callerRegion,
-			profile: options.profile
-		}));
+	const platformArgs = platform ? ["--platform", platform] : [];
+	if (getLogger().getLevel() === "debug") {
+		logger.info(`Pulling ${image}${platform ? ` (${platform})` : ""}...`);
 		try {
-			const identity = await sts.send(new GetCallerIdentityCommand({}));
-			if (!identity.Account) throw new LocalInvokeBuildError("STS GetCallerIdentity returned no Account. Verify your AWS credentials.");
-			callerAccount = identity.Account;
-			CALLER_IDENTITY_CACHE.set(callerIdentityKey, callerAccount);
-		} finally {
-			sts.destroy();
-		}
-	}
-	const crossAccount = callerAccount !== parsed.accountId;
-	const crossRegion = callerRegion !== void 0 && callerRegion !== parsed.region;
-	let assumed;
-	if (options.ecrRoleArn) {
-		const cacheKey = `${options.profile ?? "_noprofile"}|${options.ecrRoleArn}|${callerRegion ?? "_unset"}`;
-		const cached = ASSUMED_ROLE_CACHE.get(cacheKey);
-		if (cached && isCredentialFresh(cached)) {
-			assumed = cached;
-			logger.debug(`Reusing cached AssumeRole credentials for ${options.ecrRoleArn}`);
-		} else {
-			assumed = await assumeRoleForEcr(options.ecrRoleArn, callerRegion, options.profile, logger);
-			ASSUMED_ROLE_CACHE.set(cacheKey, assumed);
-			logger.info(`Assumed role ${options.ecrRoleArn} for ECR pull (account=${parsed.accountId}, region=${parsed.region})`);
+			await runDockerForeground([
+				"pull",
+				...platformArgs,
+				image
+			]);
+		} catch (err) {
+			throw new DockerRunnerError(`docker pull ${image} failed: ${err.message}`);
 		}
-	} else if (crossAccount) logger.info(`Cross-account ECR pull: image account ${parsed.accountId} != caller ${callerAccount}. Using the caller's credentials; pass --ecr-role-arn <arn> if AWS rejects with AccessDenied.`);
-	if (crossRegion) logger.info(`Cross-region ECR pull: image region ${parsed.region} != caller ${callerRegion ?? "(unset)"}. Authenticating against the image region directly.`);
-	const ecr = new ECRClient({
-		region: parsed.region,
-		...assumed ? { credentials: assumed } : options.profile ? { profile: options.profile } : {}
-	});
-	try {
-		await ecrLogin(ecr, parsed.accountId, parsed.region);
-	} finally {
-		ecr.destroy();
+		return;
 	}
-	logger.info(`Pulling ${imageUri}...`);
+	logger.debug(`Pulling ${image} (silent — pass --verbose to stream progress)`);
 	try {
-		await runDockerForeground(["pull", imageUri]);
+		await runDockerStreaming([
+			"pull",
+			...platformArgs,
+			image
+		], {
+			streamLive: false,
+			progressLabel: `Pulling ${image}`
+		});
 	} catch (err) {
-		throw new LocalInvokeBuildError(`docker pull ${imageUri} failed: ${err.message}`);
+		const e = err;
+		if (e.exitCode === void 0 || e.exitCode === null) throw new DockerRunnerError(`docker pull ${image} failed: ${e.message ?? String(err)}`);
+		const detail = e.stderr?.trim() || e.stdout?.trim() || "(no output)";
+		throw new DockerRunnerError(`docker pull ${image} exited with code ${e.exitCode}: ${detail}`);
 	}
-	return imageUri;
 }
 /**
-* Assume the supplied role via the SDK default credential chain and
-* return the resulting temporary credentials. The STS client is built
-* with the caller's profile region (or unset) — STS is a global
-* service so the region is informational, but threading it through
-* mirrors the convention used by `src/utils/role-arn.ts`.
+* Run the container detached. Returns the container ID.
+*
+* The caller is responsible for:
+*   - polling `host:port` for RIE readiness,
+*   - issuing the invoke,
+*   - calling `removeContainer` from a `try`/`finally` so the container
+*     is cleaned up on any error path including SIGINT.
 */
-async function assumeRoleForEcr(roleArn, callerRegion, profile, logger) {
-	logger.debug(`Assuming role ${roleArn} for ECR pull...`);
-	const sts = new STSClient(buildStsClientConfig({
-		region: callerRegion,
-		profile
-	}));
+async function runDetached(opts) {
+	const args = [
+		"run",
+		"-d",
+		"--rm"
+	];
+	if (opts.name) args.push("--name", opts.name);
+	if (opts.network) args.push("--network", opts.network);
+	if (opts.platform) {
+		args.push("--platform", opts.platform);
+		warnIfEmulatedPlatform(opts.platform, opts.name ? { label: opts.name } : {});
+	}
+	if (opts.extraHosts) for (const entry of opts.extraHosts) args.push("--add-host", `${entry.host}:${entry.ip}`);
+	const host = opts.host ?? "127.0.0.1";
+	args.push("-p", `${host}:${opts.hostPort}:${opts.containerPort ?? 8080}`);
+	if (opts.debugPort !== void 0) args.push("-p", `${host}:${opts.debugPort}:${opts.debugPort}`);
+	for (const mount of opts.mounts) {
+		const ro = mount.readOnly ? ":ro" : "";
+		args.push("-v", `${mount.hostPath}:${mount.containerPath}${ro}`);
+	}
+	if (opts.extraMounts) for (const mount of opts.extraMounts) {
+		const ro = mount.readOnly ? ":ro" : "";
+		args.push("-v", `${mount.hostPath}:${mount.containerPath}${ro}`);
+	}
+	const sensitiveKeys = opts.sensitiveEnvKeys && opts.sensitiveEnvKeys.size > 0 ? new Set([...SENSITIVE_ENV_KEYS, ...opts.sensitiveEnvKeys]) : SENSITIVE_ENV_KEYS;
+	const passthroughEnv = appendEnvFlags(args, opts.env, sensitiveKeys);
+	if (opts.tmpfs) args.push("--tmpfs", `${opts.tmpfs.target}:rw,size=${opts.tmpfs.sizeMb}m`);
+	if (opts.workingDir) args.push("--workdir", opts.workingDir);
+	let entryPointTail = [];
+	if (opts.entryPoint && opts.entryPoint.length > 0) {
+		args.push("--entrypoint", opts.entryPoint[0]);
+		entryPointTail = opts.entryPoint.slice(1);
+	}
+	args.push(opts.image, ...entryPointTail, ...opts.cmd);
+	getLogger().child("docker").debug(`${getDockerCmd()} ${redactAwsCredentialsInArgs(args).join(" ")}`);
 	try {
-		const creds = (await sts.send(new AssumeRoleCommand({
-			RoleArn: roleArn,
-			RoleSessionName: `${getEmbedConfig().resourceNamePrefix}-ecr-${Date.now()}`,
-			DurationSeconds: 3600
-		}))).Credentials;
-		if (!creds || !creds.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new LocalInvokeBuildError(`AssumeRole(${roleArn}) returned no usable credentials. Verify the role's trust policy allows your identity to assume it.`);
-		return {
-			accessKeyId: creds.AccessKeyId,
-			secretAccessKey: creds.SecretAccessKey,
-			sessionToken: creds.SessionToken,
-			...creds.Expiration && { expiration: creds.Expiration }
-		};
-	} catch (err) {
-		if (err instanceof LocalInvokeBuildError) throw err;
-		throw new LocalInvokeBuildError(`Failed to assume role ${roleArn} for ECR pull: ${err instanceof Error ? err.message : String(err)}. Verify the role exists and its trust policy permits the caller's identity to assume it.`);
-	} finally {
-		sts.destroy();
+		const { stdout } = await execFileAsync$5(getDockerCmd(), args, {
+			maxBuffer: 10 * 1024 * 1024,
+			...execEnvForSecrets(passthroughEnv)
+		});
+		return stdout.trim();
+	} catch (error) {
+		const err = error;
+		throw new DockerRunnerError(`docker run failed: ${err.stderr?.trim() || err.message || String(error)}`);
 	}
 }
 /**
-* Authenticate the local docker daemon against the target ECR registry.
-* Self-contained in this module so the local-invoke path stays
-* independent of any full asset-publish path's larger surface area.
+* `docker logs -f <id>` plumbed to stdout/stderr. Returns a function that
+* stops the stream (used by the caller in a `finally` block).
 */
-async function ecrLogin(client, accountId, region) {
-	getLogger().child("ecr-puller").debug(`ECR login (account=${accountId}, region=${region})`);
-	const authData = (await client.send(new GetAuthorizationTokenCommand({}))).authorizationData?.[0];
-	if (!authData?.authorizationToken) throw new LocalInvokeBuildError("Failed to get ECR authorization token");
-	const [username, password] = Buffer.from(authData.authorizationToken, "base64").toString().split(":");
-	if (!username || password === void 0) throw new LocalInvokeBuildError("ECR authorization token has unexpected shape (missing username/password)");
-	const endpoint = authData.proxyEndpoint || `https://${accountId}.dkr.ecr.${region}.amazonaws.com`;
-	try {
-		await runDockerStreaming([
-			"login",
-			"--username",
-			username,
-			"--password-stdin",
-			endpoint
-		], { input: password });
-	} catch (err) {
-		const e = err;
-		throw new LocalInvokeBuildError(`ECR login failed: ${formatDockerLoginError(e.stderr || e.message || String(err), endpoint)}`);
-	}
+function streamLogs(containerId) {
+	const proc = spawn(getDockerCmd(), [
+		"logs",
+		"-f",
+		containerId
+	], { stdio: [
+		"ignore",
+		"pipe",
+		"pipe"
+	] });
+	proc.stdout?.on("data", (chunk) => process.stdout.write(chunk));
+	proc.stderr?.on("data", (chunk) => process.stderr.write(chunk));
+	proc.on("error", () => {});
+	return () => {
+		if (!proc.killed) proc.kill("SIGTERM");
+	};
 }
 /**
-* `docker image inspect <uri>` returns non-zero when the image is not in
-* the local cache. Surface a clearer error than docker's raw output so
-* the user knows the `--no-pull` path requires a pre-cached image.
+* Best-effort `docker rm -f <id>`. Errors are swallowed (logged at debug)
+* because this typically runs from a `finally` and the parent has its own
+* error to surface.
 */
-async function verifyImageInLocalCache(imageUri) {
+async function removeContainer(containerId) {
+	if (!containerId) return;
+	const logger = getLogger().child("docker");
 	try {
-		await runDockerStreaming([
-			"image",
-			"inspect",
-			imageUri
+		await execFileAsync$5(getDockerCmd(), [
+			"rm",
+			"-f",
+			containerId
 		]);
-	} catch {
-		throw new LocalInvokeBuildError(`Image '${imageUri}' is not in the local docker cache and --no-pull was set. Either remove --no-pull (${getEmbedConfig().productName} will pull from ECR) or pre-pull the image manually with \`docker pull\`.`);
+		logger.debug(`Removed container ${containerId}`);
+	} catch (error) {
+		const err = error;
+		logger.debug(`docker rm -f ${containerId} failed: ${err.stderr || err.message || String(error)}`);
 	}
 }
 /**
-* Check whether a docker image is in the local registry. Pure boolean —
-* the caller decides what message to surface on miss. Reused by the
-* `docker-image-builder` `--no-build` path so both the ECR-pull verifier
-* (above) and the local-build verifier route through one `docker image
-* inspect` shape.
+* Verify the docker daemon is reachable. Surfaces a friendlier error than
+* the raw `ENOENT` / "Cannot connect to the Docker daemon" the user would
+* otherwise see at the first run call. Called once up front.
 */
-async function isImageInLocalCache(imageRef) {
+async function ensureDockerAvailable() {
+	const cmd = getDockerCmd();
 	try {
-		await runDockerStreaming([
-			"image",
-			"inspect",
-			imageRef
+		await execFileAsync$5(cmd, [
+			"version",
+			"--format",
+			"{{.Server.Version}}"
 		]);
-		return true;
-	} catch {
-		return false;
+	} catch (error) {
+		const err = error;
+		if (err.code === "ENOENT") throw new DockerRunnerError(`${cmd} is not installed or not on PATH. ${getEmbedConfig().cliName} invoke needs Docker (or a compatible CLI specified via CDK_DOCKER) — install it and retry.`);
+		throw new DockerRunnerError(`${cmd} daemon is not reachable: ${err.stderr?.trim() || err.message || String(error)}. Start Docker Desktop / the docker daemon and retry.`);
 	}
 }
-
-//#endregion
-//#region src/local/docker-image-builder.ts
 /**
-* Build a Lambda container image from a CDK asset entry. Returns the
-* local image tag the caller should pass to `docker run`.
+* Allocate a free TCP port on `127.0.0.1`. Used to pick a host port for
+* publishing the RIE :8080 endpoint without colliding with whatever else
+* the user has running. The OS assigns a port via `port: 0` and we
+* close the probe before returning so docker can bind it next.
 *
-* When `options.noBuild` is set, skips `docker build` entirely and
-* verifies the deterministic local tag is already in the docker
-* registry; throws `LocalInvokeBuildError` with an actionable message
-* when the tag is missing.
+* There is a tiny race window between close and `docker run -p` — in
+* practice it's never been observed for local invoke; if it ever
+* surfaces, the caller can retry with a fresh port.
 */
-async function buildContainerImage(asset, cdkOutDir, options) {
-	const tag = computeLocalTag(asset.source);
-	const platform = architectureToPlatform(options.architecture);
-	const logger = getLogger().child("local-invoke-build");
-	if (options.noBuild === true) {
-		logger.info(`Skipping docker build (--no-build). Verifying ${tag} is in local registry...`);
-		if (!await isImageInLocalCache(tag)) throw new LocalInvokeBuildError(`image '${tag}' not in local registry and --no-build is set; remove --no-build or run \`docker build\` manually first.`);
-		logger.debug(`Local tag ${tag} is cached; skipping build.`);
-		return tag;
-	}
-	logger.info(`Building container image (platform=${platform})...`);
-	logger.debug(`Local tag: ${tag}`);
-	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}`),
-		progressLabel: `Building container image (platform=${platform})`
+function pickFreePort() {
+	return new Promise((resolvePort, rejectPort) => {
+		const server = createServer();
+		server.unref();
+		server.on("error", rejectPort);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			if (!address || typeof address === "string") {
+				server.close();
+				rejectPort(/* @__PURE__ */ new Error("Could not allocate a host port"));
+				return;
+			}
+			const port = address.port;
+			server.close(() => resolvePort(port));
+		});
 	});
-	if (actualTag !== tag) {
-		logger.debug(`Re-tagging executable-built image '${actualTag}' → '${tag}'`);
-		try {
-			await runDockerStreaming([
-				"tag",
-				actualTag,
-				tag
-			]);
-		} catch (err) {
-			const e = err;
-			throw new LocalInvokeBuildError(`docker tag failed re-tagging '${actualTag}' → '${tag}': ${e.stderr?.trim() || e.message || String(err)}`);
-		}
-	}
-	return tag;
 }
 /**
-* Translate Lambda's `Architectures` enum to a Docker `--platform` value.
-*
-* Critical bug fix C2 from the design doc — without this the build /
-* run step uses the host's default arch, which races on M1/M2 Macs
-* (arm64 host) with x86_64 Lambdas. Threaded into BOTH the build (here)
-* and the run path (`docker-runner.runDetached`).
+* Env keys whose VALUES are sensitive (AWS credentials). These are
+* routed through docker's value-from-process-env form by
+* {@link appendEnvFlags} so the value never appears in `docker run`'s
+* argv (`ps` / `/proc/<pid>/cmdline`), and they are also redacted by
+* {@link redactAwsCredentialsInArgs} as a defense for any path that
+* still emits the inline `-e <KEY>=<value>` form into the debug log.
 */
-function architectureToPlatform(architecture) {
-	return architecture === "arm64" ? "linux/arm64" : "linux/amd64";
-}
+const SENSITIVE_ENV_KEYS = new Set([
+	"AWS_ACCESS_KEY_ID",
+	"AWS_SECRET_ACCESS_KEY",
+	"AWS_SESSION_TOKEN"
+]);
 /**
-* Build a stable local tag derived from the asset's build context.
+* Append `-e` flags for `env` to `args`, routing keys in `sensitiveKeys`
+* through docker's value-from-process-env form (`-e KEY`, with NO
+* `=value`). Docker reads the value from its OWN environment at run time,
+* so the secret never lands in `docker run`'s argv — invisible to
+* `ps aux` / `/proc/<pid>/cmdline` (other users on a shared host) and to
+* shell history. Non-sensitive keys keep the inline `-e KEY=VALUE` form
+* (fine for non-secret config, and keeps `--debug` output readable).
 *
-* Fingerprints every field that affects the produced image so an iteration
-* that doesn't change those fields hits Docker's layer cache; an iteration
-* that DOES change them gets a fresh tag (the old tag stays around in
-* `docker images` but harmlessly). The fingerprint covers the full CDK
-* `DockerImageSource` schema so `dockerBuildSecrets` / `dockerBuildContexts`
-* / `cacheFrom` / etc. changes also bust the local cache as expected.
+* Returns the `{ KEY: value }` map of routed-through keys; the caller MUST
+* merge it into the spawned docker process's `env` (see
+* {@link execEnvForSecrets}) so docker can resolve each passed-through
+* key. Values still appear in `docker inspect` Config.Env — that is
+* inherent to container env and matches production behavior.
+*
+* Unlike `--env-file`, this handles multi-line values (e.g. PEM secrets)
+* and needs no temp file on disk.
 */
-function computeLocalTag(source) {
-	const hash = createHash("sha256");
-	pushField(hash, "directory", source.directory ?? "");
-	pushField(hash, "executable", (source.executable ?? []).join(" "));
-	pushField(hash, "dockerFile", source.dockerFile ?? "");
-	pushField(hash, "dockerBuildTarget", source.dockerBuildTarget ?? "");
-	pushField(hash, "networkMode", source.networkMode ?? "");
-	pushField(hash, "platform", source.platform ?? "");
-	pushField(hash, "dockerBuildSsh", source.dockerBuildSsh ?? "");
-	pushField(hash, "cacheDisabled", source.cacheDisabled ? "1" : "0");
-	pushMap(hash, "dockerBuildArgs", source.dockerBuildArgs);
-	pushMap(hash, "dockerBuildContexts", source.dockerBuildContexts);
-	pushMap(hash, "dockerBuildSecrets", source.dockerBuildSecrets);
-	pushField(hash, "dockerOutputs", (source.dockerOutputs ?? []).join(""));
-	pushField(hash, "cacheFrom", (source.cacheFrom ?? []).map((o) => JSON.stringify(o)).join(""));
-	pushField(hash, "cacheTo", source.cacheTo ? JSON.stringify(source.cacheTo) : "");
-	return `${getEmbedConfig().resourceNamePrefix}-invoke-${hash.digest("hex").slice(0, 16)}`;
+function appendEnvFlags(args, env, sensitiveKeys) {
+	const passthrough = {};
+	for (const [k, v] of Object.entries(env)) if (sensitiveKeys.has(k)) {
+		args.push("-e", k);
+		passthrough[k] = v;
+	} else args.push("-e", `${k}=${v}`);
+	return passthrough;
 }
-function pushField(hash, name, value) {
-	hash.update(name);
-	hash.update("=");
-	hash.update(value);
-	hash.update("\0");
+/**
+* Build the `env` option for an `execFile` / `spawn` call that runs a
+* `docker run` whose args include passed-through sensitive keys (from
+* {@link appendEnvFlags}). Returns `{ env: {...process.env, ...passthrough} }`
+* so docker inherits the normal environment PLUS the sensitive values it
+* must resolve, or `{}` when there is nothing to pass through (preserving
+* the default inherited-environment behavior).
+*/
+function execEnvForSecrets(passthrough) {
+	if (Object.keys(passthrough).length === 0) return {};
+	return { env: {
+		...process.env,
+		...passthrough
+	} };
 }
-function pushMap(hash, name, value) {
-	hash.update(name);
-	hash.update("={");
-	if (value) for (const [k, v] of Object.entries(value)) {
-		hash.update(k);
-		hash.update("=");
-		hash.update(v);
-		hash.update(";");
+/**
+* Returns a copy of `args` with any `-e <KEY>=<value>` pair whose KEY is
+* in {@link SENSITIVE_ENV_KEYS} replaced with `-e <KEY>=***`. The actual
+* `args` passed to `spawn` are never mutated — this is for log output
+* only. With {@link appendEnvFlags} routing credentials through the
+* value-less `-e KEY` form this rarely fires, but it stays as defense for
+* any inline-form credential that slips into a logged command.
+*/
+function redactAwsCredentialsInArgs(args) {
+	const out = [];
+	for (let i = 0; i < args.length; i++) {
+		const cur = args[i];
+		const next = args[i + 1];
+		if (cur === "-e" && typeof next === "string") {
+			const eqIdx = next.indexOf("=");
+			if (eqIdx > 0) {
+				const key = next.substring(0, eqIdx);
+				if (SENSITIVE_ENV_KEYS.has(key)) {
+					out.push("-e", `${key}=***`);
+					i++;
+					continue;
+				}
+			}
+		}
+		out.push(cur);
 	}
-	hash.update("}\0");
+	return out;
 }
 
 //#endregion
@@ -21397,8 +21441,13 @@ function buildDockerRunArgs(opts) {
 		}
 	}
 	if (opts.addHostFlags && opts.addHostFlags.length > 0) for (const f of opts.addHostFlags) args.push(f);
-	if (opts.platformOverride) args.push("--platform", opts.platformOverride);
-	else if (task.runtimePlatform) args.push("--platform", task.runtimePlatform.cpuArchitecture === "ARM64" ? "linux/arm64" : "linux/amd64");
+	let resolvedPlatform;
+	if (opts.platformOverride) resolvedPlatform = opts.platformOverride;
+	else if (task.runtimePlatform) resolvedPlatform = task.runtimePlatform.cpuArchitecture === "ARM64" ? "linux/arm64" : "linux/amd64";
+	if (resolvedPlatform) {
+		args.push("--platform", resolvedPlatform);
+		warnIfEmulatedPlatform(resolvedPlatform, { label: `${task.family}/${container.name}` });
+	}
 	const ephemeralPorts = new Set(opts.ephemeralPublishContainerPorts ?? []);
 	if (!opts.skipHostPortPublish) for (const pm of container.portMappings) {
 		if (ephemeralPorts.has(pm.containerPort)) continue;
@@ -31937,10 +31986,10 @@ const STUDIO_CSS = `
     padding: 5px 16px; font-size: 12px; cursor: pointer; margin: 0;
   }
   .log-clear:hover { background: #2a2a2a; color: #fff; border-color: #4a4a4a; }
-  /* A Clear action sits BELOW the log it clears, right-aligned within the
-     same capped content column so it lands near the log, not at the far
-     right edge of a wide pane. */
-  .clear-row { display: flex; justify-content: flex-end; max-width: 760px; margin-top: 6px; }
+  /* A Clear action sits on its own row, right-aligned, ABOVE the log it
+     clears (the log streams downward) and below the action controls (the
+     WS console's Send row). */
+  .clear-row { display: flex; justify-content: flex-end; margin: 4px 0; }
   .composer .err { color: #e0707a; margin-top: 6px; min-height: 18px; }
   .section { padding: 8px 12px; border-bottom: 1px solid #222; }
   .section h3 { margin: 0 0 6px; font-size: 11px; color: #888; text-transform: uppercase; }
@@ -31951,12 +32000,7 @@ const STUDIO_CSS = `
   .endpoint:hover { text-decoration: underline; }
   .ws-console .ws-status { font-size: 12px; color: #888; margin-left: 8px; font-weight: 400; }
   .ws-console .ws-status.on { color: #4ec97a; }
-  /* Cap the interactive content to a readable column so on a wide center
-     pane the input does not stretch edge-to-edge and fling Send far to the
-     right. Send then sits right after the input; the log + Clear share the
-     same column. The cap is a no-op on a narrow pane (content uses what is
-     available). */
-  .ws-row { display: flex; gap: 6px; align-items: center; margin: 6px 0; max-width: 760px; }
+  .ws-row { display: flex; gap: 6px; align-items: center; margin: 6px 0; }
   .ws-row .ws-input { flex: 1; min-width: 0; background: #1a1a1a; border: 1px solid #333;
     color: #ddd; border-radius: 4px; padding: 5px 7px; font: inherit; }
   .ws-row .ws-input:focus { outline: none; border-color: #4ec97a; }
@@ -31964,10 +32008,7 @@ const STUDIO_CSS = `
     padding: 5px 12px; cursor: pointer; }
   .ws-row button:disabled { background: #2a2a2a; color: #666; cursor: default; }
   .ws-frames { max-height: 180px; overflow: auto; background: #141414; border: 1px solid #262626;
-    border-radius: 4px; padding: 6px 8px; margin-top: 4px; min-height: 22px; max-width: 760px; }
-  /* The serve LOGS <pre> shares the capped column so its Clear (below it,
-     right-aligned via .clear-row) lands at the column edge, near the log. */
-  .serve-log { max-width: 760px; }
+    border-radius: 4px; padding: 6px 8px; margin-top: 4px; min-height: 22px; }
   .searchbar { padding: 6px 10px; border-bottom: 1px solid #2a2a2a; background: #151515;
     position: sticky; top: 28px; z-index: 1; }
   .searchbar input {
@@ -33023,12 +33064,9 @@ const STUDIO_SCRIPT = `
         )
       );
     }
-    const logPre = el('pre', 'serve-log', logs.length ? logs.join('\\n') : '(none)');
-    logSec.appendChild(logPre);
-    // Clear sits below the log (issue #338): hammering a serve piles up log
-    // lines, so let the user empty the panel (display-only — the server-side
-    // store / history is untouched). Below the log + right-aligned so it lands
-    // near the content it clears, not in the section header above.
+    // Clear sits ABOVE the log, right-aligned (issue #338): hammering a serve
+    // piles up log lines, so let the user empty the panel (display-only — the
+    // server-side store / history is untouched).
     const logClearRow = el('div', 'clear-row');
     const logClear = el('button', 'log-clear', 'Clear');
     logClear.onclick = function () {
@@ -33039,6 +33077,8 @@ const STUDIO_SCRIPT = `
     };
     logClearRow.appendChild(logClear);
     logSec.appendChild(logClearRow);
+    const logPre = el('pre', null, logs.length ? logs.join('\\n') : '(none)');
+    logSec.appendChild(logPre);
     ws.appendChild(logSec);
     // Register the live LOGS <pre> so streamed log events update it surgically
     // (issue #334) instead of re-rendering the whole serve workspace.
@@ -33488,22 +33528,28 @@ const STUDIO_SCRIPT = `
     sendBtn.disabled = !on;
     sendBtn.onclick = wsSend;
 
+    // Input fills the row width; Send is wrapped onto its OWN row below so on
+    // a wide pane it sits at the left (near the input) instead of being flung
+    // to the far right edge.
     const row = el('div', 'ws-row');
     row.appendChild(connectBtn);
     row.appendChild(input);
-    row.appendChild(sendBtn);
     sec.appendChild(row);
 
-    const frames = el('pre', 'ws-frames', wsFrames.join('\\n'));
-    sec.appendChild(frames);
+    const sendRow = el('div', 'ws-row');
+    sendRow.appendChild(sendBtn);
+    sec.appendChild(sendRow);
 
-    // Clear sits BELOW the log it clears (the log streams downward), right-
-    // aligned within the capped column so it stays near the content.
+    // Clear sits directly below the Send button (and above the log it clears),
+    // right-aligned.
     const clearRow = el('div', 'clear-row');
     const clearBtn = el('button', 'log-clear ws-clear', 'Clear');
     clearBtn.onclick = wsClear;
     clearRow.appendChild(clearBtn);
     sec.appendChild(clearRow);
+
+    const frames = el('pre', 'ws-frames', wsFrames.join('\\n'));
+    sec.appendChild(frames);
     return sec;
   }
 
@@ -36507,4 +36553,4 @@ function addStudioSpecificOptions(cmd) {
 
 //#endregion
 export { CLOUDFRONT_DISTRIBUTION_TYPE as $, computeRequestIdentityHash as $n, availableWebSocketApiIdentifiers as $r, getContainerNetworkIp as $t, addStartCloudFrontSpecificOptions as A, resolveApiTargetSubset as An, buildContainerImage as Ar, addImageOverrideOptions as At, classifyS3Error as B, groupRoutesByServer as Bn, createLocalStateProvider as Br, enforceImageOverrideOrphans as Bt, addListSpecificOptions as C, toCmdArgv as Cn, buildMgmtEndpointEnvUrl as Cr, createLocalStartServiceCommand as Ct, createLocalStartAgentCoreCommand as D, addStartApiSpecificOptions as Dn, buildDisconnectEvent as Dr, MAX_TASKS_SUBNET_RANGE_CAP as Dt, addStartAgentCoreSpecificOptions as E, createLocalInvokeCommand as En, buildConnectEvent as Er, createLocalRunTaskCommand as Et, idFromArn as F, materializeLayerFromArn as Fn, substituteAgainstState as Fr, resolveEcsAssumeRoleOption as Ft, serveFromStaticOrigin as G, defaultCredentialsLoader as Gn, resolveCfnStackName as Gr, describePinnedImageUri as Gt, matchBehavior as H, startApiServer as Hn, rejectExplicitCfnStackWithMultipleStacks as Hr, parseImageOverrideFlags as Ht, resolveKvsModulesForDistribution as I, resolveEnvVars$1 as In, substituteAgainstStateAsync as Ir, resolveSharedSidecarCredentials as It, applyEdgeResponseResult as J, createJwksCache as Jn, resolveSsmParameters as Jr, buildCloudMapIndex as Jt, serveLambdaUrlOrigin as K, buildCognitoJwksUrl as Kn, CfnLocalStateProvider as Kr, isLocalCdkAssetImage as Kt, createDeployedKvsDataSource as L, availableApiIdentifiers as Ln, substituteEnvVarsFromState as Lr, runEcsServiceEmulator as Lt, parseKvsFileOverrides as M, createFileWatcher as Mn, resolveRuntimeFileExtension as Mr, ecsClusterOption as Mt, parseOriginOverrides as N, attachStageContext as Nn, resolveRuntimeImage as Nr, parseMaxTasks as Nt, startAgentCoreWsBridge as O, createLocalStartApiCommand as On, buildMessageEvent as Or, addCommonEcsServiceOptions as Ot, resolveCloudFrontTarget as P, buildStageMap as Pn, EcsTaskResolutionError as Pr, parseRestartPolicy as Pt, httpHeadersToEdge as Q, buildMethodArn as Qn, listTargets as Qr, setShadowReadyTimeoutMs as Qt, resolveDeployedKvsArnByName as R, filterRoutesByApiIdentifier as Rn, substituteEnvVarsFromStateAsync as Rr, ImageOverrideError as Rt, StudioEventBus as S, resolveProfileCredentials as Si, renderCodeDockerfile as Sn, ConnectionRegistry as Sr, addStartServiceSpecificOptions as St, formatTargetListing as T, addInvokeSpecificOptions as Tn, parseConnectionsPath as Tr, addRunTaskSpecificOptions as Tt, startCloudFrontServer as U, resolveSelectionExpression as Un, resolveCfnFallbackRegion as Ur, resolveImageOverrides as Ut, createS3OriginReader as V, readMtlsMaterialsFromDisk as Vn, isCfnFlagPresent as Vr, mergeForService as Vt, resolveErrorResponseCandidates as W, resolveServiceIntegrationParameters as Wn, resolveCfnRegion as Wr, runImageOverrideBuilds as Wt, buildEdgeResponseEvent as X, verifyJwtAuthorizer as Xn, resolveSingleTarget as Xr, DEFAULT_SHADOW_READY_TIMEOUT_MS as Xt, buildEdgeRequestEvent as Y, verifyCognitoJwt as Yn, resolveWatchConfig as Yr, CloudMapRegistry as Yt, edgeHeadersToHttp as Z, verifyJwtViaDiscovery as Zn, countTargets as Zr, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as Zt, filterStudioTargetGroups as _, formatStateRemedy as _i, waitForAgentCorePing as _n, tryParseStatus as _r, createLocalStartAlbCommand as _t, createLocalStudioCommand as a, discoverRoutes as ai, A2A_CONTAINER_PORT as an, buildCorsConfigByApiId as ar, pickLambdaEdgeFunctionLogicalId as at, renderStudioHtml as b, LocalInvokeBuildError as bi, buildAgentCoreCodeImage as bn, probeHostGatewaySupport as br, isApplicationLoadBalancer as bt, startStudioProxy as c, AGENTCORE_A2A_PROTOCOL as ci, MCP_CONTAINER_PORT as cn, matchPreflight as cr, compileCloudFrontFunction as ct, createStudioDispatcher as d, AGENTCORE_MCP_PROTOCOL as di, mcpInvokeOnce as dn, applyAuthorizerOverlay as dr, stripCloudFrontImport as dt, discoverWebSocketApis as ei, attachContainerLogStreamer as en, evaluateCachedLambdaPolicy as er, describeS3OriginDomain as et, filterStudioCustomResources as f, AGENTCORE_RUNTIME_TYPE as fi, parseSseForJsonRpc as fn, buildHttpApiV2Event as fr, createCloudFrontModule as ft, annotatePinnedEcsTargets as g, derivePseudoParametersFromRegion as gi, invokeAgentCore as gn, selectIntegrationResponse as gr, albStrategy as gt, annotateEcsTaskPinnedTargets as h, resolveAgentCoreTarget as hi, AGENTCORE_SESSION_ID_HEADER as hn, pickResponseTemplate as hr, addAlbSpecificOptions as ht, coerceStopRequest as i, webSocketApiMatchesIdentifier as ii, invokeAgentCoreWs as in, applyCorsResponseHeaders as ir, pickKvsLogicalIdFromArn as it, createLocalStartCloudFrontCommand as j, createAuthorizerCache as jn, resolveRuntimeCodeMountPath as jr, buildEcsImageResolutionContext$1 as jt, LocalStartCloudFrontError as k, createWatchPredicates as kn, architectureToPlatform as kr, addEcsAssumeRoleOptions as kt, relayServeRequest as l, AGENTCORE_AGUI_PROTOCOL as li, MCP_PATH as ln, matchRoute as lr, runViewerRequest as lt, annotateAlbPinnedBackingServices as m, pickAgentCoreCandidateStack as mi, signAgentCoreInvocation as mn, evaluateResponseParameters as mr, createUnboundCloudFrontModule as mt, coerceRunRequest as n, filterWebSocketApisByIdentifiers as ni, createLocalInvokeAgentCoreCommand as nn, invokeTokenAuthorizer as nr, isCloudFrontDistribution as nt, resolveServeBaseUrl as o, pickRefLogicalId as oi, A2A_PATH as on, buildCorsConfigFromCloudFrontChain as or, pickTargetFunctionLogicalId as ot, isCustomResourceLambdaTarget as p, AgentCoreResolutionError as pi, AGENTCORE_SIGV4_SERVICE as pn, buildRestV1Event as pr, createLocalFileKvsDataSource as pt, applyEdgeRequestResult as q, buildJwksUrlFromIssuer as qn, collectSsmParameterRefs as qr, listPinnedTargets as qt, coerceServeRequest as r, parseSelectionExpressionPath as ri, bridgeAgentCoreWs as rn, attachAuthorizers as rr, pickFunctionUrlLogicalIdFromOrigin as rt, createStudioServeManager as s, resolveLambdaArnIntrinsic as si, a2aInvokeOnce as sn, isFunctionUrlOacFronted as sr, resolveCloudFrontDistribution as st, addStudioSpecificOptions as t, discoverWebSocketApisOrThrow as ti, addInvokeAgentCoreSpecificOptions as tn, invokeRequestAuthorizer as tr, extractKvsAssociations as tt, reinvoke as u, AGENTCORE_HTTP_PROTOCOL as ui, MCP_PROTOCOL_VERSION as un, translateLambdaResponse as ur, runViewerResponse as ut, startStudioServer as v, substituteImagePlaceholders as vi, downloadAndExtractS3Bundle as vn, VtlEvaluationError as vr, parseLbPortOverrides as vt, createLocalListCommand as w, classifySourceChange as wn, handleConnectionsRequest as wr, serviceStrategy as wt, createStudioStore as x, buildStsClientConfig as xi, computeCodeImageTag as xn, bufferToBody as xr, resolveAlbFrontDoor as xt, toStudioTargetGroups as y, tryResolveImageFnJoin as yi, SUPPORTED_CODE_RUNTIMES as yn, HOST_GATEWAY_MIN_VERSION as yr, resolveAlbTarget as yt, resolveDeployedOriginBucket as z, filterRoutesByApiIdentifiers as zn, LocalStateSourceError as zr, buildImageOverrideTag as zt };
-//# sourceMappingURL=local-studio-HawiuYRz.js.map
+//# sourceMappingURL=local-studio-BlFoXpwl.js.map