cdk-local 0.73.0 → 0.73.2

package/dist/{local-list-Ch0RglJl.js → local-list-Cj96dZzK.js}

@@ -2029,11 +2029,14 @@ function applyResponseParameters(base, responseParameters, responseCtx) {
 			continue;
 		}
 		const headerMatch = /^(append|overwrite|remove):header\.(.+)$/i.exec(key);
-		if (!headerMatch || !headerMatch[1] || !headerMatch[2]) continue;
+		if (!headerMatch || !headerMatch[1] || !headerMatch[2]) {
+			logger.warn(`ResponseParameters: key '${key}' does not match the expected shape '(append|overwrite|remove):header.<name>' or 'overwrite:statuscode'; the value was dropped. Check for typos (e.g. 'appen:' vs 'append:').`);
+			continue;
+		}
 		const op = headerMatch[1].toLowerCase();
 		const name = headerMatch[2].toLowerCase();
 		if (isReservedHeader(name)) {
-			logger.debug(`ResponseParameters: header '${name}' is reserved by API Gateway and was skipped`);
+			logger.warn(`ResponseParameters: header '${name}' is reserved by API Gateway and was skipped`);
 			continue;
 		}
 		if (op === "remove") delete headers[name];
@@ -8488,7 +8491,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 +10157,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 +10327,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 +10340,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 +10376,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 +10389,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 {
@@ -11196,7 +11217,7 @@ function attachWebSocketServer(opts) {
 				try {
 					ws.close(1008, "Forbidden");
 				} catch {}
-				logger.debug(`WebSocket $connect denied for connection ${connectionId} on ${cfg.api.declaredAt}`);
+				logger.info(`WebSocket $connect denied for connection ${connectionId} on ${cfg.api.declaredAt} — authorizer returned a non-allow verdict. Client was closed with code 1008.`);
 				return;
 			}
 		}
