cdk-local 0.72.0 → 0.73.1

package/dist/{local-list-BOmsOq0r.js → local-list-CE7RB46x.js}

@@ -8488,7 +8488,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 (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions. Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from state (requires an active state source); (3) `--no-assume-role` explicitly opts out. Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers. Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries. Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via ListStackResources and substitute Ref / Fn::ImportValue in env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the resolved stack name; pass an explicit value when CFn stack name differs. Fn::GetAtt is warn-and-dropped in v1 (CFn ListStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-cfn-stack as the CFn client region."));
+	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."));
 }
 
 //#endregion
@@ -10154,6 +10154,30 @@ function shortJson(value) {
 
 //#endregion
 //#region src/local/cognito-jwt.ts
+/**
+* Re-emit window for unreachable-endpoint warns. 5 minutes is short enough
+* the user notices the degraded state on a normal `--watch` session, long
+* enough not to spam the log on every request when the upstream IdP is down.
+*/
+const WARN_REEMIT_INTERVAL_MS = 300 * 1e3;
+/**
+* Returns true iff `key`'s last warn timestamp is older than
+* {@link WARN_REEMIT_INTERVAL_MS} (or has never been recorded). When true,
+* `warnedAt[key]` is updated to `now` as a side effect so the next call
+* within the window returns false.
+*
+* Callers that omit `warnedAt` (the per-AuthCheck local fallback in tests
+* and the no-dedup branch in shape-only call sites) get a no-op true on
+* every call.
+*/
+function shouldWarn(key, warnedAt, now) {
+	if (!warnedAt) return true;
+	const last = warnedAt.get(key);
+	const t = now();
+	if (last !== void 0 && t - last < 3e5) return false;
+	warnedAt.set(key, t);
+	return true;
+}
 const DEFAULT_JWKS_TTL_MS = 3600 * 1e3;
 /**
 * Failure-mode TTL for JWKS-unreachable entries. Pre-fix the failure
@@ -10300,7 +10324,7 @@ async function verifyCognitoJwt(authorizer, authorizationHeader, jwksCache, opts
 		identityHash,
 		ttlSeconds: 0
 	};
-	return verifyAndShape(token, buildCognitoJwksUrl(selectedPool.region, selectedPool.userPoolId), buildCognitoIssuer(selectedPool.region, selectedPool.userPoolId), void 0, void 0, void 0, jwksCache, opts.warned, now);
+	return verifyAndShape(token, buildCognitoJwksUrl(selectedPool.region, selectedPool.userPoolId), buildCognitoIssuer(selectedPool.region, selectedPool.userPoolId), void 0, void 0, void 0, jwksCache, opts.warnedAt, now);
 }
 /**
 * Verify a Bearer JWT against an HTTP v2 JWT authorizer's `JwtConfiguration`.
@@ -10313,7 +10337,7 @@ async function verifyJwtAuthorizer(authorizer, authorizationHeader, jwksCache, o
 		identityHash: void 0,
 		ttlSeconds: 0
 	};
-	return verifyAndShape(token, authorizer.region && authorizer.userPoolId ? buildCognitoJwksUrl(authorizer.region, authorizer.userPoolId) : buildJwksUrlFromIssuer(authorizer.issuer), authorizer.issuer.replace(/\/+$/, ""), authorizer.audience, void 0, void 0, jwksCache, opts.warned, now);
+	return verifyAndShape(token, authorizer.region && authorizer.userPoolId ? buildCognitoJwksUrl(authorizer.region, authorizer.userPoolId) : buildJwksUrlFromIssuer(authorizer.issuer), authorizer.issuer.replace(/\/+$/, ""), authorizer.audience, void 0, void 0, jwksCache, opts.warnedAt, now);
 }
 /**
 * Verify a Bearer JWT against an OIDC-discovery-URL authorizer (Bedrock
@@ -10349,10 +10373,7 @@ async function verifyJwtViaDiscovery(authorizer, authorizationHeader, jwksCache,
 		issuer = doc.issuer;
 		jwksUri = doc.jwks_uri;
 	} catch (err) {
-		if (opts.warned && !opts.warned.has(authorizer.discoveryUrl)) {
-			opts.warned.add(authorizer.discoveryUrl);
-			getLogger().child("cognito-jwt").warn(`OIDC discovery unreachable at ${authorizer.discoveryUrl}: ${err instanceof Error ? err.message : String(err)}. Token accepted without verification — local dev fallback.`);
-		}
+		if (shouldWarn(authorizer.discoveryUrl, opts.warnedAt, now)) getLogger().child("cognito-jwt").warn(`OIDC discovery unreachable at ${authorizer.discoveryUrl}: ${err instanceof Error ? err.message : String(err)}. Token accepted without verification — local dev fallback.`);
 		const identityHash = buildIdentityHash([token]);
 		const parsed = parseJwt(token);
 		if (parsed) return shapeAllowResult(parsed, identityHash, now);
@@ -10365,16 +10386,13 @@ async function verifyJwtViaDiscovery(authorizer, authorizationHeader, jwksCache,
 		};
 	}
 	const allowlist = [...authorizer.allowedAudience ?? [], ...authorizer.allowedClients ?? []];
-	return verifyAndShape(token, jwksUri, issuer.replace(/\/+$/, ""), allowlist.length > 0 ? allowlist : void 0, authorizer.allowedScopes, authorizer.customClaims, jwksCache, opts.warned, now);
+	return verifyAndShape(token, jwksUri, issuer.replace(/\/+$/, ""), allowlist.length > 0 ? allowlist : void 0, authorizer.allowedScopes, authorizer.customClaims, jwksCache, opts.warnedAt, now);
 }
-async function verifyAndShape(token, jwksUrl, expectedIssuer, expectedAudience, requiredScopes, customClaims, jwksCache, warned, now) {
+async function verifyAndShape(token, jwksUrl, expectedIssuer, expectedAudience, requiredScopes, customClaims, jwksCache, warnedAt, now) {
 	const identityHash = buildIdentityHash([token]);
 	const jwks = await jwksCache.fetchAndCache(jwksUrl);
 	if (jwks.passThrough) {
-		if (warned && !warned.has(jwksUrl)) {
-			warned.add(jwksUrl);
-			getLogger().child("cognito-jwt").warn(`JWKS pass-through mode for ${jwksUrl}: token accepted without signature verification.`);
-		}
+		if (shouldWarn(jwksUrl, warnedAt, now)) getLogger().child("cognito-jwt").warn(`JWKS pass-through mode for ${jwksUrl}: token accepted without signature verification.`);
 		const parsed = parseJwt(token);
 		if (parsed) return shapeAllowResult(parsed, identityHash, now);
 		return {
@@ -15669,7 +15687,7 @@ async function runAuthorizerPass(authorizer, snapshot, matchCtx, state, opts, re
 		denyKind: "policy-deny"
 	};
 	const authHeader = headers["authorization"];
-	const jwksOpts = { ...opts.jwksWarnedUrls && { warned: opts.jwksWarnedUrls } };
+	const jwksOpts = { ...opts.jwksWarnedAt && { warnedAt: opts.jwksWarnedAt } };
 	if (authorizer.kind === "cognito") {
 		if (cache && authHeader !== void 0) {
 			const cached = cache.get(authorizer.logicalId, hashOne(authHeader));
@@ -16625,7 +16643,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 	let profileCredsFile;
 	const authorizerCache = createAuthorizerCache();
 	const jwksCache = createJwksCache();
-	const jwksWarnedUrls = /* @__PURE__ */ new Set();
+	const jwksWarnedAt = /* @__PURE__ */ new Map();
 	let sigV4CredentialsLoader;
 	const sigV4WarnedForeignIds = /* @__PURE__ */ new Set();
 	const fromCfnTipEmitted = { value: false };
@@ -16802,7 +16820,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 			port: basePort === 0 ? 0 : nextPort,
 			authorizerCache,
 			jwksCache,
-			jwksWarnedUrls,
+			jwksWarnedAt,
 			sigV4CredentialsLoader,
 			sigV4WarnedForeignIds,
 			sigV4Strict: options.strictSigv4 === true,
@@ -16849,7 +16867,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 			port: basePort === 0 ? 0 : nextPort,
 			authorizerCache,
 			jwksCache,
-			jwksWarnedUrls,
+			jwksWarnedAt,
 			sigV4WarnedForeignIds,
 			sigV4Strict: options.strictSigv4 === true,
 			preDispatch: async (req, res) => {
@@ -18544,7 +18562,7 @@ async function resolveInboundAuthorization(resolved, options) {
 		...authorizer.allowedClients && { allowedClients: authorizer.allowedClients },
 		...authorizer.allowedScopes && { allowedScopes: authorizer.allowedScopes },
 		...authorizer.customClaims && { customClaims: authorizer.customClaims }
-	}, header, createJwksCache(), { warned: /* @__PURE__ */ new Set() })).allow) throw new CdkLocalError(`Inbound JWT rejected by the runtime's customJwtAuthorizer (signature / issuer / expiry / audience check failed against ${authorizer.discoveryUrl}).`, "LOCAL_INVOKE_AGENTCORE_AUTH_DENIED");
+	}, header, createJwksCache(), { warnedAt: /* @__PURE__ */ new Map() })).allow) throw new CdkLocalError(`Inbound JWT rejected by the runtime's customJwtAuthorizer (signature / issuer / expiry / audience check failed against ${authorizer.discoveryUrl}).`, "LOCAL_INVOKE_AGENTCORE_AUTH_DENIED");
 	logger.info(`Inbound JWT verified against ${authorizer.discoveryUrl}.`);
 	return header;
 }
