@go-to-k/cdkd 0.157.0 → 0.158.0

package/dist/cli.js

@@ -12,7 +12,7 @@ import { AddPermissionCommand, CreateEventSourceMappingCommand, CreateFunctionCo
 import { AssumeRoleCommand, GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
 import { AssociateRouteTableCommand, AttachInternetGatewayCommand, AuthorizeSecurityGroupEgressCommand, AuthorizeSecurityGroupIngressCommand, CreateInternetGatewayCommand, CreateNatGatewayCommand, CreateNetworkAclCommand, CreateNetworkAclEntryCommand, CreateRouteCommand, CreateRouteTableCommand, CreateSecurityGroupCommand, CreateSubnetCommand, CreateTagsCommand, CreateVpcCommand, DeleteInternetGatewayCommand, DeleteNatGatewayCommand, DeleteNetworkAclCommand, DeleteNetworkAclEntryCommand, DeleteNetworkInterfaceCommand, DeleteRouteCommand, DeleteRouteTableCommand, DeleteSecurityGroupCommand, DeleteSubnetCommand, DeleteTagsCommand, DeleteVpcCommand, DescribeAvailabilityZonesCommand, DescribeInstanceAttributeCommand, DescribeInstancesCommand, DescribeInternetGatewaysCommand, DescribeNatGatewaysCommand, DescribeNetworkAclsCommand, DescribeNetworkInterfacesCommand, DescribeRouteTablesCommand, DescribeSecurityGroupsCommand, DescribeSubnetsCommand, DescribeVolumesCommand, DescribeVpcAttributeCommand, DescribeVpcsCommand, DetachInternetGatewayCommand, DisassociateRouteTableCommand, EC2Client, ModifyInstanceAttributeCommand, ModifySubnetAttributeCommand, ModifyVpcAttributeCommand, ReplaceNetworkAclAssociationCommand, RevokeSecurityGroupEgressCommand, RevokeSecurityGroupIngressCommand, RunInstancesCommand, TerminateInstancesCommand, waitUntilInstanceRunning, waitUntilInstanceTerminated, waitUntilNatGatewayAvailable, waitUntilNatGatewayDeleted } from "@aws-sdk/client-ec2";
 import { CreateTableCommand, DeleteTableCommand, DescribeContinuousBackupsCommand, DescribeContributorInsightsCommand, DescribeKinesisStreamingDestinationCommand, DescribeTableCommand, DescribeTimeToLiveCommand, DynamoDBClient, ListTablesCommand, ListTagsOfResourceCommand, ResourceNotFoundException as ResourceNotFoundException$1, TagResourceCommand as TagResourceCommand$2, UntagResourceCommand as UntagResourceCommand$2, UpdateTableCommand, UpdateTimeToLiveCommand } from "@aws-sdk/client-dynamodb";
-import { CloudFormationClient, CreateChangeSetCommand, DeleteChangeSetCommand, DeleteStackCommand, DescribeChangeSetCommand, DescribeStackEventsCommand, DescribeStackResourcesCommand, DescribeStacksCommand, DescribeTypeCommand, ExecuteChangeSetCommand, GetTemplateCommand, UpdateStackCommand, waitUntilChangeSetCreateComplete, waitUntilStackDeleteComplete, waitUntilStackImportComplete, waitUntilStackUpdateComplete } from "@aws-sdk/client-cloudformation";
+import { CloudFormationClient, CreateChangeSetCommand, DeleteChangeSetCommand, DeleteStackCommand, DescribeChangeSetCommand, DescribeStackEventsCommand, DescribeStackResourcesCommand, DescribeStacksCommand, DescribeTypeCommand, ExecuteChangeSetCommand, GetTemplateCommand, ListExportsCommand, UpdateStackCommand, waitUntilChangeSetCreateComplete, waitUntilStackDeleteComplete, waitUntilStackImportComplete, waitUntilStackUpdateComplete } from "@aws-sdk/client-cloudformation";
 import { APIGatewayClient, CreateAuthorizerCommand, CreateDeploymentCommand, CreateResourceCommand, CreateStageCommand, DeleteAuthorizerCommand, DeleteDeploymentCommand, DeleteMethodCommand, DeleteResourceCommand, DeleteStageCommand, GetAccountCommand, GetAuthorizerCommand, GetDeploymentCommand, GetMethodCommand, GetResourceCommand, GetStageCommand, NotFoundException as NotFoundException$1, PutIntegrationCommand, PutIntegrationResponseCommand, PutMethodCommand, PutMethodResponseCommand, TagResourceCommand as TagResourceCommand$3, UntagResourceCommand as UntagResourceCommand$3, UpdateAccountCommand, UpdateAuthorizerCommand, UpdateMethodCommand, UpdateStageCommand } from "@aws-sdk/client-api-gateway";
 import { CreateEventBusCommand, DeleteEventBusCommand, DeleteRuleCommand, DescribeEventBusCommand, DescribeRuleCommand, EventBridgeClient, ListEventBusesCommand, ListRulesCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$1, ListTargetsByRuleCommand, PutRuleCommand, PutTargetsCommand, RemoveTargetsCommand, ResourceNotFoundException as ResourceNotFoundException$2, TagResourceCommand as TagResourceCommand$4, UntagResourceCommand as UntagResourceCommand$4, UpdateEventBusCommand } from "@aws-sdk/client-eventbridge";
 import { CreateSecretCommand, DeleteSecretCommand, DescribeSecretCommand, GetSecretValueCommand, ListSecretsCommand, RemoveRegionsFromReplicationCommand, ReplicateSecretToRegionsCommand, ResourceNotFoundException as ResourceNotFoundException$3, SecretsManagerClient, TagResourceCommand as TagResourceCommand$5, UntagResourceCommand as UntagResourceCommand$5, UpdateSecretCommand } from "@aws-sdk/client-secrets-manager";
@@ -41485,6 +41485,418 @@ async function buildCrossStackResolver(consumerRegion, opts) {
 	};
 }
 
+//#endregion
+//#region src/local/s3-local-state-provider.ts
+/**
+* `S3LocalStateProvider` — implementation of {@link LocalStateProvider}
+* backed by cdkd's S3 state. Wraps the existing
+* `loadStateForStack` + `buildCrossStackResolver` helpers in
+* `src/cli/commands/local-state-loader.ts` so the four `cdkd local *`
+* commands can route both `--from-state` and `--from-cfn-stack`
+* through the same provider-shaped interface (issue #606).
+*
+* Behavior is identical to the pre-issue-#606 code path — this file
+* exists ONLY to give the CLI layer a single interface against which
+* to wire both flags, so adding a third state source (a future
+* `--from-tf-state`? out of scope for now) doesn't require touching
+* the four `local-*.ts` command files again.
+*/
+var S3LocalStateProvider = class {
+	label = "--from-state";
+	opts;
+	disposers = [];
+	constructor(opts) {
+		this.opts = opts;
+	}
+	async load(stackName, synthRegion) {
+		const loaded = await loadStateForStack(stackName, synthRegion, {
+			statePrefix: this.opts.statePrefix,
+			...this.opts.stackRegion !== void 0 && { stackRegion: this.opts.stackRegion },
+			...this.opts.stateBucket !== void 0 && { stateBucket: this.opts.stateBucket },
+			...this.opts.region !== void 0 && { region: this.opts.region },
+			...this.opts.profile !== void 0 && { profile: this.opts.profile }
+		});
+		if (!loaded) return void 0;
+		const outputs = {};
+		for (const [k, v] of Object.entries(loaded.state.outputs ?? {})) if (typeof v === "string") outputs[k] = v;
+		else if (typeof v === "number" || typeof v === "boolean") outputs[k] = String(v);
+		else outputs[k] = JSON.stringify(v);
+		return {
+			resources: loaded.state.resources,
+			outputs,
+			region: loaded.region
+		};
+	}
+	async buildCrossStackResolver(consumerRegion) {
+		const built = await buildCrossStackResolver(consumerRegion, {
+			statePrefix: this.opts.statePrefix,
+			...this.opts.stateBucket !== void 0 && { stateBucket: this.opts.stateBucket },
+			...this.opts.region !== void 0 && { region: this.opts.region },
+			...this.opts.profile !== void 0 && { profile: this.opts.profile }
+		});
+		if (!built) return void 0;
+		this.disposers.push(built.dispose);
+		return built.resolver;
+	}
+	dispose() {
+		while (this.disposers.length > 0) {
+			const fn = this.disposers.pop();
+			if (fn) try {
+				fn();
+			} catch {}
+		}
+	}
+};
+
+//#endregion
+//#region src/local/cfn-local-state-provider.ts
+/**
+* `CfnLocalStateProvider` — implementation of {@link LocalStateProvider}
+* backed by a deployed CloudFormation stack. Powers `cdkd local *
+* --from-cfn-stack` (issue #606).
+*
+* The shape mirrors the SAM CLI's `sam local invoke --stack-name X`
+* behavior: reach into a deployed CFn stack via `DescribeStackResources`
+* to look up physical IDs of every same-stack resource, then make those
+* IDs available to the existing `state-resolver.ts` substitution engine.
+* This lets `cdkd local *` substitute env vars / secrets / images that
+* reference deployed resources in a CDK app deployed via the upstream
+* CDK CLI (`cdk deploy` → CloudFormation) WITHOUT first migrating the
+* stack to cdkd.
+*
+* Wire-format mapping:
+*
+*   - `Ref: <LogicalId>` → resolved via the synthetic `ResourceState`
+*     map built from `DescribeStackResources.StackResources[]` (one
+*     entry per `(LogicalResourceId, PhysicalResourceId, ResourceType)`
+*     tuple).
+*   - `Fn::GetAtt: [<LogicalId>, <Attr>]` → **warn-and-drop**. CFn's
+*     `DescribeStackResources` does NOT return per-attribute values
+*     and the v1 policy (issue #606 recommendation (a)) is to surface
+*     a per-key warn instead of pulling in the full provisioning layer
+*     to call provider-specific describe APIs (e.g. `GetQueueAttributes`
+*     for SQS, `GetFunction` for Lambda). Users override the affected
+*     env var via `--env-vars` if the value is critical.
+*   - `Fn::ImportValue: <exportName>` → resolved via `ListExports`
+*     (paginated). Same-region only — CFn exports are region-scoped.
+*   - `Fn::GetStackOutput` → rejected with a clear pointer that the
+*     intrinsic is cdkd-specific (CFn has no equivalent — exports +
+*     outputs are the only cross-stack vocabulary CFn understands).
+*   - Stack outputs (consumed by both `Fn::GetStackOutput` and the
+*     cross-stack-resolver's index-miss fallback) → sourced from
+*     `DescribeStacks.Outputs[]`.
+*
+* Region handling: the provider takes a single region at construction
+* time (the `cdkd local *` commands resolve this from
+* `--stack-region` > `--region` > `AWS_REGION` > the synth-derived
+* region per the existing `--from-state` precedence). Cross-region
+* `Fn::ImportValue` is out of scope for v1 (CFn's `ListExports` is
+* region-scoped; a future PR can add a multi-region scan if real
+* usage justifies it).
+*
+* AWS API contract notes:
+*
+*   - `DescribeStackResources` is unpaginated up to 500 resources (CFn's
+*     hard stack cap). One call suffices for the entire stack.
+*   - `DescribeStacks` is unpaginated when called with `StackName`.
+*   - `ListExports` is paginated; the provider walks `NextToken` until
+*     the page set is exhausted.
+*/
+var CfnLocalStateProvider = class {
+	label = "--from-cfn-stack";
+	cfnStackName;
+	region;
+	client;
+	clientOptions;
+	constructor(opts) {
+		this.cfnStackName = opts.cfnStackName;
+		this.region = opts.region;
+		this.clientOptions = { region: opts.region };
+		if (opts.profile !== void 0) this.clientOptions.profile = opts.profile;
+	}
+	getClient() {
+		if (!this.client) this.client = new CloudFormationClient({ region: this.region });
+		return this.client;
+	}
+	/**
+	* Load the deployed CFn stack's resources + outputs and return them
+	* as a synthetic `LocalStateRecord` (matching the shape the existing
+	* S3-state-driven path produces). `synthRegion` is accepted for
+	* interface parity with the S3 provider but ignored here — the
+	* provider is region-bound at construction time.
+	*
+	* Best-effort: on any CFn API failure (stack not found, access
+	* denied, throttling) the provider logs a warn and returns
+	* `undefined`. The caller then falls back to the PR 1 warn-and-drop
+	* behavior on every intrinsic-valued env var.
+	*/
+	async load(_stackName, _synthRegion) {
+		const logger = getLogger();
+		const client = this.getClient();
+		let resourceMap;
+		try {
+			resourceMap = buildResourceStateMap((await client.send(new DescribeStackResourcesCommand({ StackName: this.cfnStackName }))).StackResources ?? []);
+		} catch (err) {
+			logger.warn(`${this.label}: DescribeStackResources(${this.cfnStackName}) failed: ${err instanceof Error ? err.message : String(err)}. Was the stack deployed in region '${this.region}'? Falling back.`);
+			return;
+		}
+		let outputs;
+		try {
+			const stack = (await client.send(new DescribeStacksCommand({ StackName: this.cfnStackName }))).Stacks?.[0];
+			if (!stack) {
+				logger.warn(`${this.label}: DescribeStacks(${this.cfnStackName}) returned no stack; outputs will be empty.`);
+				outputs = {};
+			} else outputs = buildOutputsMap(stack.Outputs ?? []);
+		} catch (err) {
+			logger.warn(`${this.label}: DescribeStacks(${this.cfnStackName}) failed: ${err instanceof Error ? err.message : String(err)}. Outputs will be empty (Fn::GetStackOutput cannot resolve).`);
+			outputs = {};
+		}
+		return {
+			resources: resourceMap,
+			outputs,
+			region: this.region
+		};
+	}
+	/**
+	* Build a `CrossStackResolver` that resolves `Fn::ImportValue` via
+	* `cloudformation:ListExports`. `Fn::GetStackOutput` is rejected here
+	* — it's a cdkd-specific intrinsic with no CFn-side equivalent, and
+	* the user-visible error message names the right intrinsic
+	* (`Fn::ImportValue`) for that use case.
+	*
+	* `consumerRegion` is accepted for interface parity with the S3
+	* provider but the `CfnLocalStateProvider` only resolves exports in
+	* the region the stack lives in (which is the same region the
+	* consumer Lambda runs in for the common single-region use case).
+	* A future PR can extend this to multi-region by walking the SDK's
+	* partition-aware region list.
+	*/
+	async buildCrossStackResolver(_consumerRegion) {
+		const logger = getLogger();
+		const client = this.getClient();
+		const label = this.label;
+		const region = this.region;
+		let cachedExports;
+		const ensureExports = async () => {
+			if (cachedExports) return cachedExports;
+			const result = await fetchAllExports(client).catch((err) => {
+				logger.warn(`${label}: ListExports (${region}) failed: ${err instanceof Error ? err.message : String(err)}. Fn::ImportValue intrinsics will warn-and-drop.`);
+			});
+			if (result) cachedExports = result;
+			return result;
+		};
+		return {
+			async resolveImport(exportName) {
+				const map = await ensureExports();
+				if (!map) return void 0;
+				return map.get(exportName);
+			},
+			async resolveGetStackOutput(producerStack, producerRegion, outputName) {
+				logger.warn(`${label}: Fn::GetStackOutput '${producerStack}.${outputName}' (${producerRegion}) is a cdkd-specific intrinsic with no CloudFormation equivalent. Use Fn::ImportValue against an exported output instead, or deploy the producer stack via cdkd deploy and use --from-state.`);
+			}
+		};
+	}
+	dispose() {
+		if (this.client) {
+			this.client.destroy();
+			this.client = void 0;
+		}
+	}
+};
+/**
+* Build the synthetic per-logical-id resource map from
+* `DescribeStackResources` output. Each `ResourceState` carries the
+* physical id (covers `Ref`) and the resource type; `attributes` is
+* left empty per issue #606's (a) recommendation — the warn-and-drop
+* policy on unresolvable `Fn::GetAtt` is the v1 contract. The other
+* `ResourceState` fields (`properties`, `dependencies`, etc.) are
+* also left empty since the substituter doesn't read them.
+*
+* Exported for unit testing.
+*/
+function buildResourceStateMap(stackResources) {
+	const out = {};
+	for (const r of stackResources) {
+		if (!r.LogicalResourceId || !r.PhysicalResourceId || !r.ResourceType) continue;
+		out[r.LogicalResourceId] = {
+			physicalId: r.PhysicalResourceId,
+			resourceType: r.ResourceType,
+			properties: {},
+			attributes: {},
+			dependencies: []
+		};
+	}
+	return out;
+}
+/**
+* Build the outputs map from `DescribeStacks.Outputs[]`. CFn outputs
+* are stringly typed at the wire level (key + value, with the value
+* always a string), so the cast is safe.
+*
+* Exported for unit testing.
+*/
+function buildOutputsMap(outputs) {
+	const out = {};
+	for (const o of outputs) {
+		if (o.OutputKey === void 0 || o.OutputValue === void 0) continue;
+		out[o.OutputKey] = o.OutputValue;
+	}
+	return out;
+}
+/**
+* Walk `ListExports` until every page is consumed and return the
+* `Name -> Value` map. Same-region only (CFn exports are
+* region-scoped); the caller picks the region at provider
+* construction time.
+*
+* Exported for unit testing.
+*/
+async function fetchAllExports(client) {
+	const out = /* @__PURE__ */ new Map();
+	let nextToken;
+	let pages = 0;
+	do {
+		const resp = await client.send(new ListExportsCommand({ ...nextToken !== void 0 && { NextToken: nextToken } }));
+		for (const exp of resp.Exports ?? []) {
+			if (exp.Name === void 0 || exp.Value === void 0) continue;
+			out.set(exp.Name, exp.Value);
+		}
+		nextToken = resp.NextToken;
+		pages += 1;
+		if (pages > 50) throw new Error("ListExports pagination exceeded 50 pages — likely a malformed NextToken loop.");
+	} while (nextToken !== void 0);
+	return out;
+}
+
+//#endregion
+//#region src/cli/commands/local-state-source.ts
+/**
+* Single-source-of-truth helper that picks a {@link LocalStateProvider}
+* for the `cdkd local *` family from CLI flags (issue #606).
+*
+* The four `cdkd local *` commands all support two mutually-exclusive
+* state-source flags:
+*
+*   - `--from-state` (S3-backed; reads cdkd's state for a stack
+*     deployed via `cdkd deploy`).
+*   - `--from-cfn-stack [<cfn-stack-name>]` (CFn-backed; reads a
+*     deployed CloudFormation stack via `DescribeStackResources`).
+*
+* This module centralizes:
+*
+*   - The mutual-exclusion check (rejected at the CLI layer before any
+*     synth / AWS call fires).
+*   - The bare-vs-explicit `--from-cfn-stack` resolution: bare flag uses
+*     the cdkd stack name; explicit value overrides. Matches the
+*     `cdkd import --migrate-from-cloudformation` precedent.
+*   - Region resolution for the CFn client: reuses the existing
+*     `--stack-region` flag (no separate `--cfn-stack-region`) per
+*     issue #606 recommendation.
+*
+* Returns `undefined` when neither flag is set — the caller skips the
+* substitution pass entirely (which is the pre-issue-#606 behavior
+* when `--from-state` was absent).
+*/
+/**
+* Default cdkd stack name → CFn stack name. Matches the
+* `cdkd import --migrate-from-cloudformation` bare-form precedent:
+* bare `--from-cfn-stack` uses the cdkd stack name verbatim as the CFn
+* stack name (typical for CDK apps where the names are the same).
+* Override by passing `--from-cfn-stack <explicit-name>`.
+*
+* Exported for unit testing.
+*/
+function resolveCfnStackName(fromCfnStack, cdkdStackName) {
+	if (typeof fromCfnStack === "string") return fromCfnStack;
+	return cdkdStackName;
+}
+/**
+* Resolve the region used for the CFn client. The CFn provider is
+* region-bound at construction time; we apply the precedence chain
+* `--stack-region` > `--region` > `AWS_REGION` > `AWS_DEFAULT_REGION`
+* > the synth-derived stack region. Throws `LocalStateSourceError`
+* when none of these signals is set — the CFn API call needs a
+* concrete region and silently picking `us-east-1` would query the
+* wrong stack environment (worst case: succeed against the wrong
+* stack and return wrong physical IDs). Distinct from
+* `loadStateForStack`'s behavior: the S3 state bucket name is
+* account-scoped (not region-scoped) and the bucket's region is
+* auto-discovered via `GetBucketLocation`, so the S3 provider can
+* tolerate a missing region. The CFn provider cannot.
+*
+* Exported for unit testing.
+*/
+function resolveCfnRegion(options, synthRegion) {
+	const region = options.stackRegion ?? options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? synthRegion;
+	if (region === void 0) throw new LocalStateSourceError("--from-cfn-stack requires a region to query CloudFormation. Set one of: --stack-region <region>, --region <region>, AWS_REGION env var, AWS_DEFAULT_REGION env var, or an env.region on the target CDK stack.");
+	return region;
+}
+/**
+* Common error class for the mutual-exclusion check so the CLI layer
+* can surface a consistent error message from all four commands.
+*/
+var LocalStateSourceError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LocalStateSourceError";
+	}
+};
+/**
+* Pre-flight check for `--from-cfn-stack <explicit-name>` when the
+* caller will construct one provider per routed stack (`local
+* start-api` / `local start-service`). An explicit value applies to
+* the SINGLE CFn stack named — when multiple cdkd stacks are routed,
+* every one of them would query the same CFn stack, yielding silent
+* wrong-physical-id substitutions for any logical id that happens to
+* collide between the user's stacks. Reject at the CLI layer instead.
+*
+* Bare `--from-cfn-stack` (the cdkdStackName-default) is fine for
+* multi-stack: each routed stack reads its own CFn counterpart.
+* `--from-state` is also fine: cdkd's state is per-(stack, region).
+*
+* Call this from `start-api` / `start-service` BEFORE the per-stack
+* `createLocalStateProvider` loop when `routedStackCount > 1`.
+*/
+function rejectExplicitCfnStackWithMultipleStacks(options, routedStackCount) {
+	if (routedStackCount <= 1) return;
+	if (typeof options.fromCfnStack !== "string") return;
+	throw new LocalStateSourceError(`--from-cfn-stack <name> cannot be used with multiple routed stacks (got ${routedStackCount}). An explicit CFn stack name applies to one stack only and would silently mismap logical IDs across siblings. Use bare --from-cfn-stack (each cdkd stack uses its own name as the CFn stack name) or run one cdkd local invocation per stack.`);
+}
+/**
+* Pick and construct the right `LocalStateProvider` for the supplied
+* flag set. Returns `undefined` when neither flag is set (caller skips
+* the substitution pass). Throws `LocalStateSourceError` when both
+* flags are set (mutually exclusive — different state sources, asking
+* for both is ambiguous about precedence).
+*
+* `cdkdStackName` is the cdkd-side stack name the local command
+* resolved to its target — needed to apply the bare-`--from-cfn-stack`
+* default. `synthRegion` is the synth-derived stack region (`env.region`
+* on the CDK stack) — fallback for the CFn client when no explicit
+* region override is set.
+*
+* For multi-stack callers (`local start-api` / `local start-service`)
+* also invoke `rejectExplicitCfnStackWithMultipleStacks` BEFORE the
+* per-stack loop — see that helper's docstring for the rationale.
+*/
+function createLocalStateProvider(options, cdkdStackName, synthRegion) {
+	const cfnStackOpt = options.fromCfnStack;
+	const cfnFlagPresent = cfnStackOpt !== void 0 && cfnStackOpt !== false;
+	if (options.fromState && cfnFlagPresent) throw new LocalStateSourceError("--from-state and --from-cfn-stack are mutually exclusive. Use --from-state for stacks deployed via `cdkd deploy`; use --from-cfn-stack for stacks deployed via `cdk deploy` (CloudFormation).");
+	if (options.fromState) return new S3LocalStateProvider({
+		statePrefix: options.statePrefix,
+		...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
+		...options.region !== void 0 && { region: options.region },
+		...options.profile !== void 0 && { profile: options.profile },
+		...options.stackRegion !== void 0 && { stackRegion: options.stackRegion }
+	});
+	if (cfnFlagPresent) return new CfnLocalStateProvider({
+		cfnStackName: resolveCfnStackName(cfnStackOpt, cdkdStackName),
+		region: resolveCfnRegion(options, synthRegion),
+		...options.profile !== void 0 && { profile: options.profile }
+	});
+}
+
 //#endregion
 //#region src/local/intrinsic-image.ts
 /**
@@ -53415,7 +53827,7 @@ async function localStartApiCommand(target, options) {
 			const m = buildCorsConfigByApiId(stack.template);
 			for (const [k, v] of m) corsConfigByApiId.set(k, v);
 		}
-		const stateByStack = options.fromState ? await loadStateForRoutedStacks(targetStacks, routes, routesWithAuth, options) : /* @__PURE__ */ new Map();
+		const stateByStack = options.fromState || options.fromCfnStack !== void 0 && options.fromCfnStack !== false ? await loadStateForRoutedStacks(targetStacks, routes, routesWithAuth, options) : /* @__PURE__ */ new Map();
 		const lambdaIds = uniqueLambdaIds(routes, routesWithAuth, webSocketApis);
 		const specs = /* @__PURE__ */ new Map();
 		for (let i = 0; i < lambdaIds.length; i++) {
@@ -54455,13 +54867,14 @@ function envHasIntrinsicValue$1(templateEnv) {
 	return false;
 }
 /**
-* Load cdkd's S3 state for every stack that owns a routed Lambda. Once
+* Load deployed state for every stack that owns a routed Lambda. Once
 * per `synthesizeAndBuild` pass (initial boot + every reload), so a
 * Lambda's per-spec build does not pay one round-trip per Lambda. Per-
 * stack failures (no state, ambiguous region, bucket resolution error)
-* degrade to warn-and-fall-back via {@link loadStateForStack} — the
-* affected stack's reachable Lambdas behave as if `--from-state` were
-* not set, while sibling stacks with loadable state still substitute.
+* degrade to warn-and-fall-back via the active `LocalStateProvider` —
+* the affected stack's reachable Lambdas behave as if `--from-state` /
+* `--from-cfn-stack` were not set, while sibling stacks with loadable
+* state still substitute.
 *
 * Pseudo parameters are resolved per stack and only when at least one
 * reachable Lambda in that stack has an intrinsic-valued env entry
@@ -54490,24 +54903,31 @@ async function loadStateForRoutedStacks(stacks, routes, routesWithAuth, options)
 		}
 		return false;
 	};
+	rejectExplicitCfnStackWithMultipleStacks(options, reachableStackNames.size);
 	for (const stackName of reachableStackNames) {
 		const stack = stacks.find((s) => s.stackName === stackName);
 		if (!stack) continue;
-		const loaded = await loadStateForStack(stack.stackName, stack.region, {
-			...options.stackRegion !== void 0 && { stackRegion: options.stackRegion },
-			...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
-			statePrefix: options.statePrefix,
-			...options.region !== void 0 && { region: options.region },
-			...options.profile !== void 0 && { profile: options.profile }
-		});
-		if (!loaded) continue;
-		const bundle = { state: loaded.state };
-		if (stackHasIntrinsicEnv(stackName)) {
-			const pseudo = await resolvePseudoParametersForStartApi(loaded.region, options);
-			if (pseudo) bundle.pseudoParameters = pseudo;
+		const provider = createLocalStateProvider(options, stack.stackName, stack.region);
+		if (!provider) continue;
+		try {
+			const loaded = await provider.load(stack.stackName, stack.region);
+			if (!loaded) continue;
+			const bundle = { state: {
+				version: 1,
+				stackName: stack.stackName,
+				resources: loaded.resources,
+				outputs: loaded.outputs,
+				lastModified: 0
+			} };
+			if (stackHasIntrinsicEnv(stackName)) {
+				const pseudo = await resolvePseudoParametersForStartApi(loaded.region, options);
+				if (pseudo) bundle.pseudoParameters = pseudo;
+			}
+			out.set(stackName, bundle);
+			logger.debug(`${provider.label}: loaded state for ${stackName} (${loaded.region})`);
+		} finally {
+			provider.dispose();
 		}
-		out.set(stackName, bundle);
-		logger.debug(`--from-state: loaded state for ${stackName} (${loaded.region})`);
 	}
 	return out;
 }
@@ -54520,7 +54940,7 @@ async function loadStateForRoutedStacks(stacks, routes, routesWithAuth, options)
 * region takes priority).
 *
 * Region precedence: `--region` > `AWS_REGION` > `AWS_DEFAULT_REGION` >
-* the state record's region (returned by `loadStateForStack`).
+* the state record's region (returned by the active `LocalStateProvider`).
 */
 async function resolvePseudoParametersForStartApi(stateRegion, options) {
 	const logger = getLogger();
@@ -54584,7 +55004,7 @@ function resolveMtlsConfig(options) {
 * Builder for the `start-api` subcommand. Wired up by `local.ts`.
 */
 function createLocalStartApiCommand() {
-	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).addOption(new Option("--mtls-truststore <path>", "PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj \"/CN=cdkd-local-ca\" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj \"/CN=localhost\"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj \"/CN=client\"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...")).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
+	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).addOption(new Option("--mtls-truststore <path>", "PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj \"/CN=cdkd-local-ca\" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj \"/CN=localhost\"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj \"/CN=client\"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...")).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -55478,6 +55898,7 @@ async function localRunTaskCommand(target, options) {
 	const state = createEcsRunState();
 	let sigintHandler;
 	let sigintCount = 0;
+	let stateProvider;
 	let cleanupPromise;
 	const cleanup = async () => {
 		if (!cleanupPromise) cleanupPromise = (async () => {
@@ -55510,34 +55931,22 @@ async function localRunTaskCommand(target, options) {
 			...options.profile && { macroExpandS3ClientOpts: { profile: options.profile } }
 		};
 		const { stacks } = await synthesizer.synthesize(synthOpts);
-		const imageContext = await buildEcsImageResolutionContext$1(target, stacks, options);
+		const candidate = pickCandidateStack$1(parseEcsTarget(target).stackPattern, stacks);
+		stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", candidate?.region);
+		const imageContext = await buildEcsImageResolutionContext$1(candidate, stateProvider, options);
 		const task = resolveEcsTaskTarget(target, stacks, imageContext);
 		logger.info(`Target: ${task.stack.stackName}/${task.taskDefinitionLogicalId} (family=${task.family}, containers=${task.containers.length})`);
 		const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === task.stack.stackName) ?? task.stack);
-		let taskCrossStackDispose;
-		if (options.fromState && taskNeeds.needsCrossStackResolver) {
+		if (stateProvider && taskNeeds.needsCrossStackResolver) {
 			const consumerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? task.stack.region ?? "us-east-1";
-			const built = await buildCrossStackResolver(consumerRegion, {
-				...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
-				statePrefix: options.statePrefix,
-				...options.region !== void 0 && { region: options.region },
-				...options.profile !== void 0 && { profile: options.profile }
+			const resolver = await stateProvider.buildCrossStackResolver(consumerRegion);
+			if (resolver) await applyCrossStackResolverToTask(task, {
+				resources: imageContext?.stateResources ?? {},
+				...imageContext?.pseudoParameters && { pseudoParameters: imageContext.pseudoParameters },
+				consumerRegion,
+				crossStackResolver: resolver
 			});
-			if (built) {
-				taskCrossStackDispose = built.dispose;
-				try {
-					await applyCrossStackResolverToTask(task, {
-						resources: imageContext?.stateResources ?? {},
-						...imageContext?.pseudoParameters && { pseudoParameters: imageContext.pseudoParameters },
-						consumerRegion,
-						crossStackResolver: built.resolver
-					});
-				} finally {
-					taskCrossStackDispose();
-					taskCrossStackDispose = void 0;
-				}
-			}
-		} else if (!options.fromState && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass --from-state to substitute them against deployed cdkd state.");
+		} else if (!stateProvider && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass --from-state (cdkd-deployed) or --from-cfn-stack (cdk-deployed) to substitute them against deployed state.");
 		sigintHandler = () => {
 			sigintCount += 1;
 			if (sigintCount >= 2) {
@@ -55583,6 +55992,7 @@ async function localRunTaskCommand(target, options) {
 		if (result.exitCode !== 0) process.exitCode = result.exitCode;
 	} finally {
 		if (sigintHandler) process.off("SIGINT", sigintHandler);
+		if (stateProvider) stateProvider.dispose();
 		if (!options.detach) await cleanup();
 	}
 }
@@ -55635,19 +56045,18 @@ async function assumeTaskRole$1(roleArn, region) {
 *
 * Tier 1 (pseudo parameters) fires `sts:GetCallerIdentity` once for
 * `${AWS::AccountId}`; region / partition / URL suffix come from the CLI
-* (`--region` → env vars → synth-derived stack region). Tier 2
-* (`--from-state`) reuses the shared state-loader to pull cdkd's S3 state
-* for the candidate stack — same warn-and-fall-back error policy as
-* `cdkd local invoke --from-state`.
+* (`--region` → env vars → synth-derived stack region). Tier 2 (state
+* load) routes through the active {@link LocalStateProvider} so both
+* `--from-state` and `--from-cfn-stack` produce the same downstream
+* context shape (issue #606).
 */
-async function buildEcsImageResolutionContext$1(target, stacks, options) {
+async function buildEcsImageResolutionContext$1(candidate, stateProvider, options) {
 	const logger = getLogger();
-	const candidate = pickCandidateStack$1(parseEcsTarget(target).stackPattern, stacks);
 	if (!candidate) return void 0;
 	const needs = detectEcsImageResolutionNeeds(candidate);
 	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
 	const ctx = {};
-	const wantsPseudoForEnvOrSecret = options.fromState && needs.needsEnvOrSecretSubstitution;
+	const wantsPseudoForEnvOrSecret = !!stateProvider && needs.needsEnvOrSecretSubstitution;
 	if (needs.needsPseudoParameters || wantsPseudoForEnvOrSecret) {
 		const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
 		if (!region) logger.warn("Resolver references ${AWS::Region} but cdkd could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.");
@@ -55668,17 +56077,11 @@ async function buildEcsImageResolutionContext$1(target, stacks, options) {
 		};
 	}
 	const wantsState = needs.needsStateResources || needs.needsEnvOrSecretSubstitution;
-	if (options.fromState && wantsState) {
-		const loaded = await loadStateForStack(candidate.stackName, candidate.region, {
-			...options.stackRegion !== void 0 && { stackRegion: options.stackRegion },
-			...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
-			statePrefix: options.statePrefix,
-			...options.region !== void 0 && { region: options.region },
-			...options.profile !== void 0 && { profile: options.profile }
-		});
-		if (loaded) ctx.stateResources = loaded.state.resources;
-	} else if (!options.fromState && needs.needsStateResources) logger.warn("Container Image references a same-stack AWS::ECR::Repository. Pass --from-state to substitute the deployed repository URI (requires the stack to have been deployed via cdkd deploy). Otherwise the resolver will surface its existing error.");
-	else if (!options.fromState && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics (Ref / Fn::GetAtt / Fn::Sub / Fn::Join). Pass --from-state to substitute them against the deployed cdkd state. Without --from-state these entries are dropped (per-key warnings will follow).");
+	if (stateProvider && wantsState) {
+		const loaded = await stateProvider.load(candidate.stackName, candidate.region);
+		if (loaded) ctx.stateResources = loaded.resources;
+	} else if (!stateProvider && needs.needsStateResources) logger.warn("Container Image references a same-stack AWS::ECR::Repository. Pass --from-state (cdkd-deployed) or --from-cfn-stack (cdk-deployed) to substitute the deployed repository URI. Otherwise the resolver will surface its existing error.");
+	else if (!stateProvider && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics (Ref / Fn::GetAtt / Fn::Sub / Fn::Join). Pass --from-state (cdkd-deployed) or --from-cfn-stack (cdk-deployed) to substitute them against deployed state. Without a state source these entries are dropped (per-key warnings will follow).");
 	return ctx;
 }
 function pickCandidateStack$1(stackPattern, stacks) {
@@ -55721,7 +56124,7 @@ function readEnvOverridesFile$2(filePath) {
 	return parsed;
 }
 function createLocalRunTaskCommand() {
-	const cmd = new Command("run-task").description("Run an AWS::ECS::TaskDefinition locally — pulls/builds images, sets up a per-task docker network with the AWS-published metadata-endpoints sidecar, and starts every container in dependsOn order. Target accepts a CDK display path (MyStack/MyService/TaskDef) or stack-qualified logical ID (MyStack:MyServiceTaskDefXYZ1234). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the AWS::ECS::TaskDefinition to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).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 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 (#455). 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-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt references to same-stack AWS::ECR::Repository resources with the deployed URI. Off by default — only the AWS pseudo-parameter tier (${AWS::AccountId} / ${AWS::Region}) is resolved without this flag.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localRunTaskCommand));
+	const cmd = new Command("run-task").description("Run an AWS::ECS::TaskDefinition locally — pulls/builds images, sets up a per-task docker network with the AWS-published metadata-endpoints sidecar, and starts every container in dependsOn order. Target accepts a CDK display path (MyStack/MyService/TaskDef) or stack-qualified logical ID (MyStack:MyServiceTaskDefXYZ1234). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the AWS::ECS::TaskDefinition to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).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 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 (#455). 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-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt references to same-stack AWS::ECR::Repository resources with the deployed URI. Off by default — only the AWS pseudo-parameter tier (${AWS::AccountId} / ${AWS::Region}) is resolved without this flag.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources 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 cdkd stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).action(withErrorHandling(localRunTaskCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -56797,6 +57200,7 @@ async function localStartServiceCommand(targets, options) {
 	warnIfDeprecatedRegion(options);
 	const skipPull = options.pull === false;
 	if (!targets || targets.length === 0) throw new LocalStartServiceError("cdkd local start-service requires at least one <target>. Pass one or more service paths like 'Stack/Orders' 'Stack/Frontend'.");
+	rejectExplicitCfnStackWithMultipleStacks(options, targets.length);
 	const perTarget = targets.map((t) => ({
 		target: t,
 		runState: createServiceRunState()
@@ -56893,34 +57297,36 @@ async function localStartServiceCommand(targets, options) {
 * outer code to wait + tear down.
 */
 async function bootOneTarget(target, runState, stacks, options, discovery, skipPull) {
+	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", candidate?.region);
+	try {
+		return await runOneTarget(target, runState, stacks, options, discovery, skipPull, stateProvider);
+	} finally {
+		if (stateProvider) stateProvider.dispose();
+	}
+}
+async function runOneTarget(target, runState, stacks, options, discovery, skipPull, stateProvider) {
 	const logger = getLogger();
-	const imageContext = await buildEcsImageResolutionContext(target, stacks, options);
+	const imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
 	const service = resolveEcsServiceTarget(target, stacks, imageContext);
 	logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
 	for (const w of service.warnings) logger.warn(w);
 	if (service.serviceConnect) logger.info(`Service Connect: namespace='${service.serviceConnect.namespaceName}', ${service.serviceConnect.services.length} service(s) registered for peer discovery.`);
 	if (service.serviceRegistries.length > 0) logger.info(`Cloud Map: ${service.serviceRegistries.length} ServiceRegistry binding(s).`);
 	const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === service.stack.stackName) ?? service.stack);
-	if (options.fromState && taskNeeds.needsCrossStackResolver) {
+	if (stateProvider && taskNeeds.needsCrossStackResolver) {
 		const consumerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? service.stack.region ?? "us-east-1";
-		const built = await buildCrossStackResolver(consumerRegion, {
-			...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
-			statePrefix: options.statePrefix,
-			...options.region !== void 0 && { region: options.region },
-			...options.profile !== void 0 && { profile: options.profile }
-		});
-		if (built) try {
+		const resolver = await stateProvider.buildCrossStackResolver(consumerRegion);
+		if (resolver) {
 			const subContext = {
 				resources: imageContext?.stateResources ?? {},
 				...imageContext?.pseudoParameters && { pseudoParameters: imageContext.pseudoParameters },
 				consumerRegion,
-				crossStackResolver: built.resolver
+				crossStackResolver: resolver
 			};
 			await applyCrossStackResolverToTask(service.task, subContext);
-		} finally {
-			built.dispose();
 		}
-	} else if (!options.fromState && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass --from-state to substitute them against deployed cdkd state.");
+	} else if (!stateProvider && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass --from-state (cdkd-deployed) or --from-cfn-stack (cdk-deployed) to substitute them against deployed state.");
 	let assumedCredentials;
 	let resolvedRoleArn;
 	if (options.assumeTaskRole === true) {
@@ -56989,14 +57395,14 @@ async function assumeTaskRole(roleArn, region) {
 * the candidate stack picker differs because services and tasks share
 * the same stack-pattern grammar.
 */
-async function buildEcsImageResolutionContext(target, stacks, options) {
+async function buildEcsImageResolutionContext(target, stacks, options, stateProvider) {
 	const logger = getLogger();
 	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
 	if (!candidate) return void 0;
 	const needs = detectEcsImageResolutionNeeds(candidate);
 	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
 	const ctx = {};
-	const wantsPseudoForEnvOrSecret = options.fromState && needs.needsEnvOrSecretSubstitution;
+	const wantsPseudoForEnvOrSecret = !!stateProvider && needs.needsEnvOrSecretSubstitution;
 	if (needs.needsPseudoParameters || wantsPseudoForEnvOrSecret) {
 		const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
 		if (!region) logger.warn("Resolver references ${AWS::Region} but cdkd could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.");
@@ -57017,17 +57423,11 @@ async function buildEcsImageResolutionContext(target, stacks, options) {
 		};
 	}
 	const wantsState = needs.needsStateResources || needs.needsEnvOrSecretSubstitution;
-	if (options.fromState && wantsState) {
-		const loaded = await loadStateForStack(candidate.stackName, candidate.region, {
-			...options.stackRegion !== void 0 && { stackRegion: options.stackRegion },
-			...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
-			statePrefix: options.statePrefix,
-			...options.region !== void 0 && { region: options.region },
-			...options.profile !== void 0 && { profile: options.profile }
-		});
-		if (loaded) ctx.stateResources = loaded.state.resources;
-	} else if (!options.fromState && needs.needsStateResources) logger.warn("Container Image references a same-stack AWS::ECR::Repository. Pass --from-state to substitute the deployed repository URI.");
-	else if (!options.fromState && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics. Pass --from-state to substitute them against the deployed cdkd state.");
+	if (stateProvider && wantsState) {
+		const loaded = await stateProvider.load(candidate.stackName, candidate.region);
+		if (loaded) ctx.stateResources = loaded.resources;
+	} else if (!stateProvider && needs.needsStateResources) logger.warn("Container Image references a same-stack AWS::ECR::Repository. Pass --from-state (cdkd-deployed) or --from-cfn-stack (cdk-deployed) to substitute the deployed repository URI.");
+	else if (!stateProvider && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics. Pass --from-state (cdkd-deployed) or --from-cfn-stack (cdk-deployed) to substitute them against the deployed cdkd state.");
 	return ctx;
 }
 function pickCandidateStack(stackPattern, stacks) {
@@ -57098,7 +57498,7 @@ function parseRestartPolicy(raw) {
 	throw new LocalStartServiceError(`--restart-policy must be one of 'on-failure', 'always', or 'none' (got '${raw}').`);
 }
 function createLocalStartServiceCommand() {
-	const cmd = new Command("start-service").description("Run one or more AWS::ECS::Service resources locally as a long-running emulator. Spins up DesiredCount task replicas per service (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as `cdkd local run-task`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Each <target> accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix. When two or more <target>s are supplied, every service is booted into a shared Cloud Map / Service Connect registry so peer services discover each other via docker --add-host overlay (Issue #460).").argument("<targets...>", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ECS::Service resources to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).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-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt / Fn::ImportValue / Fn::GetStackOutput intrinsics in container images, environment variables, secrets, role ARNs, and volumes.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localStartServiceCommand));
+	const cmd = new Command("start-service").description("Run one or more AWS::ECS::Service resources locally as a long-running emulator. Spins up DesiredCount task replicas per service (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as `cdkd local run-task`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Each <target> accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix. When two or more <target>s are supplied, every service is booted into a shared Cloud Map / Service Connect registry so peer services discover each other via docker --add-host overlay (Issue #460).").argument("<targets...>", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ECS::Service resources to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).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-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt / Fn::ImportValue / Fn::GetStackOutput intrinsics in container images, environment variables, secrets, role ARNs, and volumes.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources 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 cdkd stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).action(withErrorHandling(localStartServiceCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -57212,19 +57612,19 @@ async function localInvokeCommand(target, options) {
 		let stateAudit;
 		let templateEnv = getTemplateEnv(lambda.resource);
 		let stateForRoleHint;
-		let crossStackDispose;
-		if (options.fromState) {
-			const loaded = await loadStateForStack(lambda.stack.stackName, lambda.stack.region, {
-				...options.stackRegion !== void 0 && { stackRegion: options.stackRegion },
-				...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
-				statePrefix: options.statePrefix,
-				...options.region !== void 0 && { region: options.region },
-				...options.profile !== void 0 && { profile: options.profile }
-			});
+		const stateProvider = createLocalStateProvider(options, lambda.stack.stackName, lambda.stack.region);
+		if (stateProvider) try {
+			const loaded = await stateProvider.load(lambda.stack.stackName, lambda.stack.region);
 			if (loaded) {
-				stateForRoleHint = loaded.state;
+				stateForRoleHint = {
+					version: 1,
+					stackName: lambda.stack.stackName,
+					resources: loaded.resources,
+					outputs: loaded.outputs,
+					lastModified: 0
+				};
 				const subContext = {
-					resources: loaded.state.resources,
+					resources: loaded.resources,
 					consumerRegion: loaded.region
 				};
 				if (envHasIntrinsicValue(templateEnv)) {
@@ -57232,36 +57632,24 @@ async function localInvokeCommand(target, options) {
 					if (pseudo) subContext.pseudoParameters = pseudo;
 				}
 				if (envHasCrossStackIntrinsic(templateEnv)) {
-					const built = await buildCrossStackResolver(loaded.region, {
-						...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
-						statePrefix: options.statePrefix,
-						...options.region !== void 0 && { region: options.region },
-						...options.profile !== void 0 && { profile: options.profile }
-					});
-					if (built) {
-						subContext.crossStackResolver = built.resolver;
-						crossStackDispose = built.dispose;
-					}
-				}
-				try {
-					const { env, audit } = await substituteEnvVarsFromStateAsync(templateEnv, subContext);
-					templateEnv = env;
-					stateAudit = audit;
-					for (const key of audit.resolvedKeys) logger.debug(`--from-state: substituted env var ${key} from cdkd state`);
-					for (const { key, reason } of audit.unresolved) logger.warn(`--from-state: could not substitute env var ${key} (${reason}). Override it via --env-vars or it will be dropped.`);
-				} finally {
-					if (crossStackDispose) {
-						crossStackDispose();
-						crossStackDispose = void 0;
-					}
+					const resolver = await stateProvider.buildCrossStackResolver(loaded.region);
+					if (resolver) subContext.crossStackResolver = resolver;
 				}
+				const { env, audit } = await substituteEnvVarsFromStateAsync(templateEnv, subContext);
+				templateEnv = env;
+				stateAudit = audit;
+				const label = stateProvider.label;
+				for (const key of audit.resolvedKeys) logger.debug(`${label}: substituted env var ${key}`);
+				for (const { key, reason } of audit.unresolved) logger.warn(`${label}: could not substitute env var ${key} (${reason}). Override it via --env-vars or it will be dropped.`);
 			}
+		} finally {
+			stateProvider.dispose();
 		}
 		const overrides = readEnvOverridesFile(options.envVars);
 		const envResult = resolveEnvVars(lambda.logicalId, templateEnv, overrides);
 		for (const key of envResult.unresolved) {
 			if (stateAudit && stateAudit.unresolved.some((u) => u.key === key)) continue;
-			logger.warn(`Environment variable ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${lambda.logicalId}":{"${key}":"<literal>"}}) or pass --from-state to recover deployed values.`);
+			logger.warn(`Environment variable ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${lambda.logicalId}":{"${key}":"<literal>"}}), or pass --from-state (cdkd-deployed) / --from-cfn-stack (cdk-deployed) to recover deployed values.`);
 		}
 		let resolvedAssumeRoleArn;
 		if (typeof options.assumeRole === "string") resolvedAssumeRoleArn = options.assumeRole;
@@ -57831,7 +58219,7 @@ function pickReferencedLogicalId(intrinsic) {
 */
 function createLocalCommand() {
 	const local = new Command("local").description("Local execution of Lambda functions (RIE) and ECS task definitions (Docker required)");
-	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").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 (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). 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 (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). 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-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
+	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").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 (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). 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 (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). 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-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources 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 cdkd stack name; pass an explicit value when CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).action(withErrorHandling(localInvokeCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -58955,7 +59343,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.157.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.158.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());