@@ -14604,21 +14625,21 @@ async function verifySigV4(req, loadCredentials, opts = {}) {
 	try {
 		parsed = parseAuthorizationHeader(authHeader);
 	} catch (err) {
-		logger.debug(`AWS_IAM authorizer: malformed Authorization header — ${err instanceof Error ? err.message : String(err)}`);
+		logger.info(`AWS_IAM authorizer: rejecting request — malformed Authorization header (${err instanceof Error ? err.message : String(err)}). Expected shape: 'AWS4-HMAC-SHA256 Credential=<AKID>/<YYYYMMDD>/<region>/<service>/aws4_request, SignedHeaders=<h1>;<h2>;..., Signature=<hex>'.`);
 		return {
 			allow: false,
 			identityHash: void 0
 		};
 	}
 	if (parsed.algorithm !== "AWS4-HMAC-SHA256") {
-		logger.debug(`AWS_IAM authorizer: unsupported algorithm '${parsed.algorithm}'`);
+		logger.info(`AWS_IAM authorizer: rejecting request — unsupported Authorization algorithm '${parsed.algorithm}'. Expected 'AWS4-HMAC-SHA256'.`);
 		return {
 			allow: false,
 			identityHash: void 0
 		};
 	}
 	if (parsed.credentialTerminator !== "aws4_request") {
-		logger.debug(`AWS_IAM authorizer: invalid credential scope terminator '${parsed.credentialTerminator}'`);
+		logger.info(`AWS_IAM authorizer: rejecting request — invalid credential-scope terminator '${parsed.credentialTerminator}'. Expected 'aws4_request' (the last '/' segment of the Credential= value).`);
 		return {
 			allow: false,
 			identityHash: void 0
@@ -14626,21 +14647,22 @@ async function verifySigV4(req, loadCredentials, opts = {}) {
 	}
 	const amzDate = pickHeader(req.headers, "x-amz-date") ?? pickHeader(req.headers, "date");
 	if (!amzDate) {
-		logger.debug("AWS_IAM authorizer: missing x-amz-date / date header");
+		logger.info("AWS_IAM authorizer: rejecting request — missing x-amz-date / date header. Expected ISO-8601 basic 'YYYYMMDDTHHMMSSZ' in 'x-amz-date' (AWS SDK default) or RFC 1123 in 'date' (curl --aws-sigv4).");
 		return {
 			allow: false,
 			identityHash: void 0
 		};
 	}
 	if (!validateAmzDateMatchesCredentialDate(amzDate, parsed.credentialDate)) {
-		logger.debug(`AWS_IAM authorizer: x-amz-date '${amzDate}' does not match credential scope date '${parsed.credentialDate}'`);
+		logger.info(`AWS_IAM authorizer: rejecting request — x-amz-date '${amzDate}' does not match credential-scope date '${parsed.credentialDate}'. The 'YYYYMMDD' prefix of x-amz-date must equal the date segment of Credential=<AKID>/<YYYYMMDD>/...`);
 		return {
 			allow: false,
 			identityHash: void 0
 		};
 	}
-	if (amzDateOutsideSkew(amzDate, (opts.now ?? (() => /* @__PURE__ */ new Date()))())) {
-		logger.debug(`AWS_IAM authorizer: x-amz-date '${amzDate}' outside 15-min clock skew`);
+	const now = (opts.now ?? (() => /* @__PURE__ */ new Date()))();
+	if (amzDateOutsideSkew(amzDate, now)) {
+		logger.info(`AWS_IAM authorizer: rejecting request — x-amz-date '${amzDate}' is outside the 15-minute clock-skew window (local now=${now.toISOString()}). Re-sign the request with the current time or sync the local clock.`);
 		return {
 			allow: false,
 			identityHash: void 0
@@ -14692,7 +14714,7 @@ async function verifySigV4(req, loadCredentials, opts = {}) {
 	}
 	const recomputed = computeSignature(req, parsed, local.secretAccessKey, amzDate);
 	if (!constantTimeEqual(recomputed, parsed.signature)) {
-		logger.debug(`AWS_IAM authorizer: signature mismatch (expected '${recomputed}', got '${parsed.signature}')`);
+		logger.info(`AWS_IAM authorizer: rejecting request — Signature= mismatch (recomputed '${recomputed}', got '${parsed.signature}'). The request was signed with the expected access-key-id but the HMAC does not verify — check the SignedHeaders list, request body, and canonical-request normalization on the signer side.`);
 		return {
 			allow: false,
 			identityHash: void 0
@@ -15669,7 +15691,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));
@@ -16494,10 +16516,13 @@ const DEFAULT_DEBOUNCE_MS = 500;
 * (chokidar starts listening before this function returns); the
 * caller does not need to `await` ready.
 *
-* Errors from chokidar (typically "ENOENT: path doesn't exist") are
-* logged at debug and otherwise swallowed — the start-api server
-* should keep serving even when one of the watched asset directories
-* goes missing during a reload.
+* Errors from chokidar (typically "ENOENT: path doesn't exist", or
+* EMFILE on macOS when watching a deep tree) are logged at WARN and
+* otherwise swallowed — the start-api server should keep serving even
+* when one of the watched asset directories goes missing during a
+* reload, but the user gets a visible signal that `--watch` may have
+* stopped firing so they don't sit there waiting for a reload that
+* will never come.
 */
 function createFileWatcher(options) {
 	const logger = getLogger().child("start-api-watch");
@@ -16537,7 +16562,7 @@ function createFileWatcher(options) {
 	watcher.on("change", onEvent);
 	watcher.on("unlink", onEvent);
 	watcher.on("error", (err) => {
-		logger.debug(`chokidar error: ${err instanceof Error ? err.message : String(err)}. Continuing.`);
+		logger.warn(`chokidar error: ${err instanceof Error ? err.message : String(err)}. --watch may be degraded for the remainder of this session — file changes may no longer trigger reloads. Restart cdkl to recover.`);
 	});
 	return { close: async () => {
 		closed = true;
@@ -16625,7 +16650,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 +16827,7 @@ async function localStartApiCommand(targets, options, extraStateProviders) {
 			port: basePort === 0 ? 0 : nextPort,
 			authorizerCache,
 			jwksCache,
-			jwksWarnedUrls,
+			jwksWarnedAt,
 			sigV4CredentialsLoader,
 			sigV4WarnedForeignIds,
 			sigV4Strict: options.strictSigv4 === true,
@@ -16849,7 +16874,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 +18569,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 +19176,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 +20665,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 +24133,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,16 +24160,20 @@ 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)."
 				};
 			} catch (err) {
-				getLogger().child("front-door-auth").debug(`auth check threw: ${err instanceof Error ? err.message : String(err)}`);
+				const errClass = err instanceof Error ? err.constructor.name : typeof err;
+				const errMessage = err instanceof Error ? err.message : String(err);
+				const REASON_MESSAGE_CAP = 200;
+				const clientMessage = errMessage.length > REASON_MESSAGE_CAP ? `${errMessage.slice(0, REASON_MESSAGE_CAP)}...` : errMessage;
+				getLogger().child("front-door-auth").warn(`Bearer JWT verification threw (${errClass}): ${errMessage}. Returning 401 to client. Check the JWKS URL is reachable and the token is well-formed.`);
 				return {
 					allow: false,
-					reason: "Auth check failed."
+					reason: `Auth check failed: ${errClass} — ${clientMessage}`
 				};
 			}
 		}
@@ -25117,24 +25146,44 @@ async function reloadAllServices(args) {
 */
 async function loadAssetContextForTarget(args) {
 	const { target, controller, stacks, cdkOutDir, assetLoader, logger } = args;
-	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
-	if (!candidate) return void 0;
+	const parsed = parseEcsTarget(target);
+	const candidate = pickCandidateStack(parsed.stackPattern, stacks);
+	if (!candidate) {
+		logger.debug(`loadAssetContext: stack pattern '${parsed.stackPattern}' from target '${target}' not in the assembly. Classifier will see no asset context (rebuild).`);
+		return;
+	}
 	let newService;
 	try {
 		newService = resolveEcsServiceTarget(target, stacks, void 0, { suppressLoadBalancerWarning: true });
 	} catch (err) {
-		logger.debug(`loadAssetContextForTarget: target '${target}' could not be re-resolved against the new stacks: ${err instanceof Error ? err.message : String(err)}. Classifier will see no asset context (rebuild).`);
+		logger.debug(`loadAssetContext: resolveEcsServiceTarget threw for target '${target}' against the new stacks: ${err instanceof Error ? err.message : String(err)}. Classifier will see no asset context (rebuild).`);
 		return;
 	}
 	const essential = newService.task.containers.find((c) => c.essential) ?? newService.task.containers[0];
-	if (!essential) return void 0;
-	if (essential.image.kind !== "cdk-asset" || !essential.image.assetHash) return;
+	if (!essential) {
+		logger.debug(`loadAssetContext: task definition for target '${target}' has no containers. Classifier will see no asset context (rebuild).`);
+		return;
+	}
+	if (essential.image.kind !== "cdk-asset" || !essential.image.assetHash) {
+		const assetHashStr = essential.image.kind === "cdk-asset" ? essential.image.assetHash ?? "undefined" : "n/a";
+		logger.debug(`loadAssetContext: target '${target}' essential image is not a CDK asset (kind='${essential.image.kind}', assetHash=${assetHashStr}). Classifier will see no asset context (rebuild).`);
+		return;
+	}
 	const newAssetHash = essential.image.assetHash;
 	const manifest = await assetLoader.loadManifest(cdkOutDir, candidate.stackName);
-	if (!manifest) return void 0;
+	if (!manifest) {
+		logger.debug(`loadAssetContext: asset manifest missing for stack '${candidate.stackName}' under '${cdkOutDir}'. Classifier will see no asset context (rebuild).`);
+		return;
+	}
 	const newDockerImage = manifest.dockerImages?.[newAssetHash];
-	if (!newDockerImage) return void 0;
-	if (!newDockerImage.source.directory) return;
+	if (!newDockerImage) {
+		logger.debug(`loadAssetContext: asset hash '${newAssetHash}' not present in stack '${candidate.stackName}' dockerImages. Classifier will see no asset context (rebuild).`);
+		return;
+	}
+	if (!newDockerImage.source.directory) {
+		logger.debug(`loadAssetContext: docker asset '${newAssetHash}' for stack '${candidate.stackName}' is executable-mode (no source.directory). Classifier will see no asset context (rebuild).`);
+		return;
+	}
 	const newAssetSourceDir = path.resolve(cdkOutDir, newDockerImage.source.directory);
 	let oldAssetHash;
 	const liveReplica = controller.runState.replicas.find((r) => !r.shuttingDown);
@@ -25419,11 +25468,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,
@@ -25851,7 +25900,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(),
@@ -26901,4 +26950,4 @@ function addListSpecificOptions(cmd) {
 
 //#endregion
 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-Ch0RglJl.js.map
+//# sourceMappingURL=local-list-Cj96dZzK.js.map