@@ -19151,7 +19169,7 @@ function readEnvOverridesFile$2(filePath) {
 }
 function createLocalInvokeAgentCoreCommand(opts = {}) {
 	setEmbedConfig(opts.embedConfig);
-	const cmd = new Command("invoke-agentcore").description("Run a Bedrock AgentCore Runtime container locally and invoke it once over its protocol contract: HTTP (POST /invocations + GET /ping on 8080) or MCP (POST /mcp Streamable HTTP on 8000). Resolves the AWS::BedrockAgentCore::Runtime, pulls/builds its container, injects env vars + AWS credentials, and prints the response. For an MCP runtime, runs the session handshake then sends one JSON-RPC request (tools/list by default, or the method/params from --event). Target accepts a CDK display path (MyStack/MyAgent) or stack-qualified logical ID (MyStack:MyAgentRuntime1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick from a list. Supports the container artifact and the CodeConfiguration managed-runtime artifact (fromCodeAsset, built from source) on the HTTP + MCP protocols; the agent calls real AWS for managed services.").argument("[target]", "CDK display path or stack-qualified logical ID of the AgentCore Runtime to invoke (omit to pick interactively in a TTY)").action(withErrorHandling(async (target, options) => {
+	const cmd = new Command("invoke-agentcore").description("Run a Bedrock AgentCore Runtime container locally and invoke it once over its protocol contract: HTTP (POST /invocations + GET /ping on 8080; SSE / WebSocket are HTTP wire-shape variants on the same port), MCP (POST /mcp Streamable HTTP on 8000), A2A, or AGUI. Resolves the AWS::BedrockAgentCore::Runtime, pulls/builds its container, injects env vars + AWS credentials, and prints the response. For an MCP runtime, runs the session handshake then sends one JSON-RPC request (tools/list by default, or the method/params from --event). Target accepts a CDK display path (MyStack/MyAgent) or stack-qualified logical ID (MyStack:MyAgentRuntime1234). Single-stack apps may omit the stack prefix. Omit <target> in an interactive terminal to pick from a list. Supports the container artifact and the CodeConfiguration managed-runtime artifact (fromCodeAsset, built from source) on all four protocols; the agent calls real AWS for managed services.").argument("[target]", "CDK display path or stack-qualified logical ID of the AgentCore Runtime to invoke (omit to pick interactively in a TTY)").action(withErrorHandling(async (target, options) => {
 		await localInvokeAgentCoreCommand(target, options, opts.extraStateProviders);
 	}));
 	addInvokeAgentCoreSpecificOptions(cmd);
@@ -20640,7 +20658,7 @@ function createLocalRunTaskCommand(opts = {}) {
 * 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 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("--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
@@ -24108,7 +24126,7 @@ function buildAuthCheck(guard, jwksCache, opts = {}) {
 		realm,
 		check: async () => ({ allow: true })
 	};
-	const warned = opts.warned ?? /* @__PURE__ */ new Set();
+	const warnedAt = opts.warnedAt ?? /* @__PURE__ */ new Map();
 	const sessionCookiePrefix = guard.sessionCookieName;
 	const injectedBearer = opts.bearerToken;
 	return {
@@ -24135,7 +24153,7 @@ function buildAuthCheck(guard, jwksCache, opts = {}) {
 					audience: [guard.audience],
 					...guard.region !== void 0 && { region: guard.region },
 					...guard.userPoolId !== void 0 && { userPoolId: guard.userPoolId }
-				}, authorization, jwksCache, { warned })).allow) return { allow: true };
+				}, authorization, jwksCache, { warnedAt })).allow) return { allow: true };
 				return {
 					allow: false,
 					reason: "Bearer token rejected (signature / iss / aud / exp check failed)."
@@ -24248,6 +24266,42 @@ function describePinnedImageUri(service) {
 	if (image.kind === "cdk-asset") return void 0;
 	return image.uri;
 }
+/**
+* Issue #242 / N1 — dedupe pinned-target detection across the two
+* sites that need it during a `cdkl start-service` / `cdkl start-alb`
+* boot:
+*
+*   1. The `--image-override` engine's pre-boot resolution
+*      ({@link resolveImageOverrides}) — needs the pinned set + per-
+*      target deployed-registry URI labels so the picker + boot-prompt
+*      hint can name the image the user is overriding.
+*   2. The post-boot WARN loop in `runEcsServiceEmulator` — surfaces a
+*      per-target WARN naming the deployed-registry URI for every
+*      pinned target the override engine did NOT cover.
+*
+* Before this helper both sites re-walked `isLocalCdkAssetImage` +
+* `describePinnedImageUri` independently. The semantic computation is
+* identical — given a `ResolvedEcsService`, decide pinned vs local-
+* asset and (for pinned targets) surface the URI label. Hoisting the
+* walk here keeps the two call sites in lock-step and gives both a
+* single test surface.
+*
+* Returns one entry per pinned target in the input's iteration order.
+* Targets whose representative image is a local CDK asset are
+* filtered out — the caller never sees them.
+*/
+function listPinnedTargets(resolvedServices) {
+	const out = [];
+	for (const { target, service } of resolvedServices) {
+		if (isLocalCdkAssetImage(service)) continue;
+		const label = describePinnedImageUri(service);
+		out.push({
+			target,
+			...label !== void 0 && { label }
+		});
+	}
+	return out;
+}
 
 //#endregion
 //#region src/local/image-override-engine.ts
@@ -24274,16 +24328,76 @@ var ImageOverrideError = class ImageOverrideError extends CdkLocalError {
 * - `--image-override <svc>=<dockerfile>` -> `explicit.set(svc, dockerfile)`
 * - `--image-override <dockerfile>` (no `=`) -> `pickerPaths.push(...)`
 * - `--image-build-arg KEY=VAL` -> `globals.buildArgs.set('KEY', 'VAL')`
+* - `--image-build-arg <svc>:KEY=VAL` -> `perService(svc).buildArgs.set('KEY', 'VAL')` (issue #240)
 * - `--image-build-secret id=src` -> `globals.buildSecrets.set('id', 'src')`
+* - `--image-build-secret <svc>:id=src` -> `perService(svc).buildSecrets.set('id', 'src')` (issue #240)
 * - `--image-target <stage>` -> `globals.targetStage = '<stage>'`
+* - `--image-target <svc>=<stage>` -> `perService(svc).targetStage = '<stage>'` (issue #240)
+*
+* Per-service syntax convention (issue #240):
+* - Flags whose payload already contains `=` (build-arg, build-secret)
+*   use `:` to separate the service prefix from the `<key>=<value>`
+*   payload — `<svc>:KEY=VAL`. The FIRST `:` before the FIRST `=` (if
+*   any) is treated as the prefix delimiter.
+* - Flags whose payload is a single token (target) use `=` to separate
+*   the service prefix from the stage — `<svc>=stage`. Matches the
+*   `--image-override <svc>=<dockerfile>` convention.
+* - Per-service entries override the global entry per-key when both
+*   forms set the same key on the same target. Globals still apply to
+*   every OTHER overridden target.
 *
 * Collision detection: a service target named more than once in
 * `--image-override <svc>=...` is an error (last-write-wins would
 * silently drop the earlier mapping; explicit error is clearer).
+* Repeated per-service `--image-build-arg <svc>:KEY=...` entries on
+* the same `<svc>:KEY` pair are last-write-wins (the same shape the
+* global form already uses for repeated `KEY=...` entries — both
+* forms behave identically inside their respective bucket).
+*
+* Empty-value semantics:
+* - `--image-build-arg KEY=` (empty value) is ACCEPTED. The empty
+*   string is forwarded verbatim to `docker build --build-arg KEY=`,
+*   which docker itself accepts (the canonical way to unset a
+*   Dockerfile `ARG`'s default). `KEY=` (empty key) is rejected.
+*   Per-service form `<svc>:KEY=` is similarly accepted (same empty-
+*   value semantics applied to the per-service entry).
+* - `--image-target ""` (empty value) is REJECTED — an empty
+*   `--target` is meaningless to `docker build` (`--target` is a
+*   single stage name, not a list). Per-service `<svc>=` is similarly
+*   rejected (empty stage).
+* - `--image-override <svc>=` and `--image-override =<dockerfile>`
+*   are REJECTED — both halves must be non-empty.
+* - `--image-build-secret id=` and `--image-build-secret =src` are
+*   REJECTED — both halves must be non-empty. Per-service form
+*   `<svc>:id=` and `<svc>:=src` are similarly rejected.
 */
 function parseImageOverrideFlags(input) {
 	const explicit = /* @__PURE__ */ new Map();
 	const pickerPaths = [];
+	const perService = /* @__PURE__ */ new Map();
+	const getPerSvc = (svc) => {
+		let entry = perService.get(svc);
+		if (!entry) {
+			entry = {
+				buildArgs: /* @__PURE__ */ new Map(),
+				buildSecrets: /* @__PURE__ */ new Map()
+			};
+			perService.set(svc, entry);
+		}
+		return entry;
+	};
+	const splitPerServicePrefix = (raw) => {
+		const colon = raw.indexOf(":");
+		const eq = raw.indexOf("=");
+		if (colon < 0) return null;
+		if (eq >= 0 && eq < colon) return null;
+		const svc = raw.slice(0, colon).trim();
+		if (!svc) return null;
+		return {
+			svc,
+			rest: raw.slice(colon + 1)
+		};
+	};
 	for (const raw of input.imageOverride ?? []) {
 		const eq = raw.indexOf("=");
 		if (eq < 0) {
@@ -24300,6 +24414,16 @@ function parseImageOverrideFlags(input) {
 	}
 	const buildArgs = /* @__PURE__ */ new Map();
 	for (const raw of input.imageBuildArg ?? []) {
+		const prefix = splitPerServicePrefix(raw);
+		if (prefix) {
+			const eq = prefix.rest.indexOf("=");
+			if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": expected <service>:KEY=VAL.`);
+			const key = prefix.rest.slice(0, eq).trim();
+			const value = prefix.rest.slice(eq + 1);
+			if (!key) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": empty key (after service prefix).`);
+			getPerSvc(prefix.svc).buildArgs.set(key, value);
+			continue;
+		}
 		const eq = raw.indexOf("=");
 		if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": expected KEY=VAL.`);
 		const key = raw.slice(0, eq).trim();
@@ -24309,6 +24433,17 @@ function parseImageOverrideFlags(input) {
 	}
 	const buildSecrets = /* @__PURE__ */ new Map();
 	for (const raw of input.imageBuildSecret ?? []) {
+		const prefix = splitPerServicePrefix(raw);
+		if (prefix) {
+			const eq = prefix.rest.indexOf("=");
+			if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": expected <service>:id=src (e.g. AppService:npmrc=./.npmrc).`);
+			const id = prefix.rest.slice(0, eq).trim();
+			const src = prefix.rest.slice(eq + 1).trim();
+			if (!id || !src) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": id and src must both be non-empty (after service prefix).`);
+			const absSrcPS = isAbsolute(src) ? src : resolve(process.cwd(), src);
+			getPerSvc(prefix.svc).buildSecrets.set(id, absSrcPS);
+			continue;
+		}
 		const eq = raw.indexOf("=");
 		if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": expected id=src (e.g. npmrc=./.npmrc).`);
 		const id = raw.slice(0, eq).trim();
@@ -24321,14 +24456,26 @@ function parseImageOverrideFlags(input) {
 		buildArgs,
 		buildSecrets
 	};
-	if (input.imageTarget !== void 0) {
-		if (!input.imageTarget) throw new ImageOverrideError("Invalid --image-target value: empty string.");
-		globals.targetStage = input.imageTarget;
+	const imageTargetList = input.imageTarget === void 0 ? [] : Array.isArray(input.imageTarget) ? input.imageTarget : [input.imageTarget];
+	for (const raw of imageTargetList) {
+		if (raw === void 0 || raw === null) continue;
+		if (!raw) throw new ImageOverrideError("Invalid --image-target value: empty string.");
+		const eq = raw.indexOf("=");
+		if (eq < 0) {
+			globals.targetStage = raw.trim();
+			continue;
+		}
+		const svc = raw.slice(0, eq).trim();
+		const stage = raw.slice(eq + 1).trim();
+		if (!svc) throw new ImageOverrideError(`Invalid --image-target value "${raw}": left side (service target) is empty.`);
+		if (!stage) throw new ImageOverrideError(`Invalid --image-target value "${raw}": right side (stage) is empty.`);
+		getPerSvc(svc).targetStage = stage;
 	}
 	return {
 		explicit,
 		pickerPaths,
-		globals
+		globals,
+		perService
 	};
 }
 /**
@@ -24370,7 +24517,7 @@ async function resolveImageOverrides(args) {
 			logger.warn(`--image-override: service '${svc}' is not in the pinned-target set (no deployed-registry pin detected for it). Mapping ignored.`);
 			continue;
 		}
-		out.set(svc, makeEntryFromPath(dockerfileRaw, rawFlags.globals, cwd));
+		out.set(svc, makeEntryFromPath(dockerfileRaw, svc, rawFlags, cwd));
 	}
 	if (rawFlags.pickerPaths.length > 0) if (!(isInteractive() && noInteractive !== true)) logger.warn("--image-override <dockerfile> (picker form) requires an interactive TTY and --no-interactive-overrides not to be set. Skipping picker-form mapping(s).");
 	else for (const dockerfileRaw of rawFlags.pickerPaths) {
@@ -24395,8 +24542,7 @@ async function resolveImageOverrides(args) {
 			logger.warn(`--image-override ${dockerfileRaw}: empty selection. Skipped.`);
 			continue;
 		}
-		const entry = makeEntryFromPath(dockerfileRaw, rawFlags.globals, cwd);
-		for (const t of chosen) out.set(t, entry);
+		for (const t of chosen) out.set(t, makeEntryFromPath(dockerfileRaw, t, rawFlags, cwd));
 	}
 	if (args.interactiveBootPrompt === true && isInteractive() && noInteractive !== true) for (const target of pinnedTargets) {
 		if (out.has(target)) continue;
@@ -24410,28 +24556,61 @@ async function resolveImageOverrides(args) {
 		if (!value) continue;
 		const lower = value.toLowerCase();
 		if (lower === "n" || lower === "no") continue;
-		out.set(target, makeEntryFromPath(value, rawFlags.globals, cwd));
+		out.set(target, makeEntryFromPath(value, target, rawFlags, cwd));
 	}
 	return out;
 }
 /**
-* Promote a per-target Dockerfile path + globals into a full
+* Issue #240 — produce the EFFECTIVE per-target build inputs by layering
+* a per-service overlay on top of the global baseline. Per-service
+* entries override the global per-key (and per-service `targetStage`
+* overrides the global `targetStage`).
+*
+* The returned Maps are fresh copies — the caller may mutate the
+* resulting {@link ImageOverrideEntry}'s Maps without bleeding back
+* into the shared global Maps inside {@link RawImageOverrideFlags}.
+* Per-service entries are merged AFTER globals so a key shared between
+* the two ends up with the per-service value (Map's `set` overwrites
+* on duplicate key).
+*/
+function mergeForService(serviceTarget, globals, perService) {
+	const buildArgs = new Map(globals.buildArgs);
+	const buildSecrets = new Map(globals.buildSecrets);
+	let targetStage = globals.targetStage;
+	const overlay = perService.get(serviceTarget);
+	if (overlay) {
+		for (const [k, v] of overlay.buildArgs.entries()) buildArgs.set(k, v);
+		for (const [k, v] of overlay.buildSecrets.entries()) buildSecrets.set(k, v);
+		if (overlay.targetStage !== void 0) targetStage = overlay.targetStage;
+	}
+	return {
+		buildArgs,
+		buildSecrets,
+		...targetStage !== void 0 && { targetStage }
+	};
+}
+/**
+* Promote a per-target Dockerfile path + raw flags into a full
 * {@link ImageOverrideEntry}. Resolves the path against `cwd`, asserts
 * the Dockerfile exists and is a regular file (so the user sees
 * "file not found" up-front rather than mid-`docker build`), and
 * derives the build context as the Dockerfile's parent directory
 * (the v1 simplification — custom contexts are tracked separately).
+*
+* Issue #240 — `serviceTarget` is now part of the entry-construction
+* input so the global + per-service merge runs per target.
 */
-function makeEntryFromPath(raw, globals, cwd) {
+function makeEntryFromPath(raw, serviceTarget, rawFlags, cwd) {
 	const abs = isAbsolute(raw) ? raw : resolve(cwd, raw);
 	if (!existsSync(abs)) throw new ImageOverrideError(`--image-override: Dockerfile '${raw}' does not exist (resolved to '${abs}').`);
 	if (!statSync(abs).isFile()) throw new ImageOverrideError(`--image-override: '${raw}' is not a regular file (resolved to '${abs}').`);
+	const merged = mergeForService(serviceTarget, rawFlags.globals, rawFlags.perService);
 	return {
 		dockerfile: abs,
 		contextDir: dirname(abs),
-		buildArgs: globals.buildArgs,
-		buildSecrets: globals.buildSecrets,
-		...globals.targetStage !== void 0 && { targetStage: globals.targetStage }
+		buildArgs: merged.buildArgs,
+		buildSecrets: merged.buildSecrets,
+		...merged.targetStage !== void 0 && { targetStage: merged.targetStage }
 	};
 }
 /**
@@ -24493,10 +24672,26 @@ function buildImageOverrideTag(serviceTarget, entry) {
 * order maximizes cache reuse). On any failure the function rejects
 * with {@link ImageOverrideError}; the emulator surfaces this before
 * any container is started.
+*
+* Partial-failure rollback (issue #242 / N3): when build N (1-indexed)
+* fails, the 1..(N-1) successfully built local-only tags from THIS run
+* are best-effort `docker image rm`'d before re-throwing. Not a leak
+* (the tags are deterministic per
+* {@link buildImageOverrideTag} so a re-run collides safely with any
+* leftover), but the cleanup keeps the local Docker daemon tidy after
+* a failed boot — disk-pressure scenarios that occasionally surface
+* on dev laptops never accumulate orphan override images across a
+* day of iterations. Cleanup failures are logged at `debug` (another
+* container could be using the image, the image could already have
+* been removed by a parallel `docker system prune`, etc.) and the
+* loop continues so one un-removable tag doesn't shadow the others.
+* The originating {@link ImageOverrideError} is always the thrown
+* value — a cleanup-step error never replaces it.
 */
 async function runImageOverrideBuilds(overrides) {
 	const logger = getLogger();
 	const out = /* @__PURE__ */ new Map();
+	const builtTags = [];
 	for (const [target, entry] of overrides.entries()) {
 		const tag = buildImageOverrideTag(target, entry);
 		const args = [
@@ -24518,12 +24713,69 @@ async function runImageOverrideBuilds(overrides) {
 			});
 		} catch (err) {
 			const e = err;
-			throw new ImageOverrideError(`docker build failed for --image-override '${target}' (Dockerfile=${entry.dockerfile}): ` + (e.stderr?.trim() || e.message || String(err)));
+			const wrapped = new ImageOverrideError(`docker build failed for --image-override '${target}' (Dockerfile=${entry.dockerfile}): ` + (e.stderr?.trim() || e.message || String(err)));
+			for (const priorTag of builtTags) try {
+				await runDockerStreaming([
+					"image",
+					"rm",
+					priorTag
+				], {});
+			} catch (rmErr) {
+				logger.debug(`Image-override rollback: \`docker image rm ${priorTag}\` failed: ${rmErr instanceof Error ? rmErr.message : String(rmErr)}.`);
+			}
+			throw wrapped;
 		}
 		out.set(target, tag);
+		builtTags.push(tag);
 	}
 	return out;
 }
+/**
+* Issue #240 — orphan validation. A per-service build-input flag
+* (`--image-build-arg <svc>:KEY=VAL`, `--image-build-secret
+* <svc>:id=src`, or `--image-target <svc>=stage`) names a service that
+* MUST appear in the resolved override map — otherwise the per-service
+* value silently gets discarded because no `docker build` runs for
+* that service.
+*
+* Called AFTER {@link resolveImageOverrides} (Stage 3 boot prompt
+* complete) so a service the user added via the prompt counts as
+* covered. A still-orphan per-service flag at this point means the
+* user typo'd the service name OR forgot a corresponding
+* `--image-override <svc>=<dockerfile>` mapping (and either chose `N`
+* in the boot prompt or ran with `--no-interactive-overrides`).
+*
+* Throws {@link LocalStartServiceError} naming every offending
+* `<flag>` + `<service>` pair so the user can fix all in one go
+* (matches the `enforceStrictOverrides` pattern). Mutates nothing.
+*
+* Host-side use case: cdkd and other shim hosts that wrap the engine
+* re-export this via `cdk-local/internal` and call it right after
+* their own `resolveImageOverrides` invocation to inherit the same
+* orphan-detection semantics.
+*
+* @param rawFlags Output of {@link parseImageOverrideFlags}.
+* @param resolvedOverrides Output of {@link resolveImageOverrides}
+*   (after the boot prompt has run).
+*/
+function enforceImageOverrideOrphans(rawFlags, resolvedOverrides) {
+	if (rawFlags.perService.size === 0) return;
+	const offenders = [];
+	for (const [svc, overlay] of rawFlags.perService.entries()) {
+		if (resolvedOverrides.has(svc)) continue;
+		if (overlay.buildArgs.size > 0) {
+			const keys = Array.from(overlay.buildArgs.keys()).join(", ");
+			offenders.push(`--image-build-arg ${svc}:${keys} references a service with no --image-override mapping.`);
+		}
+		if (overlay.buildSecrets.size > 0) {
+			const ids = Array.from(overlay.buildSecrets.keys()).join(", ");
+			offenders.push(`--image-build-secret ${svc}:${ids} references a service with no --image-override mapping.`);
+		}
+		if (overlay.targetStage !== void 0) offenders.push(`--image-target ${svc}=${overlay.targetStage} references a service with no --image-override mapping.`);
+	}
+	if (offenders.length === 0) return;
+	throw new LocalStartServiceError(`Per-service image-override flag(s) target a service with no --image-override coverage. Add the matching --image-override <service>=<dockerfile>, drop the per-service flag, or fix the service name:\n  ${offenders.join("\n  ")}`);
+}
 
 //#endregion
 //#region src/cli/commands/ecs-service-emulator.ts
@@ -24676,15 +24928,15 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		logEndpointsBanner(perTarget, frontDoorServers, logger);
 		logger.info("Press ^C to shut down.");
 		const uncoveredPinnedTargets = [];
-		for (const pt of perTarget) {
-			const service = pt.controller?.service;
-			if (!service) continue;
-			if (isLocalCdkAssetImage(service)) continue;
-			if (imageOverrideTags.has(pt.boot.target)) continue;
-			const pinnedUri = describePinnedImageUri(service);
-			const uriDisplay = pinnedUri ? `\`${pinnedUri}\`` : "a deployed registry";
-			logger.warn(`'${pt.boot.target}': running image is pinned to a deployed registry (${uriDisplay}). To iterate on local source, either pass \`--image-override <dockerfile>\` (or \`<service>=<dockerfile>\`) to substitute a local build, or drop \`--from-cfn-stack\` and switch the CDK app to \`ContainerImage.fromAsset(...)\`.`);
-			uncoveredPinnedTargets.push(pt.boot.target);
+		const pinnedEntries = listPinnedTargets(perTarget.filter((pt) => pt.controller?.service).map((pt) => ({
+			target: pt.boot.target,
+			service: pt.controller.service
+		})));
+		for (const entry of pinnedEntries) {
+			if (imageOverrideTags.has(entry.target)) continue;
+			const uriDisplay = entry.label ? `\`${entry.label}\`` : "a deployed registry";
+			logger.warn(`'${entry.target}': running image is pinned to a deployed registry (${uriDisplay}). To iterate on local source, either pass \`--image-override <dockerfile>\` (or \`<service>=<dockerfile>\`) to substitute a local build, or drop \`--from-cfn-stack\` and switch the CDK app to \`ContainerImage.fromAsset(...)\`.`);
+			uncoveredPinnedTargets.push(entry.target);
 		}
 		enforceStrictOverrides(options.strictOverrides === true, uncoveredPinnedTargets);
 		if (options.watch === true && strategy.supportsWatch === true) {
@@ -25185,11 +25437,11 @@ async function buildFrontDoor(plan, options, logger) {
 		keyPath: options.tlsKey
 	}) : void 0;
 	const jwksCache = createJwksCache();
-	const sharedWarned = /* @__PURE__ */ new Set();
+	const sharedWarnedAt = /* @__PURE__ */ new Map();
 	const authForGuard = (guard) => buildAuthCheck(guard, jwksCache, {
 		...options.verifyAuth === false && { noVerifyAuth: true },
 		...options.bearerToken !== void 0 && { bearerToken: options.bearerToken },
-		warned: sharedWarned
+		warnedAt: sharedWarnedAt
 	});
 	const attachAuth = (action, guard) => guard ? {
 		...action,
@@ -25554,8 +25806,7 @@ async function resolveSharedSidecarCredentials(options) {
 */
 async function resolveAndBuildImageOverrides(args) {
 	const { perTarget, stacks, options, extraStateProviders, logger } = args;
-	const pinnedTargets = [];
-	const pinnedLabels = /* @__PURE__ */ new Map();
+	const resolvedForPeek = [];
 	for (const target of perTarget) {
 		const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
 		const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
@@ -25571,18 +25822,22 @@ async function resolveAndBuildImageOverrides(args) {
 			if (stateProvider) stateProvider.dispose();
 		}
 		if (!service) continue;
-		if (isLocalCdkAssetImage(service)) continue;
-		pinnedTargets.push(target);
-		const uri = describePinnedImageUri(service);
-		if (uri) pinnedLabels.set(target, uri);
+		resolvedForPeek.push({
+			target,
+			service
+		});
 	}
+	const pinnedEntries = listPinnedTargets(resolvedForPeek);
+	const pinnedTargets = pinnedEntries.map((e) => e.target);
+	const pinnedLabels = /* @__PURE__ */ new Map();
+	for (const entry of pinnedEntries) if (entry.label !== void 0) pinnedLabels.set(entry.target, entry.label);
 	const rawFlags = parseImageOverrideFlags({
 		...options.imageOverride && { imageOverride: options.imageOverride },
 		...options.imageBuildArg && { imageBuildArg: options.imageBuildArg },
 		...options.imageBuildSecret && { imageBuildSecret: options.imageBuildSecret },
 		...options.imageTarget && { imageTarget: options.imageTarget }
 	});
-	if (pinnedTargets.length === 0 && rawFlags.explicit.size === 0 && rawFlags.pickerPaths.length === 0) return /* @__PURE__ */ new Map();
+	if (pinnedTargets.length === 0 && rawFlags.explicit.size === 0 && rawFlags.pickerPaths.length === 0 && rawFlags.perService.size === 0) return /* @__PURE__ */ new Map();
 	const overrides = await resolveImageOverrides({
 		rawFlags,
 		pinnedTargets,
@@ -25590,6 +25845,7 @@ async function resolveAndBuildImageOverrides(args) {
 		interactiveBootPrompt: true,
 		noInteractive: options.interactiveOverrides === false
 	});
+	enforceImageOverrideOrphans(rawFlags, overrides);
 	if (overrides.size === 0) return /* @__PURE__ */ new Map();
 	return runImageOverrideBuilds(overrides);
 }
@@ -25613,7 +25869,7 @@ function enforceStrictOverrides(strict, uncoveredPinnedTargets) {
 * 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 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("--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."));
+	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."));
 	[
 		...commonOptions(),
 		...appOptions(),
@@ -25639,7 +25895,7 @@ function addCommonEcsServiceOptions(cmd) {
 * factories inherit the flag set without duplication.
 */
 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>", "Global `docker build --target=<stage>` forwarded to every --image-override build. Useful when the Dockerfile is multi-stage and you want to stop at a specific intermediate stage.")).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));
+	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
@@ -26662,5 +26918,5 @@ function addListSpecificOptions(cmd) {
 }
 
 //#endregion
-export { resolveSelectionExpression as $, downloadAndExtractS3Bundle as $t, CloudMapRegistry as A, resolveSingleTarget as An, verifyCognitoJwt as At, createLocalStartApiCommand as B, AGENTCORE_AGUI_PROTOCOL as Bn, A2A_CONTAINER_PORT as Bt, buildImageOverrideTag as C, resolveCfnFallbackRegion as Cn, parseConnectionsPath as Ct, describePinnedImageUri as D, collectSsmParameterRefs as Dn, buildCognitoJwksUrl as Dt, runImageOverrideBuilds as E, CfnLocalStateProvider as En, buildMessageEvent as Et, createLocalRunTaskCommand as F, parseSelectionExpressionPath as Fn, buildCorsConfigByApiId as Ft, attachStageContext as G, pickAgentCoreCandidateStack as Gn, MCP_PROTOCOL_VERSION as Gt, resolveApiTargetSubset as H, AGENTCORE_MCP_PROTOCOL as Hn, a2aInvokeOnce as Ht, attachContainerLogStreamer as I, discoverRoutes as In, buildCorsConfigFromCloudFrontChain as It, filterRoutesByApiIdentifier as J, formatStateRemedy as Jn, AGENTCORE_SIGV4_SERVICE as Jt, buildStageMap as K, resolveAgentCoreTarget as Kn, mcpInvokeOnce as Kt, addInvokeAgentCoreSpecificOptions as L, pickRefLogicalId as Ln, isFunctionUrlOacFronted as Lt, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as M, listTargets as Mn, verifyJwtViaDiscovery as Mt, getContainerNetworkIp as N, discoverWebSocketApis as Nn, attachAuthorizers as Nt, isLocalCdkAssetImage as O, resolveSsmParameters as On, buildJwksUrlFromIssuer as Ot, addRunTaskSpecificOptions as P, discoverWebSocketApisOrThrow as Pn, applyCorsResponseHeaders as Pt, startApiServer as Q, waitForAgentCorePing as Qt, createLocalInvokeAgentCoreCommand as R, resolveLambdaArnIntrinsic as Rn, matchPreflight as Rt, ImageOverrideError as S, rejectExplicitCfnStackWithMultipleStacks as Sn, handleConnectionsRequest as St, resolveImageOverrides as T, resolveCfnStackName as Tn, buildDisconnectEvent as Tt, createAuthorizerCache as U, AGENTCORE_RUNTIME_TYPE as Un, MCP_CONTAINER_PORT as Ut, createWatchPredicates as V, AGENTCORE_HTTP_PROTOCOL as Vn, A2A_PATH as Vt, createFileWatcher as W, AgentCoreResolutionError as Wn, MCP_PATH as Wt, groupRoutesByServer as X, tryResolveImageFnJoin as Xn, AGENTCORE_SESSION_ID_HEADER as Xt, filterRoutesByApiIdentifiers as Y, substituteImagePlaceholders as Yn, signAgentCoreInvocation as Yt, readMtlsMaterialsFromDisk as Z, LocalInvokeBuildError as Zn, invokeAgentCore as Zt, buildEcsImageResolutionContext as _, resolveEnvVars as _n, HOST_GATEWAY_MIN_VERSION as _t, albStrategy as a, addInvokeSpecificOptions as an, invokeRequestAuthorizer as at, resolveSharedSidecarCredentials as b, createLocalStateProvider as bn, ConnectionRegistry as bt, resolveAlbTarget as c, buildContainerImage as cn, translateLambdaResponse as ct, addStartServiceSpecificOptions as d, resolveRuntimeImage as dn, buildRestV1Event as dt, SUPPORTED_CODE_RUNTIMES as en, resolveServiceIntegrationParameters as et, createLocalStartServiceCommand as f, EcsTaskResolutionError as fn, evaluateResponseParameters as ft, addImageOverrideOptions as g, substituteEnvVarsFromStateAsync as gn, VtlEvaluationError as gt, addCommonEcsServiceOptions as h, substituteEnvVarsFromState as hn, tryParseStatus as ht, addAlbSpecificOptions as i, toCmdArgv as in, evaluateCachedLambdaPolicy as it, classifySourceChange as j, countTargets as jn, verifyJwtAuthorizer as jt, buildCloudMapIndex as k, resolveWatchConfig as kn, createJwksCache as kt, isApplicationLoadBalancer as l, resolveRuntimeCodeMountPath as ln, applyAuthorizerOverlay as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, substituteAgainstStateAsync as mn, selectIntegrationResponse as mt, createLocalListCommand as n, computeCodeImageTag as nn, buildMethodArn as nt, createLocalStartAlbCommand as o, createLocalInvokeCommand as on, invokeTokenAuthorizer as ot, serviceStrategy as p, substituteAgainstState as pn, pickResponseTemplate as pt, availableApiIdentifiers as q, derivePseudoParametersFromRegion as qn, parseSseForJsonRpc as qt, formatTargetListing as r, renderCodeDockerfile as rn, computeRequestIdentityHash as rt, parseLbPortOverrides as s, architectureToPlatform as sn, matchRoute as st, addListSpecificOptions as t, buildAgentCoreCodeImage as tn, defaultCredentialsLoader as tt, resolveAlbFrontDoor as u, resolveRuntimeFileExtension as un, buildHttpApiV2Event as ut, parseMaxTasks as v, materializeLayerFromArn as vn, probeHostGatewaySupport as vt, parseImageOverrideFlags as w, resolveCfnRegion as wn, buildConnectEvent as wt, runEcsServiceEmulator as x, isCfnFlagPresent as xn, buildMgmtEndpointEnvUrl as xt, parseRestartPolicy as y, LocalStateSourceError as yn, bufferToBody as yt, addStartApiSpecificOptions as z, AGENTCORE_A2A_PROTOCOL as zn, invokeAgentCoreWs as zt };
-//# sourceMappingURL=local-list-BOmsOq0r.js.map
+export { groupRoutesByServer as $, tryResolveImageFnJoin as $n, AGENTCORE_SESSION_ID_HEADER as $t, isLocalCdkAssetImage as A, collectSsmParameterRefs as An, buildCognitoJwksUrl as At, addInvokeAgentCoreSpecificOptions as B, pickRefLogicalId as Bn, isFunctionUrlOacFronted as Bt, buildImageOverrideTag as C, createLocalStateProvider as Cn, ConnectionRegistry as Ct, resolveImageOverrides as D, resolveCfnRegion as Dn, buildConnectEvent as Dt, parseImageOverrideFlags as E, resolveCfnFallbackRegion as En, parseConnectionsPath as Et, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as F, listTargets as Fn, verifyJwtViaDiscovery as Ft, resolveApiTargetSubset as G, AGENTCORE_MCP_PROTOCOL as Gn, a2aInvokeOnce as Gt, addStartApiSpecificOptions as H, AGENTCORE_A2A_PROTOCOL as Hn, invokeAgentCoreWs as Ht, getContainerNetworkIp as I, discoverWebSocketApis as In, attachAuthorizers as It, attachStageContext as J, pickAgentCoreCandidateStack as Jn, MCP_PROTOCOL_VERSION as Jt, createAuthorizerCache as K, AGENTCORE_RUNTIME_TYPE as Kn, MCP_CONTAINER_PORT as Kt, addRunTaskSpecificOptions as L, discoverWebSocketApisOrThrow as Ln, applyCorsResponseHeaders as Lt, buildCloudMapIndex as M, resolveWatchConfig as Mn, createJwksCache as Mt, CloudMapRegistry as N, resolveSingleTarget as Nn, verifyCognitoJwt as Nt, runImageOverrideBuilds as O, resolveCfnStackName as On, buildDisconnectEvent as Ot, classifySourceChange as P, countTargets as Pn, verifyJwtAuthorizer as Pt, filterRoutesByApiIdentifiers as Q, substituteImagePlaceholders as Qn, signAgentCoreInvocation as Qt, createLocalRunTaskCommand as R, parseSelectionExpressionPath as Rn, buildCorsConfigByApiId as Rt, ImageOverrideError as S, LocalStateSourceError as Sn, bufferToBody as St, mergeForService as T, rejectExplicitCfnStackWithMultipleStacks as Tn, handleConnectionsRequest as Tt, createLocalStartApiCommand as U, AGENTCORE_AGUI_PROTOCOL as Un, A2A_CONTAINER_PORT as Ut, createLocalInvokeAgentCoreCommand as V, resolveLambdaArnIntrinsic as Vn, matchPreflight as Vt, createWatchPredicates as W, AGENTCORE_HTTP_PROTOCOL as Wn, A2A_PATH as Wt, availableApiIdentifiers as X, derivePseudoParametersFromRegion as Xn, parseSseForJsonRpc as Xt, buildStageMap as Y, resolveAgentCoreTarget as Yn, mcpInvokeOnce as Yt, filterRoutesByApiIdentifier as Z, formatStateRemedy as Zn, AGENTCORE_SIGV4_SERVICE as Zt, buildEcsImageResolutionContext as _, substituteAgainstStateAsync as _n, selectIntegrationResponse as _t, albStrategy as a, computeCodeImageTag as an, buildMethodArn as at, resolveSharedSidecarCredentials as b, resolveEnvVars as bn, HOST_GATEWAY_MIN_VERSION as bt, resolveAlbTarget as c, addInvokeSpecificOptions as cn, invokeRequestAuthorizer as ct, addStartServiceSpecificOptions as d, buildContainerImage as dn, translateLambdaResponse as dt, invokeAgentCore as en, LocalInvokeBuildError as er, readMtlsMaterialsFromDisk as et, createLocalStartServiceCommand as f, resolveRuntimeCodeMountPath as fn, applyAuthorizerOverlay as ft, addImageOverrideOptions as g, substituteAgainstState as gn, pickResponseTemplate as gt, addCommonEcsServiceOptions as h, EcsTaskResolutionError as hn, evaluateResponseParameters as ht, addAlbSpecificOptions as i, buildAgentCoreCodeImage as in, defaultCredentialsLoader as it, listPinnedTargets as j, resolveSsmParameters as jn, buildJwksUrlFromIssuer as jt, describePinnedImageUri as k, CfnLocalStateProvider as kn, buildMessageEvent as kt, isApplicationLoadBalancer as l, createLocalInvokeCommand as ln, invokeTokenAuthorizer as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, resolveRuntimeImage as mn, buildRestV1Event as mt, createLocalListCommand as n, downloadAndExtractS3Bundle as nn, resolveSelectionExpression as nt, createLocalStartAlbCommand as o, renderCodeDockerfile as on, computeRequestIdentityHash as ot, serviceStrategy as p, resolveRuntimeFileExtension as pn, buildHttpApiV2Event as pt, createFileWatcher as q, AgentCoreResolutionError as qn, MCP_PATH as qt, formatTargetListing as r, SUPPORTED_CODE_RUNTIMES as rn, resolveServiceIntegrationParameters as rt, parseLbPortOverrides as s, toCmdArgv as sn, evaluateCachedLambdaPolicy as st, addListSpecificOptions as t, waitForAgentCorePing as tn, startApiServer as tt, resolveAlbFrontDoor as u, architectureToPlatform as un, matchRoute as ut, parseMaxTasks as v, substituteEnvVarsFromState as vn, tryParseStatus as vt, enforceImageOverrideOrphans as w, isCfnFlagPresent as wn, buildMgmtEndpointEnvUrl as wt, runEcsServiceEmulator as x, materializeLayerFromArn as xn, probeHostGatewaySupport as xt, parseRestartPolicy as y, substituteEnvVarsFromStateAsync as yn, VtlEvaluationError as yt, attachContainerLogStreamer as z, discoverRoutes as zn, buildCorsConfigFromCloudFrontChain as zt };
+//# sourceMappingURL=local-list-CE7RB46x.js.map