cdk-local 0.148.4 → 0.149.1

package/dist/{local-studio-BziOGWc5.js → local-studio-D8cHeCcp.js}

@@ -1,8 +1,8 @@
 import { a as runDockerStreaming, c as resolveConfiguredLogLevel, d as setEmbedConfig, i as runDockerForeground, l as getEmbedConfig, n as formatDockerLoginError, o as spawnStreaming, r as getDockerCmd, s as getLogger } from "./docker-cmd-DLX1TqVw.js";
-import { chmodSync, cpSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, createWriteStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import * as path$1 from "node:path";
-import path, { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import path, { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { Command, Option } from "commander";
 import { AssumeRoleCommand, GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
 import { Agent, createServer, request } from "node:http";
@@ -2383,6 +2383,247 @@ function stringifyValue(value) {
 	}
 }
 
+//#endregion
+//#region src/utils/assembly-path.ts
+/**
+* `true` when `candidate` names something strictly beneath `base`, both given
+* as already-resolved absolute paths.
+*
+* The `..` test is SEPARATOR-AWARE rather than a bare `startsWith('..')`,
+* which would also reject a legitimate sibling named `..foo`. The empty-string
+* case is `base` itself; callers decide whether that counts as an escape,
+* because an asset path legitimately names a DIRECTORY while a template path
+* does not.
+*/
+function isInside(base, candidate) {
+	const rel = relative(base, candidate);
+	if (rel === "" || rel === "..") return false;
+	if (rel.startsWith(`..${sep}`)) return false;
+	return !isAbsolute(rel);
+}
+/**
+* `realpath(3)`, or `undefined` for a path that does not fully resolve.
+*
+* `.native` is load-bearing and must not be simplified to `fs.realpathSync`.
+* The plain form is a JavaScript walker that folds `..` LEXICALLY, so it
+* disagrees with the kernel on a target carrying a `..` after a symlinked
+* component — answering `ENOENT` for a path the kernel resolves, and on a
+* case-insensitive filesystem (APFS by default) it can spin on the same shape.
+* `.native` is libuv's `realpath(3)` and throws the same
+* `ENOENT` / `ELOOP` / `EACCES`.
+*/
+function tryRealpath(p) {
+	try {
+		return realpathSync.native(p);
+	} catch {
+		return;
+	}
+}
+/** `fs.readlinkSync`, or `undefined` when `p` is not a symbolic link. */
+function tryReadlink(p) {
+	try {
+		return readlinkSync(p);
+	} catch {
+		return;
+	}
+}
+/**
+* Link follows before the walk gives up and reports the path as unresolvable.
+* It does NOT refuse: an exhausted budget answers `undefined`, which leaves
+* the symlink arm silent and the lexical verdict standing. Safe because the OS
+* gives up first (macOS caps at 32, `ELOOP`), so a chain that reaches this cap
+* is one nothing can open anyway.
+*/
+const MAX_LINK_HOPS = 40;
+/**
+* Unresolvable path COMPONENTS the climb walks before giving up. Bounds the
+* recursion below, which is one frame per component, so a pathological value
+* cannot raise a `RangeError` from inside {@link tryRealpath}'s own `try` (its
+* `catch` would swallow the crash into a silent `undefined`).
+*
+* KNOW THAT EXHAUSTING THIS FAILS OPEN, and why that is accepted rather than
+* unnoticed. Unlike {@link MAX_LINK_HOPS}, which has the OS's own `ELOOP` cap
+* behind it, nothing else stops a path of 1 001 absent components: the climb
+* gives up, the symlink arm goes silent, and a value that would land outside
+* reads as CONTAINED on the lexical verdict alone. It is not reachable in
+* effect — such a path cannot exist, so `cdkl invoke`'s `existsSync` refuses it
+* and `start-api`'s `docker run` fails to mount it — but that safety lives in
+* the CONSUMERS, not here. A consumer that neither checks existence nor mounts
+* would need its own answer.
+*/
+const MAX_PATH_COMPONENTS = 1e3;
+/**
+* Where `target` REALLY points, for a path that may not exist yet.
+*
+* `realpathSync` answers only for a path that fully resolves, and it throws
+* `ENOENT` for a DANGLING symbolic link exactly as it does for an absent file.
+* `cdkl start-api` resolves an asset path without an existence check, so an
+* absent or dangling component must not silence the symlink arm.
+*
+* Each unresolvable component is therefore handled by hand: climb to the
+* deepest ancestor that DOES resolve, then re-apply the remaining components,
+* following any symbolic link with `readlink` and re-resolving its target.
+* `undefined` means the walk could not resolve the path at all.
+*
+* For a path that FULLY RESOLVES the answer is the kernel's and is exact. For
+* one that does not exist yet this is a best-effort MODEL of kernel
+* resolution; the known edge is a `..` INSIDE an unresolvable link's target,
+* folded lexically here while the kernel folds it only after following each
+* preceding component. That edge is benign for THESE callers rather than in
+* general: it needs the target to be absent, and both consumers resolve the
+* path and then open or mount it, so the divergence is between this model and
+* a path nothing can reach. A caller that CREATED a file through such a path
+* would need an `lstat` of its own.
+*
+* `EACCES` is folded into "does not resolve" along with `ENOENT`, so a link
+* under a directory this process cannot traverse reads as contained. Same
+* bound: the consumer's own `existsSync` / mount runs as the same user and
+* fails identically.
+*/
+function resolveThroughLinks(target, hops = 0, climbs = 0) {
+	const direct = tryRealpath(target);
+	if (direct !== void 0) return direct;
+	if (hops >= MAX_LINK_HOPS) return void 0;
+	if (climbs >= MAX_PATH_COMPONENTS) return void 0;
+	const parent = dirname(target);
+	if (parent === target) return void 0;
+	const realParent = resolveThroughLinks(parent, hops, climbs + 1);
+	if (realParent === void 0) return void 0;
+	const link = tryReadlink(target);
+	if (link === void 0) return join(realParent, basename(target));
+	return resolveThroughLinks(resolve(realParent, link), hops + 1, climbs);
+}
+/**
+* Resolve an assembly-supplied `candidate` against `dir` and report whether
+* the result stays inside it.
+*
+* The lexical arm joins exactly the way the call sites used to (`path.join`,
+* NOT `path.resolve`), so the verdict is about the path the caller will
+* actually use. `join`'s handling of an absolute candidate makes this arm
+* strictly more permissive than a `resolve`-based one would be; an absolute
+* value is therefore answered by {@link absoluteAssemblyPathEscape} instead,
+* because this function structurally cannot.
+*
+* The SYMLINK arm exists because the lexical arm alone leaves an equivalent
+* hole: `cdk.out/link -> /etc` plus a candidate of `link/passwd` is lexically
+* contained and still reaches `/etc/passwd`. Both sides go through
+* {@link resolveThroughLinks}, so an assembly directory REACHED through a link
+* (macOS spells `/tmp` as `/private/tmp`) is unaffected.
+*
+* The verdict is about the assembly AS IT SITS ON DISK. It is NOT a defence
+* against a process rewriting that directory concurrently — the caller uses
+* the path after this returns.
+*/
+function resolveAssemblyPath(dir, candidate, options) {
+	const base = resolve(dir);
+	const bound = options?.containWithin === void 0 ? base : resolve(options.containWithin);
+	const joined = resolve(join(base, candidate));
+	if (!isInside(bound, joined)) return {
+		contained: false,
+		escape: "lexical",
+		path: joined
+	};
+	const realBound = resolveThroughLinks(bound);
+	if (realBound !== void 0) {
+		const realTarget = resolveThroughLinks(joined);
+		if (realTarget !== void 0 && !isInside(realBound, realTarget)) return {
+			contained: false,
+			escape: "symlink",
+			path: joined,
+			realPath: realTarget
+		};
+	}
+	return {
+		contained: true,
+		path: joined
+	};
+}
+/**
+* Whether an ALREADY-ABSOLUTE assembly-supplied path lies outside `bound`.
+*
+* {@link resolveAssemblyPath} cannot answer this, and the reason is structural
+* rather than an oversight: its lexical arm joins with `path.join`, which does
+* NOT honour a leading separator, so an absolute candidate is folded INTO the
+* directory and the verdict would describe a path no caller opens. A site that
+* HONOURS an absolute value needs the verdict about the value itself.
+*
+* The callers are `cdkl invoke`'s and `cdkl start-api`'s
+* `Metadata['aws:asset:path']` resolution. Those honour an absolute path
+* because `cdk synth --no-staging` emits one — CDK writes the asset's absolute
+* SOURCE directory under `aws:cdk:disable-asset-staging`, usually outside the
+* outdir — and they WARN rather than refuse when it leaves the bound, so this
+* returns a verdict rather than throwing.
+*
+* It lives HERE so the containment rule has one spelling: it reuses this
+* module's own {@link isInside} and {@link resolveThroughLinks}, symlink arm
+* included, rather than letting a caller re-spell `path.relative` and drift.
+*
+* `bound` itself is NOT an escape, unlike in {@link resolveAssemblyPath},
+* where an empty `path.relative` means "names the directory rather than a file
+* inside it". An asset path legitimately names a DIRECTORY, so a value equal
+* to the bound is inside it and reporting it as outside would be false.
+*
+* THE REAL PATHS DECIDE IN BOTH DIRECTIONS, which is the one place this
+* deliberately does more than {@link resolveAssemblyPath}'s lexical-first
+* ordering. The lexical verdict here is about a SPELLING, and two spellings of
+* the same directory are common rather than exotic: macOS resolves `/tmp` to
+* `/private/tmp` and `/var` to `/private/var`, and a user may symlink `cdk.out`
+* itself. With an outdir of `/tmp/cdk.out` and a `--no-staging` value of
+* `/private/tmp/cdk.out/src`, a lexical-only verdict cries "pointing outside
+* the assembly ... treat this assembly as untrusted" about an asset that is
+* plainly inside it — and this arm exists to make an UNEXPECTED path visible,
+* so a false alarm is the failure that costs it its meaning.
+*
+* Exonerating requires the kernel to answer for BOTH operands: an unresolvable
+* one leaves the lexical verdict standing, so the arm stays loud when it cannot
+* see. (`resolveAssemblyPath` cannot take the same shape: its verdict is about
+* a path built with `path.join`, and letting a real path overrule the lexical
+* `..` there would answer about a location the caller never opens.)
+*/
+function absoluteAssemblyPathEscape(bound, absolutePath) {
+	const resolvedBound = resolve(bound);
+	const target = resolve(absolutePath);
+	const lexicallyOutside = !isInside(resolvedBound, target) && target !== resolvedBound;
+	const realBound = resolveThroughLinks(resolvedBound);
+	const realTarget = resolveThroughLinks(target);
+	const reallyOutside = realBound === void 0 || realTarget === void 0 ? void 0 : !isInside(realBound, realTarget) && realTarget !== realBound;
+	if (lexicallyOutside) {
+		if (reallyOutside === false) return void 0;
+		return {
+			contained: false,
+			escape: "lexical",
+			path: target
+		};
+	}
+	if (reallyOutside === true) return {
+		contained: false,
+		escape: "symlink",
+		path: target,
+		realPath: realTarget
+	};
+}
+/**
+* The shared tail of a containment refusal: what the value resolved to, what
+* it escaped, and why that means the assembly is not CDK-generated. The call
+* site supplies its own subject ("Lambda 'X' has ... which ") and its own
+* error class. `action` completes "Refusing to ..." and is REQUIRED rather
+* than defaulted: a default is a branch no caller takes, so it can neither be
+* fenced nor be right for the next caller.
+*/
+function renderAssemblyPathEscape(escape, dir, action) {
+	const provenance = `CDK emits assembly paths that stay inside the assembly directory; one that leaves it indicates the synth output was hand-modified or generated by a non-CDK toolchain. Refusing to ${action}.`;
+	const base = resolve(dir);
+	const realBase = resolveThroughLinks(base) ?? base;
+	const shownPath = sanitizeServiceExceptionMessage(escape.path);
+	const shownBase = sanitizeServiceExceptionMessage(base);
+	if (escape.escape === "symlink") {
+		if (escape.realPath === realBase) return `resolves to '${shownPath}', a symbolic link to the directory '${shownBase}' itself rather than to a path inside it. ${provenance}`;
+		return `resolves to '${shownPath}', which leads through a symbolic link to '${sanitizeServiceExceptionMessage(escape.realPath)}', outside '${shownBase}'. ${provenance}`;
+	}
+	if (escape.path === base) return `names the directory '${shownBase}' itself rather than a path inside it. ${provenance}`;
+	return `resolves to '${shownPath}', outside '${shownBase}'. ${provenance}`;
+}
+
 //#endregion
 //#region src/local/lambda-resolver.ts
 /**
@@ -2647,6 +2888,325 @@ function extractImageLambdaProperties(args) {
 	};
 }
 /**
+* Where a Lambda's `Metadata['aws:asset:path']` really lives on this host
+* (go-to-k/cdkd#3534, applying the decision taken in go-to-k/cdkd#3494).
+*
+* THE one spelling shared by `cdkl invoke`'s resolver and `cdkl start-api`'s,
+* which each carried their own copy of `isAbsolute(p) ? p : resolve(dir, p)`.
+* A second hand-written copy is how a guard on one twin becomes a guard on
+* neither. It throws through the CALLER's `wrapError` so each site keeps its
+* own error class and names its own command.
+*
+* TWO VALUE SHAPES, ANSWERED DIFFERENTLY, and the asymmetry is the decision
+* rather than an accident:
+*
+* - RELATIVE, escaping. REFUSED. `path.resolve` folds `..` exactly as
+*   `path.join` does, so `../../../home/<user>/.aws` leaves the assembly, and
+*   nothing a real `cdk synth` emits has that shape.
+* - ABSOLUTE. ACCEPTED, with a WARNING naming the path when it leaves the
+*   asset outdir, and SILENCE when it does not.
+*
+* **Why absolute is accepted, when the security axis argued for refusing it.**
+* `cdk synth --no-staging` (context flag `aws:cdk:disable-asset-staging`) makes
+* upstream `AssetStaging.relativeStagedPath` return the staged path verbatim
+* instead of relativising it, so `aws:asset:path` is the asset's absolute
+* SOURCE directory, normally outside the outdir. Refusing it therefore rejects
+* the output of a documented CDK CLI flag, and the user's view is simply that
+* cdk-local will not read what `cdk` just wrote. Record both halves of the
+* trade, because a later reader must not "restore" the refusal as an
+* oversight:
+*
+* - The security cost is genuine. This value is BIND-MOUNTED read-only at
+*   `/var/task` (or `/opt` for a layer) into a container running handler code
+*   the SAME assembly supplied, and the run may carry the caller's
+*   credentials, so an absolute path a hostile assembly chose reaches the host
+*   filesystem. Nothing here can distinguish a `--no-staging` value from a
+*   planted one: both are an absolute directory the assembly named.
+* - What bounds it: this is a LOCAL developer command run against an assembly
+*   the user pointed at, and the warning names the directory so an unexpected
+*   one is visible rather than silent. **Do not count the read-only mount as
+*   the bound.** It stops writes to the tree, not the capability: a read-only
+*   bind of a directory holding a unix socket (`/var/run`, `/run`) still
+*   permits `connect(2)` on, say, `docker.sock`. The warning is the
+*   mitigation.
+*
+* The `..` containment is NOT relaxed with it, but be precise about what it
+* buys. Against an ADVERSARY it stops nothing: they write the ABSOLUTE
+* spelling and reach the same place with a warning instead of a refusal. What
+* it still catches is an ACCIDENTAL or legacy `..`, and it costs nothing,
+* which is why the arm stays. There is no containment boundary here any more;
+* the warning is the whole signal.
+*
+* CONTAIN WITHIN `assetOutdir`, NOT the manifest's directory. A Lambda inside
+* a `cdk.Stage` legitimately carries `../asset.<hash>`, because `cdk synth`
+* stages a Stage's assets into the APP's outdir while the Stage's manifest
+* sits in `cdk.out/assembly-<Stage>/`. Binding to the manifest directory
+* refuses every Stage asset as "hand-modified".
+*
+* Exported for unit testing and for `local-start-api.ts`'s copy of the caller.
+*/
+function resolveAssetCodeDirectory(manifestDir, assetPath, wrapError, assetOutdir, logicalId) {
+	if (isAbsolute(assetPath)) {
+		const absolute = resolve(assetPath);
+		const escape = absoluteAssemblyPathEscape(assetOutdir, absolute);
+		if (escape !== void 0) getLogger().warn(`Lambda '${sanitizeServiceExceptionMessage(logicalId)}' has an absolute Metadata['aws:asset:path'] pointing outside the assembly: '${sanitizeServiceExceptionMessage(absolute)}'` + (escape.escape === "symlink" ? ` (through a symbolic link to '${sanitizeServiceExceptionMessage(escape.realPath)}')` : "") + `. ${getEmbedConfig().productName} will read that directory and expose its contents to the container — bind-mounted read-only, or copied when the asset is a .zip or one of several merged layers — where the code in this assembly can read it. This is what cdk synth --no-staging emits, and is expected for it; if you did not synthesize with that flag, treat this assembly as untrusted.`);
+		warnOutsideNamedDirectory(assetOutdir, absolute);
+		return absolute;
+	}
+	const resolved = resolveAssemblyPath(manifestDir, assetPath, { containWithin: assetOutdir });
+	if (!resolved.contained && resolved.escape === "lexical" && resolved.path === resolve(assetOutdir)) {
+		warnOutsideNamedDirectory(assetOutdir, resolved.path);
+		return resolved.path;
+	}
+	if (!resolved.contained) {
+		const climbsOut = assetPath === ".." || assetPath.startsWith(`..${sep}`) || assetPath.startsWith("../");
+		const stageHint = basename(assetOutdir).startsWith("assembly-") && climbsOut ? " This directory is named like a cdk.Stage sub-assembly, but its parent is not an assembly (no manifest.json), so it was treated as the assembly root. If you meant to point --app at a Stage inside an app's output directory, point it at that output directory." : "";
+		throw wrapError(`Lambda '${sanitizeServiceExceptionMessage(logicalId)}' has Metadata['aws:asset:path']='${sanitizeServiceExceptionMessage(assetPath)}' which ${renderAssemblyPathEscape(resolved, assetOutdir, "mount it")}${stageHint}`);
+	}
+	warnOutsideNamedDirectory(assetOutdir, resolved.path);
+	return resolved.path;
+}
+/**
+* The two directories an asset path is judged against — THE one spelling both
+* resolvers derive them with, for the same reason
+* {@link resolveAssetCodeDirectory} is one function: two sites disagreeing
+* about the BOUND is a defect no refusal test can see.
+*
+* Asset paths are relative to the manifest's own directory: the stack's
+* `assetManifestPath` is `<cdk.out>/<stack>.assets.json`, so stripping the
+* filename gives the base.
+*
+* `assetOutdir` is the app's outdir and is the CONTAINMENT bound. An ABSENT
+* one falls back to the base, which is correct for a top-level stack and
+* NARROWS for a Stage — it never opens past the base, so a hand-built
+* `StackInfo` carrying neither field is refused rather than admitted.
+* `AssemblyReader` always sets it.
+*
+* The two fallbacks are asymmetric, and the base's prefers `assetOutdir` over
+* `process.cwd()` deliberately: `AssemblyReader` always sets `assetOutdir` but
+* may leave `assetManifestPath` undefined, and taking `process.cwd()` there
+* produces a base DISJOINT from the bound — nothing under the cwd is inside
+* `cdk.out` — so every asset path is refused with a message blaming the
+* assembly. Fail-closed, so never a hole, but a wrong diagnosis.
+* `process.cwd()` survives only for a `StackInfo` carrying NEITHER field,
+* where base and bound coincide again.
+*
+* A PRESENT `assetOutdir` is never replaced BY THE BASE. It may be replaced by
+* its own ANCESTOR, and only in one shape: {@link assemblyRootOf} climbs when
+* `--app` names a `cdk.Stage` sub-assembly. That is a real widening, decided
+* partly by a file inside the tree being examined, and every instance of it is
+* warned — the reasoning is on `assemblyRootOf` and must be read with this
+* paragraph, not instead of it. **Do not restate the stronger claim here.** An
+* earlier revision of this block said the bound is used "AS GIVEN" after the
+* climb had already made that false, which is the same failure this PR
+* repaired in `StackInfo.assetOutdir`'s own doc one commit earlier.
+*
+* Note also that this helper is no longer pure: the climb reads the filesystem
+* and can emit a log line.
+*
+* The base/bound asymmetry is a trust boundary rather than a style choice:
+* `assetOutdir` comes from the user's own `--app` / `--output`, while
+* `manifestDir` is derived from `AssetManifestArtifact.file`, which cx-api
+* resolves out of the assembly's OWN `manifest.json` — so the base is
+* assembly-CONTROLLED and the bound is not. An earlier revision dropped a
+* present bound whenever it was not an ancestor of the base, meaning to
+* improve the diagnosis for a host that supplied a nonsense bound; measured,
+* it let a planted `"file": "../../../../x.assets.json"` push `manifestDir` to
+* `/` and carry the bound with it, so a plain relative `etc/passwd` resolved
+* CONTAINED. A disjoint host-supplied bound refusing everything is a wrong
+* DIAGNOSIS; a widened bound is the vulnerability this module exists to stop.
+*
+* State the property precisely, because the obvious stronger version is FALSE:
+* it is NOT that "the base left the bound, so everything resolved against it is
+* outside" — a candidate can climb back in (`app/cdk.out/asset.9f1` from a base
+* of `/Users/dev`). What holds is that THE BOUND IS ENFORCED INDEPENDENTLY OF
+* THE BASE, so a planted `file` can steer where a relative value resolves FROM
+* and can still only reach inside the BOUND — the user's own outdir, or the
+* root `assemblyRootOf` derived from it, which is the one case where a planted
+* tree can influence the bound and is warned for exactly that reason. A later reader leaning on the stronger sentence would think a
+* separate base check is redundant.
+*
+* An EMPTY string is treated as ABSENT rather than as a bound, because
+* `path.resolve('')` is the cwd — a directory the host never named. It takes
+* the same fallback as `undefined`.
+*
+* KNOW WHAT THE ABSENT CASE BUYS, which is NOT "a narrower bound": the
+* fallback is `manifestDir`, and that is assembly-derived, so a `StackInfo`
+* carrying no `assetOutdir` gets NO containment rather than a tighter one — a
+* planted `file` moves base and bound together. It is unreachable through
+* `AssemblyReader`, which always sets `assetOutdir` from `cloudAssembly.directory`,
+* and it is what cdkd does; a library host that builds `StackInfo` by hand and
+* wants the guard must supply the field.
+*
+* Exported for `local-start-api.ts`'s copy of the caller, and for unit testing.
+*/
+function assetPathDirs(stack) {
+	const bound = stack.assetOutdir === "" ? void 0 : stack.assetOutdir;
+	const manifestDir = stack.assetManifestPath ? dirname(stack.assetManifestPath) : bound ?? process.cwd();
+	return {
+		manifestDir,
+		assetOutdir: bound === void 0 ? manifestDir : assemblyRootOf(bound)
+	};
+}
+/**
+* The real assembly ROOT for a `--app` that names a `cdk.Stage`
+* SUB-assembly.
+*
+* When a user points `--app` at `cdk.out/assembly-MyStage`, the assembly they
+* are working with is rooted at `cdk.out` — `cdk synth` writes the Stage's
+* manifest into the sub-directory and stages its ASSETS one level above, so
+* CDK's own `../asset.<hash>` is a within-assembly reference. Bounding at the
+* named directory made every one of those look like an escape, and the
+* refusal had to append a paragraph explaining that the layout "is not a
+* tamper" — a guard that has to talk you out of its own verdict is computing
+* the wrong thing.
+*
+* **It is a CONVENIENCE, not a safety property, and an earlier revision of
+* this comment claimed the opposite.** That revision argued the climb is safe
+* because it runs on a USER-supplied value. That is true of the STRING and
+* false of the DECISION: the predicate is a directory NAME and the presence of
+* a FILE, both inside the tree being examined — which under this module's own
+* threat model is the attacker's. An archive unpacking as `manifest.json` +
+* `assembly-X/` into a user's home, run as `--app ~/assembly-X`, moved the
+* bound to `~`, after which `../.aws` resolved CONTAINED and was mounted with
+* no refusal and no warning. It had been refused before the climb existed.
+*
+* So the climb is bounded by two things that are not arguments:
+*
+* 1. **It WARNS every time it fires** (see {@link warnDerivedAssemblyRoot}),
+*    naming the directory the user passed and the one derived from it. The
+*    module's doctrine for an absolute path applies here unchanged — a
+*    directory the user did not name must be visible rather than silent — and
+*    it costs one line on the legitimate Stage path.
+* 2. **The parent must DECLARE this child**, not merely sit above it: its
+*    `manifest.json` must parse and carry a `cdk:cloud-assembly` artifact
+*    whose `properties.directoryName` is this directory's basename, which is
+*    cx-api's own invariant. This removes the accidental collision entirely
+*    (`manifest.json` is not a CDK-exclusive filename) and makes the hostile
+*    case require a purpose-built manifest. It does NOT make the climb safe
+*    against someone who ships the whole tree — they can write that manifest
+*    too. Point 1 is what covers that, which is why it is first.
+*
+* `manifestDir` never climbs: it stays `dirname(assetManifestPath)`, the
+* assembly-derived value, and is still judged against whatever this returns.
+*
+* Returns the caller's own spelling UNCHANGED when no climb happens, because
+* the bound is used as given elsewhere and normalising it would make a
+* relative `--output cdk.out` come back absolute for every ordinary app.
+*/
+function assemblyRootOf(outdir) {
+	const cached = derivedRootCache.get(outdir);
+	if (cached !== void 0) return cached;
+	const root = climbToAssemblyRoot(outdir);
+	derivedRootCache.set(outdir, root);
+	return root;
+}
+/** The climb itself; {@link assemblyRootOf} holds the reasoning and memoizes. */
+function climbToAssemblyRoot(outdir) {
+	let dir = resolve(outdir);
+	let climbed = false;
+	for (;;) {
+		if (!basename(dir).startsWith("assembly-")) break;
+		const parent = dirname(dir);
+		if (parent === dir || !parentDeclaresNestedAssembly(parent, basename(dir))) break;
+		dir = parent;
+		climbed = true;
+	}
+	if (!climbed) return outdir;
+	derivedRootOrigins.set(dir, outdir);
+	warnDerivedAssemblyRoot(outdir, dir);
+	return dir;
+}
+/**
+* Whether `parent`'s own `manifest.json` declares `child` as a nested
+* assembly, which is what cx-api writes for a `cdk.Stage`.
+*
+* Tolerant by construction: an unreadable or unparseable manifest, or one with
+* no matching artifact, answers `false` and the climb stops — the conservative
+* direction, since not climbing only restores the previous refusal.
+*/
+function parentDeclaresNestedAssembly(parent, child) {
+	try {
+		const raw = readFileSync(join(parent, "manifest.json"), "utf-8");
+		const artifacts = JSON.parse(raw).artifacts;
+		if (artifacts === null || typeof artifacts !== "object") return false;
+		return Object.values(artifacts).some((a) => {
+			const art = a;
+			return art?.type === "cdk:cloud-assembly" && art.properties?.directoryName === child;
+		});
+	} catch {
+		return false;
+	}
+}
+/**
+* Per-process state for the climb. `assetPathDirs` runs once per Lambda AND
+* once per layer, so without the cache a real `cdk.out/manifest.json` —
+* routinely multi-MB — is re-read and re-parsed for every one of them, and
+* `--watch` repeats that per firing. It is also the amplification bound on an
+* attacker-sized manifest.
+*
+* **A cached root can outlive its own evidence, and only in the already-warned
+* direction.** If a `--watch` re-synth rewrites the parent so it no longer
+* declares the child, the cache keeps answering the WIDE root while a fresh
+* derivation would decline and narrow. That grants nothing new: the root
+* warning fired for that root when it was first derived, and re-deriving can
+* only narrow. The reverse — cached narrow, a declaring manifest appears
+* later — stays narrow, which is fail-closed. So the cache cannot introduce an
+* UNWARNED widening in either direction.
+*
+* Keyed by the raw outdir STRING and never evicted. Sound because the same
+* string names the same directory: a second assembly reusing an outdir is the
+* same tree, and a changed tree under it is case A above. Growth is one entry
+* per distinct `--app`, and a climb only happens under `readFromDirectory`
+* where that argument is constant for the process.
+*/
+const derivedRootCache = /* @__PURE__ */ new Map();
+/**
+* Derived root -> the directory the user actually named. LAST WRITER WINS, and
+* the consequence is always a WRONG NAME, never a missing warning: two sibling
+* Stages climbing to one root make the per-path line name the other sibling,
+* and a long-lived host that processes assembly A (climbed to `/x/cdk.out`)
+* and then assembly B whose `--app` IS `/x/cdk.out` names A's Stage directory
+* throughout run B. The root and the offending path stay correct in both.
+* Both are a wrong NAME in a line that still fires with the right root and the
+* right path, which is why neither buys an eviction policy.
+*/
+const derivedRootOrigins = /* @__PURE__ */ new Map();
+const warnedDerivedRoots = /* @__PURE__ */ new Set();
+const warnedOutsideNamed = /* @__PURE__ */ new Set();
+/**
+* Warn that an accepted path leaves the directory the user NAMED, when the
+* bound was widened by a climb.
+*
+* **This is what makes the climb's signal as loud as the absolute arm's.**
+* Without it the two diverge in the attacker's favour: an absolute path warns
+* PER LAMBDA naming the exact directory, while a climb warned once at startup
+* about the root and then mounted each individual path in silence — so
+* whoever gets the climb converts a per-mount warning into a one-line notice.
+* Now both arms say something per path that leaves what the user asked for.
+*/
+function warnOutsideNamedDirectory(assetOutdir, resolved) {
+	const named = derivedRootOrigins.get(assetOutdir);
+	if (named === void 0) return;
+	if (absoluteAssemblyPathEscape(named, resolved) === void 0) return;
+	if (warnedOutsideNamed.has(resolved)) return;
+	warnedOutsideNamed.add(resolved);
+	getLogger().warn(`'${sanitizeServiceExceptionMessage(resolved)}' is outside '${sanitizeServiceExceptionMessage(named)}', the directory --app named. It is inside the assembly root derived from it, so ${getEmbedConfig().productName} is using it.`);
+}
+/**
+* Say that the assembly root was DERIVED rather than given.
+*
+* The user named one directory and the containment bound is another, wider
+* one. On the legitimate Stage path that is exactly what they wanted and the
+* line is informative; on a hostile tree it is the only signal that a sibling
+* of the directory they named is now inside the bound.
+*/
+function warnDerivedAssemblyRoot(named, derived) {
+	if (warnedDerivedRoots.has(derived)) return;
+	warnedDerivedRoots.add(derived);
+	getLogger().warn(`'${sanitizeServiceExceptionMessage(named)}' is a cdk.Stage sub-assembly, so ${getEmbedConfig().productName} is treating its parent '${sanitizeServiceExceptionMessage(derived)}' as the assembly root — that is where cdk synth stages a Stage's assets. Everything under that parent is now inside the containment bound, including siblings of the directory you named. If you did not expect the wider directory, point --app at the app's own output directory instead.`);
+}
+/**
 * Resolve the local directory that corresponds to a function's deployed
 * asset, using the CDK-blessed `Metadata['aws:asset:path']` hint (D2). The
 * value is a directory path relative to `cdk.out` (e.g. `asset.abc123def`)
@@ -2656,18 +3216,21 @@ function extractImageLambdaProperties(args) {
 * Falls back to a clear error when the metadata is missing OR the resolved
 * directory does not exist (CDK should always emit it for asset-backed
 * Lambdas; absence usually means the user pre-synthesized with a different
-* cdk.out and pointed `--output` at a stale one).
+* cdk.out and pointed `--output` at a stale one). Through
+* {@link resolveAssetCodeDirectory} it REFUSES an escaping RELATIVE value and
+* WARNS on an ABSOLUTE one that leaves the asset outdir — see that function
+* for why the two differ.
 */
 function resolveAssetCodePath$1(stack, logicalId, resource, options = {}) {
 	const assetPath = resource.Metadata?.["aws:asset:path"];
-	if (typeof assetPath !== "string" || assetPath.length === 0) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has no Metadata['aws:asset:path']. ${getEmbedConfig().cliName} invoke needs this hint to find the local asset directory. Re-synthesize the app (without \`--output <stale-dir>\`) and retry.`);
-	const cdkOutDir = stack.assetManifestPath ? dirname(stack.assetManifestPath) : process.cwd();
-	const abs = isAbsolute(assetPath) ? assetPath : resolve(cdkOutDir, assetPath);
-	if (!existsSync(abs)) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' asset path '${abs}' does not exist. Re-synthesize the app and retry.`);
+	if (typeof assetPath !== "string" || assetPath.length === 0) throw new LocalInvokeResolutionError(`Lambda '${sanitizeServiceExceptionMessage(logicalId)}' has no Metadata['aws:asset:path']. ${getEmbedConfig().cliName} invoke needs this hint to find the local asset directory. Re-synthesize the app (without \`--output <stale-dir>\`) and retry.`);
+	const { manifestDir, assetOutdir } = assetPathDirs(stack);
+	const abs = resolveAssetCodeDirectory(manifestDir, assetPath, (message) => new LocalInvokeResolutionError(message), assetOutdir, logicalId);
+	if (!existsSync(abs)) throw new LocalInvokeResolutionError(`Lambda '${sanitizeServiceExceptionMessage(logicalId)}' asset path '${sanitizeServiceExceptionMessage(abs)}' does not exist. Re-synthesize the app and retry.`);
 	const stat = statSync(abs);
 	if (stat.isDirectory()) return abs;
 	if (options.allowZip && stat.isFile() && abs.toLowerCase().endsWith(".zip")) return abs;
-	throw new LocalInvokeResolutionError(`Lambda '${logicalId}' asset path '${abs}' is not a directory` + (options.allowZip ? " or a .zip archive" : "") + ". Re-synthesize the app and retry.");
+	throw new LocalInvokeResolutionError(`Lambda '${sanitizeServiceExceptionMessage(logicalId)}' asset path '${sanitizeServiceExceptionMessage(abs)}' is not a directory` + (options.allowZip ? " or a .zip archive" : "") + ". Re-synthesize the app and retry.");
 }
 /**
 * Turn a resolved function-code asset path into a directory ready to
@@ -2686,14 +3249,14 @@ function resolveAssetCodePath$1(stack, logicalId, resource, options = {}) {
 * existing tmpdir cleanup.
 */
 function materializeAssetCodeDir(codePath) {
-	if (!existsSync(codePath)) throw new LocalInvokeResolutionError(`Lambda asset path '${codePath}' does not exist. Re-synthesize the app and retry.`);
+	if (!existsSync(codePath)) throw new LocalInvokeResolutionError(`Lambda asset path '${sanitizeServiceExceptionMessage(codePath)}' does not exist. Re-synthesize the app and retry.`);
 	if (statSync(codePath).isDirectory()) return { dir: codePath };
 	const zipBytes = readFileSync(codePath);
 	let files;
 	try {
 		files = unzipSync(zipBytes);
 	} catch (err) {
-		throw new LocalInvokeResolutionError(`Lambda asset '${codePath}' is a file but could not be read as a ZIP archive: ${err instanceof Error ? err.message : String(err)}. Re-synthesize the app and retry.`);
+		throw new LocalInvokeResolutionError(`Lambda asset '${sanitizeServiceExceptionMessage(codePath)}' is a file but could not be read as a ZIP archive: ${err instanceof Error ? err.message : String(err)}. Re-synthesize the app and retry.`);
 	}
 	const modes = parseZipUnixModes(zipBytes);
 	const S_IFMT = 61440;
@@ -2780,7 +3343,7 @@ function resolveSafeZipEntryPath(root, entry) {
 * **Order is preserved**: `Properties.Layers` is iterated left-to-right
 * and the resulting `ResolvedLambdaLayer[]` carries the same order. The
 * caller (`local-invoke.ts`'s `materializeLambdaLayers` and
-* `local-start-api.ts`'s server-boot pre-merge) `cpSync`-merges every
+* `local-start-api.ts`'s server-boot pre-merge) merges every
 * entry into one host tmpdir in template order to honor AWS's
 * "last-layer-wins" file-collision semantics — Docker rejects multiple
 * bind mounts at the same target so cdk-local cannot rely on overlay
@@ -5391,7 +5954,7 @@ var AssemblyReader = class {
 		});
 		const cached = await toolkit.synth(source);
 		try {
-			return cached.cloudAssembly.stacks.map((stack) => mapStackArtifact(stack));
+			return collectStacks(cached.cloudAssembly);
 		} finally {
 			await cached.dispose();
 		}
@@ -5421,19 +5984,54 @@ var AssemblyReader = class {
 		const source = await toolkit.fromAssemblyDirectory(assemblyDir, { failOnMissingContext: false });
 		const cached = await toolkit.synth(source);
 		try {
-			return cached.cloudAssembly.stacks.map((stack) => mapStackArtifact(stack));
+			return collectStacks(cached.cloudAssembly);
 		} finally {
 			await cached.dispose();
 		}
 	}
 };
-function mapStackArtifact(stack) {
+/**
+* Every stack this assembly enumerates, each bounded by the assembly ROOT.
+*
+* NOT `stacksRecursively`, and the omission is a decision rather than an
+* oversight. `CloudAssembly.stacks` lists only this assembly's own artifacts,
+* and a `cdk.Stage` is a `NestedCloudAssemblyArtifact`, so a Stage's stacks are
+* not enumerated at all — a pre-existing gap tracked as
+* [#746](https://github.com/go-to-k/cdk-local/issues/746). Recursing here would
+* close it and is tempting because it also makes `assetOutdir` differ from the
+* manifest directory, which is the shape this module's bound exists for. It is
+* NOT done here because the recursion changes STACK ENUMERATION for every
+* command: eleven call sites read `stacks.length === 1` to offer the
+* "single-stack apps may omit the stack prefix" convenience, `matchStacks`
+* dedupes by `stackName`, and a Stage's clones carry identical logical IDs. That
+* is a feature with its own design and its own tests, not a side effect of a
+* containment fix.
+*
+* The consequence to know: a Stage's stacks are reachable only by pointing
+* `--app` at `cdk.out/assembly-<Stage>/`, which makes that directory the
+* assembly root, so the Stage's own assets — staged into the APP's outdir by
+* `cdk synth` — fall outside it and are refused. `resolveAssetCodeDirectory`'s
+* refusal says so in as many words rather than leaving the user with the
+* generic hand-modified-assembly diagnosis.
+*/
+function collectStacks(assembly) {
+	return assembly.stacks.map((stack) => mapStackArtifact(stack, assembly.directory));
+}
+/**
+* `assetOutdir` is threaded in from the ROOT assembly rather than read off the
+* artifact's own `assembly.directory`: for a stack under a `cdk.Stage` the
+* latter is `cdk.out/assembly-<Stage>/`, which is the manifest directory, not
+* the directory the Stage's assets were staged into. See
+* `StackInfo.assetOutdir`.
+*/
+function mapStackArtifact(stack, assetOutdir) {
 	const info = {
 		stackName: stack.stackName,
 		displayName: stack.displayName ?? stack.id,
 		artifactId: stack.id,
 		template: stack.template,
-		dependencyNames: stack.dependencies.map((d) => d.id)
+		dependencyNames: stack.dependencies.map((d) => d.id),
+		assetOutdir
 	};
 	if (stack.environment.region) info.region = stack.environment.region;
 	if (stack.environment.account) info.account = stack.environment.account;
@@ -8372,6 +8970,61 @@ function resolveRuntimeCodeMountPath(runtime) {
 //#endregion
 //#region src/assets/docker-build.ts
 /**
+* Announce that a Docker asset's `source.executable` is about to run.
+*
+* The command line comes from the asset manifest, which is chosen by whoever
+* wrote the assembly, and cdk-local SPAWNS it — so a `cdkl` command against a
+* pre-synthesized assembly executes code the CloudFormation template does not
+* show. It is RUN, never refused: CDK CLI's `buildExternalAsset` does the same,
+* and an assembly is trusted input. What was missing is the line saying so.
+*
+* **It names `executable[0]` and an argument COUNT, deliberately, and the full
+* argv must stay at `debug`.** Rendering every argument at warn level is a new
+* leak introduced by a warning about leaks: a build script is not `docker
+* build`, so its own `--token ghp_…` or `--password=…` matches no argv masker's
+* flag shapes, and the warning would promote it from `--verbose`-only to a line
+* in every CI log of every run. That was a live defect in the host's copy of
+* this warning (go-to-k/cdkd#3497); do not "improve" this by expanding it.
+*
+* Placed in `buildDockerImage` rather than at a call site because this is the
+* ONE spawn point: `docker-image-builder.ts` (`invoke` / `start-api` /
+* `invoke-agentcore` / `start-agentcore`, the last two through
+* `resolveAgentCoreImage`) and `ecs-task-runner.ts` (`run-task` /
+* `start-service` / `start-alb`) both reach it, and `studio` inherits it by
+* spawning those as children. The two ECS server commands were the gap
+* (go-to-k/cdkd#3540) — the host cannot warn for them, since it re-exports
+* `runEcsServiceEmulator` as a bare passthrough and the asset build happens
+* several layers inside this engine.
+*
+* **Announced ONCE per distinct command line per process, not once per
+* spawn.** The spawn genuinely repeats — `ecs-service-runner.ts` boots every
+* replica through `bootReplica` and restarts a crashed one the same way, and
+* the agentcore commands re-resolve on reload — so a `DesiredCount: 3` service
+* would print this ~450-character paragraph three times at boot and again per
+* crash-loop restart. That is a storm, and a storm is not read. Repeats drop
+* to `debug`, where the argv already is. Deduping the LINE must never dedupe
+* the WORK: the spawn happens every time regardless.
+*
+* `sanitizeServiceExceptionMessage` for the same reason `assembly-path.ts`
+* uses it: the value is manifest-chosen, it keeps control characters, and an
+* unsanitized one lets the command forge its own log line. It is applied to
+* the DISPLAYED command only — the dedupe key is built from the raw argv and
+* cwd, so two commands differing only in control characters stay distinct
+* keys.
+*/
+const warnedExecutables = /* @__PURE__ */ new Set();
+function warnManifestExecutable(cmd, executable, cwd) {
+	const logger = getLogger().child("docker-build");
+	const key = JSON.stringify([cwd, executable]);
+	if (warnedExecutables.has(key)) {
+		logger.debug(`source.executable already announced this process: ${sanitizeServiceExceptionMessage(cmd)} (cwd=${cwd})`);
+		return;
+	}
+	warnedExecutables.add(key);
+	const argCount = executable.length - 1;
+	logger.warn(`Docker asset source.executable runs a command this asset manifest chose, on this machine: '${sanitizeServiceExceptionMessage(cmd)}'` + (argCount > 0 ? ` (with ${argCount} argument(s); --verbose shows them)` : "") + ". cdk-local runs it, matching the CDK CLI — a pre-synthesized assembly is trusted input. Note that this means running a local command against a pre-synthesized assembly DOES execute code from it, which the CloudFormation template does not show.");
+}
+/**
 * Build a Docker image from a CDK asset source. Returns the local image
 * tag the caller should use for `docker tag` / `docker push` (publisher)
 * or `docker run` (local-invoke).
@@ -8394,6 +9047,7 @@ async function buildDockerImage(asset, cdkOutDir, options) {
 		if (!cmd) throw options.wrapError("asset source.executable[] is empty");
 		const cwd = source.directory ? `${cdkOutDir}/${source.directory}` : cdkOutDir;
 		logger.debug(`Building Docker image via executable: ${source.executable.join(" ")} (cwd=${cwd})`);
+		warnManifestExecutable(cmd, source.executable, cwd);
 		let result;
 		try {
 			result = await spawnStreaming(cmd, args, { cwd });
@@ -17254,6 +17908,110 @@ function looksLikeAccessDenied(err) {
 	return name === "AccessDeniedException" || code === "AccessDeniedException" || /access denied/i.test(message) || /not authorized/i.test(message);
 }
 
+//#endregion
+//#region src/local/layer-tree-copy.ts
+/**
+* Merge one Lambda Layer's asset tree into the directory that will be
+* bind-mounted at `/opt`, with AWS's "last layer wins" semantic and with
+* symlinks kept VERBATIM (issue #727).
+*
+* Why this is a hand-written walk and not `cpSync`. The merge used to be
+* `cpSync(src, dest, { recursive: true, force: true })`, and every
+* `cpSync`-shaped repair of it was measured wrong in some direction:
+*
+*   - Without `verbatimSymlinks: true` (the default), `cpSync` rewrites a
+*     RELATIVE link target to the ABSOLUTE path of the source on the host —
+*     `bin/rel-link -> real.sh` arrives as `-> <cdk.out>/asset.<hash>/bin/
+*     real.sh`, which is dangling inside the container, where only `dest`
+*     is mounted. Measured on Node 22.12 / 24.21.
+*   - WITH `verbatimSymlinks: true`, Node's C++ `cpSync` (every release
+*     after 22.12) throws `EEXIST` when a later layer carries a symlink at a
+*     path an earlier layer already placed one — `nodejs/node_modules/.bin/
+*     <tool>` in two layers built from the same dependency is the ordinary
+*     case. Measured by the go-to-k/cdkd#3118 review (the cdkd twin) on 22.23 / 24.15 /
+*     24.21; the JS implementation on 22.12 does not throw, which is why
+*     the floor alone did not show it.
+*   - A `cpSync` + `readdirSync({ recursive: true })` pair was worse:
+*     the recursive readdir DESCENDS INTO directory symlinks on every Node
+*     after 22.12 (not on 22.12), so a cyclic link (`sub/up -> ..`, or a
+*     pnpm-style `node_modules`) hung the merge, and an absolute link to a
+*     host directory made the walk delete and write INSIDE that host
+*     directory. And `cpSync`'s `force` writes THROUGH a destination that
+*     is already a directory symlink, so a later layer's real directory
+*     landed in the earlier layer's link target — on the host, when the
+*     link was absolute. Same review, same versions.
+*
+* So the walk is explicit and recurses only on a real directory (`d_type`,
+* via `Dirent.isDirectory()`, which reports a directory symlink as a
+* symlink on 22.12 and 24.21 alike). Per entry, "last layer wins" is applied
+* the same way for every kind: whatever sits at the destination path that is
+* not of the same kind is removed first — a link, a file, or a whole
+* directory an earlier layer placed — then the entry lands. A symlink is
+* recreated with the SOURCE's own target string and never resolved, so an
+* absolute link stays absolute and a dangling one stays dangling, exactly as
+* AWS extracts the layer ZIP into `/opt`; nothing is ever written through a
+* link. A file is copied with `cpSync` (single file, `force`), which is what
+* preserves the mode bits, so a layer's `bin/<script>` keeps its `+x` — the
+* property the `local-invoke-layers` fixture executes through.
+*
+* The ROOT may itself be a symlink (an asset dir handed over through a link
+* passes `resolveAssetCodePath`'s `statSync`). `readdirSync` follows a root
+* link by itself, so the `realpathSync` is not what makes that case work,
+* and it does not move where a dangling or looping root fails either (the
+* first `readdirSync` raises the same `ENOENT` / `ELOOP` naming the asset
+* path); it only keeps every path the walk joins real.
+*
+* Bound, stated rather than handled: a FIFO or a socket inside a layer
+* makes the single-file `cpSync` throw (`ERR_FS_CP_FIFO_PIPE` /
+* `ERR_FS_CP_SOCKET`, immediately, never blocking) where the old recursive
+* copy skipped it in silence on some releases. CDK's own asset staging
+* cannot stage such an entry, so no real layer carries one.
+*
+* Both layer merges (`cdkl invoke` and `cdkl start-api`) call
+* this; keep them on the one helper rather than re-spelling copy options.
+*/
+function copyLayerTreeLastWins(src, dest) {
+	mkdirSync(dest, { recursive: true });
+	copyDirLastWins(realpathSync(src), dest);
+}
+function copyDirLastWins(fromDir, toDir) {
+	for (const entry of readdirSync(fromDir, { withFileTypes: true })) {
+		const from = join(fromDir, entry.name);
+		const to = join(toDir, entry.name);
+		if (entry.isSymbolicLink()) {
+			removeUnless(to, "symlink");
+			symlinkSync(readlinkSync(from), to);
+		} else if (entry.isDirectory()) {
+			removeUnless(to, "directory");
+			mkdirSync(to, { recursive: true });
+			copyDirLastWins(from, to);
+		} else {
+			removeUnless(to, "file");
+			cpSync(from, to, { force: true });
+		}
+	}
+}
+/**
+* Clear the destination path unless what is there is already of `kind`. A
+* directory is kept so a later layer MERGES into it; a file is kept because
+* `cpSync` overwrites it in place; a symlink is always replaced (its target
+* string comes from the later layer).
+*/
+function removeUnless(to, kind) {
+	let st;
+	try {
+		st = lstatSync(to);
+	} catch {
+		return;
+	}
+	if (kind === "directory" && st.isDirectory()) return;
+	if (kind === "file" && st.isFile()) return;
+	rmSync(to, {
+		recursive: true,
+		force: true
+	});
+}
+
 //#endregion
 //#region src/local/stage-resolver.ts
 /**
@@ -18692,12 +19450,12 @@ async function resolveLocalBuildPlan$1(lambda) {
 *     when the entry is a same-stack asset. Literal-ARN entries always
 *     pre-materialize first.
 *   - 2+ layers → copy each into a fresh tmpdir IN ORDER (later
-*     layers overwrite earlier files via `cpSync({force: true})`),
+*     layers overwrite earlier files via `copyLayerTreeLastWins`),
 *     bind-mount the tmpdir at `/opt`. Records the tmpdir in
 *     `layerTmpDirs` so `shutdown(...)` removes it.
 *
 * Issue #448: literal-ARN entries (`{kind: 'arn', ...}`) are downloaded
-* + unzipped via `lambda:GetLayerVersion` BEFORE the cpSync-merge
+* + unzipped via `lambda:GetLayerVersion` BEFORE the merge
 * branches run. Every per-ARN tmpdir is also recorded in `layerTmpDirs`
 * so the same shutdown path cleans it up — even for the single-layer
 * fast path that bind-mounts the dir directly.
@@ -18727,10 +19485,15 @@ async function materializeLambdaLayers$1(layers, layerTmpDirs, layerRoleArn) {
 	}
 	if (flat.length === 1) return flat[0].assetPath;
 	const dir = mkdtempSync(path$1.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-start-api-layers-`));
-	for (const layer of flat) cpSync(layer.assetPath, dir, {
-		recursive: true,
-		force: true
-	});
+	try {
+		for (const layer of flat) copyLayerTreeLastWins(layer.assetPath, dir);
+	} catch (error) {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
 	layerTmpDirs.add(dir);
 	return dir;
 }
@@ -18863,12 +19626,18 @@ function resolveImageLambda(args) {
 * Locate the Lambda's local code directory using the CDK-blessed
 * `Metadata['aws:asset:path']` hint. Bind-mounted directly at
 * `/var/task` (read-only) by the docker-runner.
+*
+* The resolution itself is `lambda-resolver.ts`'s
+* {@link resolveAssetCodeDirectory} — THE one spelling, so this twin and
+* `cdkl invoke`'s cannot disagree about the containment bound. It REFUSES an
+* escaping RELATIVE value and WARNS on an ABSOLUTE one that leaves the asset
+* outdir; that function's header records why the two shapes differ.
 */
 function resolveAssetCodePath(stack, logicalId, resource) {
 	const assetPath = resource.Metadata?.["aws:asset:path"];
-	if (typeof assetPath !== "string" || assetPath.length === 0) throw new Error(`Lambda '${logicalId}' has no Metadata['aws:asset:path']. ${getEmbedConfig().cliName} start-api needs this hint to find the local asset directory. Re-synthesize the app and retry.`);
-	const cdkOutDir = stack.assetManifestPath ? path$1.dirname(stack.assetManifestPath) : process.cwd();
-	return path$1.isAbsolute(assetPath) ? assetPath : path$1.resolve(cdkOutDir, assetPath);
+	if (typeof assetPath !== "string" || assetPath.length === 0) throw new Error(`Lambda '${sanitizeServiceExceptionMessage(logicalId)}' has no Metadata['aws:asset:path']. ${getEmbedConfig().cliName} start-api needs this hint to find the local asset directory. Re-synthesize the app and retry.`);
+	const { manifestDir, assetOutdir } = assetPathDirs(stack);
+	return resolveAssetCodeDirectory(manifestDir, assetPath, (message) => new Error(message), assetOutdir, logicalId);
 }
 /**
 * Print the discovered route table to stdout. Format mirrors the spec
@@ -19668,10 +20437,15 @@ function materializeLambdaLayers(layers) {
 		readOnly: true
 	} };
 	const tmpDir = mkdtempSync(path$1.join(tmpdir(), `${getEmbedConfig().resourceNamePrefix}-invoke-layers-`));
-	for (const layer of layers) cpSync(layer.assetPath, tmpDir, {
-		recursive: true,
-		force: true
-	});
+	try {
+		for (const layer of layers) copyLayerTreeLastWins(layer.assetPath, tmpDir);
+	} catch (error) {
+		rmSync(tmpDir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
 	return {
 		mount: {
 			hostPath: tmpDir,
@@ -40285,4 +41059,4 @@ function addStudioSpecificOptions(cmd) {
 
 //#endregion
 export { applyEdgeResponseResult as $, buildJwksUrlFromIssuer as $n, resolveCfnStackName as $r, buildCloudMapIndex as $t, startAgentCoreHttpServer as A, describeCredentialLoadFailure as Ai, classifySourceChange as An, ConnectionRegistry as Ar, addRunTaskSpecificOptions as At, idFromArn as B, buildStageMap as Bn, resolveRuntimeFileExtension as Br, resolveEcsAssumeRoleOption as Bt, addListSpecificOptions as C, resolveAgentCoreTarget as Ci, waitForAgentCorePing as Cn, tryParseStatus as Cr, parseLbPortOverrides as Ct, createLocalStartAgentCoreCommand as D, tryResolveImageFnJoin as Di, computeCodeImageTag as Dn, probeHostGatewaySupport as Dr, addStartServiceSpecificOptions as Dt, addStartAgentCoreSpecificOptions as E, substituteImagePlaceholders as Ei, buildAgentCoreCodeImage as En, HOST_GATEWAY_MIN_VERSION as Er, resolveAlbFrontDoor as Et, createLocalStartCloudFrontCommand as F, createWatchPredicates as Fn, buildDisconnectEvent as Fr, addImageOverrideOptions as Ft, classifyS3Error as G, filterRoutesByApiIdentifiers as Gn, substituteEnvVarsFromState as Gr, enforceImageOverrideOrphans as Gt, createDeployedKvsDataSource as H, resolveEnvVars$1 as Hn, EcsTaskResolutionError as Hr, runEcsServiceEmulator as Ht, normalizeKvsFileKeys as I, resolveApiTargetSubset as In, buildMessageEvent as Ir, buildEcsImageResolutionContext$1 as It, startCloudFrontServer as J, startApiServer as Jn, createLocalStateProvider as Jr, resolveImageOverrides as Jt, createS3OriginReader as K, groupRoutesByServer as Kn, substituteEnvVarsFromStateAsync as Kr, mergeForService as Kt, parseKvsFileOverrides as L, createAuthorizerCache as Ln, architectureToPlatform as Lr, ecsClusterOption as Lt, startAgentCoreWsBridge as M, resolveProfileCredentials as Mi, createLocalInvokeCommand as Mn, handleConnectionsRequest as Mr, MAX_TASKS_SUBNET_RANGE_CAP as Mt, LocalStartCloudFrontError as N, buildProxyClientConfig as Ni, addStartApiSpecificOptions as Nn, parseConnectionsPath as Nr, addCommonEcsServiceOptions as Nt, buildAgentCoreServeAuthCheck as O, LocalInvokeBuildError as Oi, renderCodeDockerfile as On, resolveHostGatewayExtraHosts as Or, createLocalStartServiceCommand as Ot, addStartCloudFrontSpecificOptions as P, isProxyEnvConfigured as Pi, createLocalStartApiCommand as Pn, buildConnectEvent as Pr, addEcsAssumeRoleOptions as Pt, applyEdgeRequestResult as Q, buildCognitoJwksUrl as Qn, resolveCfnRegion as Qr, listPinnedTargets as Qt, parseOriginOverrides as R, createFileWatcher as Rn, buildContainerImage as Rr, parseMaxTasks as Rt, StudioEventBus as S, pickAgentCoreCandidateStack as Si, waitForAgentCoreHttpReady as Sn, selectIntegrationResponse as Sr, createLocalStartAlbCommand as St, formatTargetListing as T, formatStateRemedy as Ti, SUPPORTED_CODE_RUNTIMES as Tn, HOST_DOCKER_INTERNAL_GATEWAY as Tr, isApplicationLoadBalancer as Tt, resolveDeployedKvsArnByName as U, availableApiIdentifiers as Un, substituteAgainstState as Ur, ImageOverrideError as Ut, resolveKvsModulesForDistribution as V, materializeLayerFromArn as Vn, resolveRuntimeImage as Vr, resolveSharedSidecarCredentials as Vt, resolveDeployedOriginBucket as W, filterRoutesByApiIdentifier as Wn, substituteAgainstStateAsync as Wr, buildImageOverrideTag as Wt, serveFromStaticOrigin as X, resolveServiceIntegrationParameters as Xn, rejectExplicitCfnStackWithMultipleStacks as Xr, describePinnedImageUri as Xt, resolveErrorResponseCandidates as Y, resolveSelectionExpression as Yn, isCfnFlagPresent as Yr, runImageOverrideBuilds as Yt, serveLambdaUrlOrigin as Z, defaultCredentialsLoader as Zn, resolveCfnFallbackRegion as Zr, isLocalCdkAssetImage as Zt, filterStudioTargetGroups as _, AGENTCORE_AGUI_PROTOCOL as _i, parseSseForJsonRpc as _n, applyAuthorizerOverlay as _r, createCloudFrontModule as _t, createLocalStudioCommand as a, countTargets as ai, attachContainerLogStreamer as an, computeRequestIdentityHash as ar, describeS3OriginDomain as at, renderStudioHtml as b, AGENTCORE_RUNTIME_TYPE as bi, AGENTCORE_SESSION_ID_HEADER as bn, evaluateResponseParameters as br, addAlbSpecificOptions as bt, startStudioProxy as c, discoverWebSocketApis as ci, bridgeAgentCoreWs as cn, invokeTokenAuthorizer as cr, pickFunctionUrlLogicalIdFromOrigin as ct, createStudioDispatcher as d, parseSelectionExpressionPath as di, A2A_PATH as dn, buildCorsConfigByApiId as dr, pickTargetFunctionLogicalId as dt, CfnLocalStateProvider as ei, CloudMapRegistry as en, createJwksCache as er, buildEdgeRequestEvent as et, filterStudioCustomResources as f, webSocketApiMatchesIdentifier as fi, a2aInvokeOnce as fn, buildCorsConfigFromCloudFrontChain as fr, resolveCloudFrontDistribution as ft, annotatePinnedEcsTargets as g, AGENTCORE_A2A_PROTOCOL as gi, mcpInvokeOnce as gn, translateLambdaResponse as gr, stripCloudFrontImport as gt, annotateEcsTaskPinnedTargets as h, resolveLambdaArnIntrinsic as hi, MCP_PROTOCOL_VERSION as hn, matchRoute as hr, runViewerResponse as ht, coerceStopRequest as i, resolveSingleTarget as ii, getContainerNetworkIp as in, buildMethodArn as ir, CLOUDFRONT_DISTRIBUTION_TYPE as it, attachAgentCoreWsBridge as j, buildStsClientConfig as ji, addInvokeSpecificOptions as jn, buildMgmtEndpointEnvUrl as jr, createLocalRunTaskCommand as jt, selectServeInboundAuth as k, describeAwsFailureForWarn as ki, toCmdArgv as kn, bufferToBody as kr, serviceStrategy as kt, relayServeRequest as l, discoverWebSocketApisOrThrow as li, invokeAgentCoreWs as ln, attachAuthorizers as lr, pickKvsLogicalIdFromArn as lt, annotateAlbPinnedBackingServices as m, pickRefLogicalId as mi, MCP_PATH as mn, matchPreflight as mr, runViewerRequest as mt, coerceRunRequest as n, resolveSsmParameters as ni, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as nn, verifyJwtAuthorizer as nr, edgeHeadersToHttp as nt, resolveServeBaseUrl as o, listTargets as oi, addInvokeAgentCoreSpecificOptions as on, evaluateCachedLambdaPolicy as or, extractKvsAssociations as ot, isCustomResourceLambdaTarget as p, discoverRoutes as pi, MCP_CONTAINER_PORT as pn, isFunctionUrlOacFronted as pr, compileCloudFrontFunction as pt, matchBehavior as q, readMtlsMaterialsFromDisk as qn, LocalStateSourceError as qr, parseImageOverrideFlags as qt, coerceServeRequest as r, resolveWatchConfig as ri, setShadowReadyTimeoutMs as rn, verifyJwtViaDiscovery as rr, httpHeadersToEdge as rt, createStudioServeManager as s, availableWebSocketApiIdentifiers as si, createLocalInvokeAgentCoreCommand as sn, invokeRequestAuthorizer as sr, isCloudFrontDistribution as st, addStudioSpecificOptions as t, collectSsmParameterRefs as ti, DEFAULT_SHADOW_READY_TIMEOUT_MS as tn, verifyCognitoJwt as tr, buildEdgeResponseEvent as tt, reinvoke as u, filterWebSocketApisByIdentifiers as ui, A2A_CONTAINER_PORT as un, applyCorsResponseHeaders as ur, pickLambdaEdgeFunctionLogicalId as ut, startStudioServer as v, AGENTCORE_HTTP_PROTOCOL as vi, AGENTCORE_SIGV4_SERVICE as vn, buildHttpApiV2Event as vr, createLocalFileKvsDataSource as vt, createLocalListCommand as w, derivePseudoParametersFromRegion as wi, downloadAndExtractS3Bundle as wn, VtlEvaluationError as wr, resolveAlbTarget as wt, createStudioStore as x, AgentCoreResolutionError as xi, invokeAgentCore as xn, pickResponseTemplate as xr, albStrategy as xt, toStudioTargetGroups as y, AGENTCORE_MCP_PROTOCOL as yi, signAgentCoreInvocation as yn, buildRestV1Event as yr, createUnboundCloudFrontModule as yt, resolveCloudFrontTarget as z, attachStageContext as zn, resolveRuntimeCodeMountPath as zr, parseRestartPolicy as zt };
-//# sourceMappingURL=local-studio-BziOGWc5.js.map
+//# sourceMappingURL=local-studio-D8cHeCcp.js.map